diff --git a/README.md b/README.md
index 030df93d0f..e8db1875c3 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,16 @@
This repository contains the conceptual documentation for .NET Multi-platform App UI (MAUI). It's published at the [.NET MAUI documentation site](https://learn.microsoft.com/dotnet/maui).
+## LLMS Files
+
+This repo includes curated `llms.txt` files for AI-friendly documentation discovery.
+
+- Use [docs/llms.txt](docs/llms.txt) for top-level routing across the MAUI docs set.
+- Use subtopic `llms.txt` files when the question is scoped to one area such as fundamentals, user interface, platform integration, data, or deployment.
+- Use nested `llms.txt` files for higher-signal retrieval in busy areas such as data binding, Shell, controls, handlers, and CollectionView.
+- Use [docs/llms-full.txt](docs/llms-full.txt) only when a tool needs one broader context file and cannot follow subtopic links.
+- Validate changes with `./docs/tools/verify-llms.ps1`.
+
## Code of Conduct
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).
diff --git a/docs/data-cloud/llms.txt b/docs/data-cloud/llms.txt
new file mode 100644
index 0000000000..50dbdb20bf
--- /dev/null
+++ b/docs/data-cloud/llms.txt
@@ -0,0 +1,30 @@
+# .NET MAUI Data and Cloud
+
+> Data access patterns for MAUI apps, including REST services, local SQLite persistence, local development services, and push notifications.
+
+Use this index for app data flow between local storage and networked services.
+
+Use this file when the question is about API access, local persistence, backend connectivity, or how app state moves between on-device storage and remote systems.
+
+## Guidance for AI assistants
+
+- Prefer HttpClient-based REST patterns and DI-managed services for backend access.
+- Use SQLite when the app needs structured local relational storage.
+- Separate local development backend setup from production deployment guidance.
+- Treat push notifications as platform-aware integration work, not just a generic messaging feature.
+
+## Core data access
+
+- [Consume REST web services](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/rest.md): HttpClient patterns, serialization, and API integration.
+- [Local SQLite databases](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/database-sqlite.md): Local relational data storage with SQLite.
+- [Local web services](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/local-web-services.md): Configure local API backends for development.
+
+## Cloud and messaging
+
+- [Push notifications](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/push-notifications.md): Notification integration across platforms.
+- [Aspire integration](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/aspire-integration.md): Connect MAUI with .NET Aspire-based backends.
+
+## Optional
+
+- [Platform integration overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/index.md): Related device and platform APIs often used with data apps.
+- [Dependency injection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/dependency-injection.md): Service registration for repositories and API clients.
diff --git a/docs/deployment/llms.txt b/docs/deployment/llms.txt
new file mode 100644
index 0000000000..71fd11c8b0
--- /dev/null
+++ b/docs/deployment/llms.txt
@@ -0,0 +1,39 @@
+# .NET MAUI Deployment and Performance
+
+> Build, publish, trim, and optimize MAUI apps for Android, iOS, Mac Catalyst, and Windows.
+
+Use this index for shipping and performance hardening scenarios.
+
+Use this file when the question is about startup time, app size, trimming, AOT, test strategy, or packaging apps for stores and devices.
+
+## Guidance for AI assistants
+
+- Measure first when diagnosing performance; do not guess.
+- Treat compiled bindings, layout simplification, and correct control choice as the first performance levers.
+- Recommend trimming and Native AOT only when code and dependencies are compatible.
+- Verify publishing guidance against the target platform rather than assuming Android, iOS, and Windows behave the same way.
+
+## Performance and optimization
+
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): Actionable guidance for bindings, layouts, images, startup, threading, and memory.
+- [Improve app performance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance.md): Performance concepts and measurement strategy.
+- [Trimming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/trimming.md): Reduce app size by removing unused code.
+- [Native AOT](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/nativeaot.md): Ahead-of-time compilation guidance and tradeoffs.
+
+## Build, test, and release
+
+- [Deployment overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/index.md): Cross-platform release flow.
+- [Unit testing](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/unit-testing.md): Testing strategy for MAUI applications.
+- [Visual Studio project properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/visual-studio-properties.md): Configure packaging and target settings.
+
+## Platform publishing
+
+- [Android deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/android/deployment/index.md): Build and publish Android artifacts.
+- [iOS deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/ios/deployment/index.md): Build and publish for iOS and TestFlight/App Store.
+- [Mac Catalyst deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/mac-catalyst/deployment/index.md): Package and publish Mac Catalyst apps.
+- [Windows deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/windows/deployment/overview.md): Package and distribute Windows apps.
+
+## Optional
+
+- [Troubleshooting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/troubleshooting.md): Common issues across build and publish workflows.
+- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): Version support constraints that affect shipping decisions.
diff --git a/docs/deployment/performance-best-practices.md b/docs/deployment/performance-best-practices.md
new file mode 100644
index 0000000000..19d22cddf3
--- /dev/null
+++ b/docs/deployment/performance-best-practices.md
@@ -0,0 +1,562 @@
+---
+title: "Performance best practices for .NET MAUI"
+description: "A practical guide to building high-performance .NET MAUI apps — covering compiled bindings, layout optimization, control selection, image handling, async patterns, startup time, and deployment options."
+ms.date: 02/10/2026
+ms.topic: conceptual
+---
+
+# Performance best practices for .NET MAUI
+
+This guide covers the most impactful performance optimizations for .NET MAUI apps. Recommendations are ordered roughly by impact — start at the top.
+
+## 1. Compiled bindings
+
+This is the single biggest performance win in most MAUI apps.
+
+### The problem
+
+Reflection-based bindings resolve property paths at runtime using `System.Reflection`. This adds overhead on every property change notification, every binding evaluation, and every `DataTemplate` instantiation. In a list with hundreds of items, this cost compounds fast.
+
+### The fix
+
+Set `x:DataType` on your page and on every `DataTemplate`. This tells the XAML compiler to generate direct property access code at build time instead of using reflection, resulting in 8–20x faster binding resolution.
+
+```xaml
+
+
+
+
+```
+
+```xaml
+
+
+
+
+```
+
+Set `x:DataType` on `DataTemplate` elements too — they don't inherit it from the page:
+
+```xaml
+
+
+
+
+
+
+
+```
+
+In C#, use the expression-based `SetBinding` overload for compiled, type-safe bindings:
+
+```csharp
+// DO: Compiled, type-safe — no reflection
+label.SetBinding(Label.TextProperty, static (MainViewModel vm) => vm.UserName);
+
+// DON'T: String-based — uses reflection at runtime
+label.SetBinding(Label.TextProperty, "UserName");
+```
+
+### Don't bind static values
+
+If a value never changes and doesn't come from a view model, set it directly. Every binding — even a compiled one — has overhead compared to a direct property assignment.
+
+```xaml
+
+
+
+
+
+```
+
+## 2. Control selection
+
+Choosing the right control eliminates entire categories of performance problems.
+
+### Use Grid instead of nested StackLayouts
+
+Nested `StackLayout` controls cause exponential layout passes. A single `Grid` with defined rows and columns achieves the same visual result with one layout pass.
+
+```xaml
+
+
+
+
+
+
+
+
+```
+
+```xaml
+
+
+
+
+
+
+```
+
+### Use specific stack layouts
+
+`VerticalStackLayout` and `HorizontalStackLayout` are lighter than the general-purpose `StackLayout` because they skip the orientation check and have a simpler layout algorithm.
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+```
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+```
+
+### Border vs Frame
+
+`Frame` is obsolete. Use `Border`, which is lighter and more flexible.
+
+```xaml
+
+
+
+
+```
+
+```xaml
+
+
+
+
+```
+
+### CollectionView vs ListView vs BindableLayout
+
+| Control | Use when | Virtualizes | Notes |
+|---------|----------|:-----------:|-------|
+| `CollectionView` | More than 20 items | Yes | Recommended for all list scenarios |
+| `BindableLayout` | 20 items or fewer | No | Simpler, attach to any layout |
+| `ListView` | Never | Yes | Obsolete — migrate to `CollectionView` |
+
+> **Warning:** Never place a `CollectionView` or `ScrollView` inside a `StackLayout`. The `StackLayout` gives infinite space, which disables virtualization and creates the items all at once. Wrap them in a `Grid` instead.
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+```
+
+```xaml
+
+
+
+
+
+
+
+
+```
+
+### Background property vs BackgroundColor
+
+Prefer the `Background` property over the obsolete `BackgroundColor`:
+
+```csharp
+// DO
+view.Background = Colors.Red;
+
+// DON'T (obsolete)
+view.BackgroundColor = Colors.Red;
+```
+
+## 3. Layout optimization
+
+### Flatten the visual tree
+
+Every nested layout adds measurement and arrangement passes. Aim for the flattest possible hierarchy.
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+```xaml
+
+
+
+
+
+
+
+```
+
+### Remove single-child layouts
+
+A layout containing a single child is pure overhead.
+
+```xaml
+
+
+
+
+
+
+
+```
+
+### Hide vs Remove
+
+Use `IsVisible="false"` to exclude a view from layout. The view remains in the visual tree but skips measurement and rendering. This is cheaper than adding and removing views for items that toggle frequently.
+
+For items shown rarely (for example, an error banner), consider removing them from the tree entirely and adding them only when needed.
+
+```xaml
+
+
+```
+
+### Reduce the app resource dictionary
+
+App-level resources are checked for every control creation across the entire app. Move page-specific styles to page-level resource dictionaries to reduce lookup scope.
+
+```xaml
+
+
+
+
+```
+
+## 4. Image optimization
+
+Images are a common source of memory pressure and slow rendering. Follow these rules:
+
+- **Reference SVGs as PNG** — .NET MAUI converts SVGs to PNGs at build time. Always reference `.png` in your XAML even if the source file is `.svg`.
+- **Size images appropriately** — don't load a 4000×3000 image for a 60×60 thumbnail. Resize source images or constrain dimensions.
+- **Set explicit dimensions** — use `HeightRequest` and `WidthRequest` with an `Aspect` mode so the layout engine doesn't need to measure the decoded image.
+- **Keep list images small and consistent** — in `CollectionView` item templates, use fixed-size images to avoid layout recalculations during scrolling.
+- **Cache remote images** — for images loaded from URLs, use an image caching library to avoid re-downloading.
+
+```xaml
+
+
+```
+
+```xaml
+
+
+```
+
+## 5. Startup optimization
+
+### Use Shell
+
+`Shell` loads pages on demand — only the visible page is created at startup. `TabbedPage` creates all tab pages eagerly, increasing startup time proportionally to the number of tabs.
+
+```csharp
+// DO: Shell with route-based navigation
+public partial class AppShell : Shell
+{
+ public AppShell()
+ {
+ InitializeComponent();
+ Routing.RegisterRoute("details", typeof(DetailsPage));
+ }
+}
+```
+
+### Delay non-critical work
+
+Don't perform heavy initialization in the `App` constructor or `MainPage` constructor. Use the `OnAppearing` override or the `Loaded` event to defer work until the UI is visible.
+
+```csharp
+public MainPage()
+{
+ InitializeComponent();
+ // DON'T: Load data in the constructor — blocks startup
+}
+
+protected override async void OnAppearing()
+{
+ base.OnAppearing();
+ // DO: Load data when the page is about to appear
+ await viewModel.LoadDataAsync();
+}
+```
+
+### Minimize DI registrations at startup
+
+Only register services you actually need. Use `AddTransient` for lightweight, stateless services and `AddSingleton` for expensive-to-create or shared-state services.
+
+```csharp
+// DO: Register only what you need, with appropriate lifetimes
+builder.Services.AddSingleton();
+builder.Services.AddTransient();
+```
+
+### Consider Native AOT (iOS/Mac Catalyst)
+
+Native AOT compilation provides approximately 2x faster startup on iOS and approximately 1.2x faster startup on Mac Catalyst. It requires fully trim-compatible code — no dynamic reflection. See [Native AOT deployment](nativeaot.md) for setup instructions.
+
+## 6. Data binding performance
+
+### Binding modes matter
+
+Choose the cheapest binding mode that satisfies your requirements:
+
+| Mode | Cost | Use when |
+|------|------|----------|
+| `OneTime` | Cheapest | Data is set once and never changes |
+| `OneWay` | Low | Data updates from source to UI only (default) |
+| `TwoWay` | Highest | User can edit the value (`Entry`, `Switch`, `Slider`) |
+
+```xaml
+
+
+
+
+
+```
+
+```xaml
+
+
+
+
+
+```
+
+### Avoid complex binding paths
+
+Deep binding paths like `{Binding Parent.Child.GrandChild.Value}` require multiple property lookups and event subscriptions at every level. Flatten your view model instead.
+
+```csharp
+// DON'T: Deep property path
+// {Binding Order.Customer.Address.City}
+
+// DO: Flatten in the view model
+public string CustomerCity => Order.Customer.Address.City;
+```
+
+## 7. Async and threading
+
+### Use async/await correctly
+
+Always use `async`/`await` end to end. Never block on async code with `.Result` or `.Wait()` — this risks deadlocks and blocks the UI thread.
+
+```csharp
+// DO: Async all the way
+public async Task LoadDataAsync()
+{
+ var data = await _service.GetDataAsync();
+ Items = new ObservableCollection(data);
+}
+```
+
+```csharp
+// DON'T: Blocking on async — deadlock risk
+public void LoadData()
+{
+ var data = _service.GetDataAsync().Result; // Can deadlock!
+ Items = new ObservableCollection(data);
+}
+```
+
+### Use Task.WhenAll for independent operations
+
+When you have multiple independent async operations, run them concurrently instead of sequentially.
+
+```csharp
+// DO: Run independent operations in parallel
+await Task.WhenAll(
+ LoadUserAsync(),
+ LoadSettingsAsync(),
+ LoadNotificationsAsync()
+);
+
+// DON'T: Sequential when operations are independent
+await LoadUserAsync();
+await LoadSettingsAsync();
+await LoadNotificationsAsync();
+```
+
+### Thread safety
+
+UI controls can only be modified on the main thread. Use `IDispatcher` (via dependency injection) or `BindableObject.Dispatcher` to marshal calls back to the UI thread. `MainThread.BeginInvokeOnMainThread()` works as a fallback.
+
+```csharp
+// DO: Use the injected dispatcher for UI updates from background threads
+await dispatcher.DispatchAsync(() =>
+{
+ Items.Add(newItem);
+});
+```
+
+> **Warning:** Never update an `ObservableCollection` bound to a UI control from a background thread. This causes cross-thread access exceptions or silent data corruption.
+
+### Avoid async void
+
+Only use `async void` for event handlers. Every other async method should return `Task` or `Task` so callers can await it and exceptions propagate correctly.
+
+```csharp
+// DO: Return Task
+public async Task SaveAsync() { ... }
+
+// OK: async void for event handlers only
+private async void OnSaveClicked(object sender, EventArgs e)
+{
+ await SaveAsync();
+}
+
+// DON'T: async void for non-event-handler methods
+private async void Save() { ... } // Exceptions are swallowed
+```
+
+## 8. Memory management
+
+### Unsubscribe from events
+
+Event subscriptions keep objects alive. Always unsubscribe when a page disappears or a view model is no longer needed.
+
+```csharp
+protected override void OnAppearing()
+{
+ base.OnAppearing();
+ _service.DataChanged += OnDataChanged;
+}
+
+protected override void OnDisappearing()
+{
+ base.OnDisappearing();
+ _service.DataChanged -= OnDataChanged;
+}
+```
+
+### Use WeakEventManager for custom events
+
+If your class exposes events that external objects subscribe to, use `WeakEventManager` to avoid preventing garbage collection of subscribers.
+
+```csharp
+readonly WeakEventManager _eventManager = new();
+
+public event EventHandler DataChanged
+{
+ add => _eventManager.AddEventHandler(value);
+ remove => _eventManager.RemoveEventHandler(value);
+}
+
+protected void OnDataChanged()
+{
+ _eventManager.HandleEvent(this, EventArgs.Empty, nameof(DataChanged));
+}
+```
+
+### Dispose IDisposable resources
+
+Use `using` statements for short-lived resources. For view model–scoped resources, implement `IDisposable` and clean up when the page disappears or when the DI container disposes the service.
+
+```csharp
+// DO: using statement for short-lived resources
+using var stream = await FileSystem.OpenAppPackageFileAsync("data.json");
+using var reader = new StreamReader(stream);
+var content = await reader.ReadToEndAsync();
+```
+
+### Avoid strong circular references (iOS/Mac Catalyst)
+
+On Apple platforms, circular references between managed (.NET) objects and native (Objective-C/Swift) objects prevent garbage collection because both runtimes hold strong references. Use weak references to break cycles between views and their delegates or data sources.
+
+## 9. Trimming and AOT
+
+Trimming and ahead-of-time compilation reduce app size and improve startup time.
+
+| Option | Effect | Trade-off |
+|--------|--------|-----------|
+| Full trimming | Removes unused code, reducing app size | Code must be trim-compatible — no unchecked reflection |
+| Native AOT (iOS/Mac) | ~2x faster startup, ~2.5x smaller apps | Requires fully trim-compatible code |
+
+Enable full trimming in your project file:
+
+```xml
+
+ full
+
+```
+
+For Native AOT on iOS or Mac Catalyst:
+
+```xml
+
+ true
+
+```
+
+Both options require that your code and all dependencies are trim-compatible. Avoid patterns that rely on dynamic reflection, such as `Type.GetType()` with runtime strings or unanalyzable `Activator.CreateInstance` calls.
+
+For details, see [Trimming a .NET MAUI app](trimming.md) and [Native AOT deployment](nativeaot.md).
+
+## 10. Profiling
+
+You can't optimize what you can't measure. Use these approaches to find bottlenecks:
+
+- **Platform profilers** — Use Android Studio Profiler for Android, Xcode Instruments for iOS/Mac Catalyst, and Visual Studio Diagnostic Tools for Windows. These show CPU, memory, and rendering performance at the platform level.
+- **Profile on real devices** — Emulators and simulators don't reflect real-world performance. Always validate on physical hardware.
+- **Test on your lowest-spec target device** — Performance that's acceptable on a flagship phone might be unusable on a budget device.
+- **Use `Stopwatch` for quick timing** — For development-time checks, `Stopwatch` gives you fast, focused measurements without a full profiler.
+
+```csharp
+var sw = System.Diagnostics.Stopwatch.StartNew();
+await LoadDataAsync();
+sw.Stop();
+Debug.WriteLine($"LoadDataAsync took {sw.ElapsedMilliseconds}ms");
+```
+
+## See also
+
+- [Improve app performance](performance.md)
+- [Trimming a .NET MAUI app](trimming.md)
+- [Native AOT deployment](nativeaot.md)
+- [Compiled bindings](../fundamentals/data-binding/compiled-bindings.md)
diff --git a/docs/fundamentals/data-binding/llms.txt b/docs/fundamentals/data-binding/llms.txt
new file mode 100644
index 0000000000..2393e84211
--- /dev/null
+++ b/docs/fundamentals/data-binding/llms.txt
@@ -0,0 +1,37 @@
+# .NET MAUI Data Binding
+
+> Data binding in .NET MAUI: compiled bindings, binding modes, paths, converters, relative bindings, multibinding, and common troubleshooting patterns.
+
+Use this file when the problem is specifically about binding correctness, performance, or how values move between a view model and UI.
+
+## Guidance for AI assistants
+
+- Prefer compiled bindings with x:DataType whenever possible.
+- Suspect BindingContext or wrong data type first when bindings do not resolve.
+- Use TwoWay only for editable scenarios; do not default everything to TwoWay.
+- Keep bindings simple in item templates because binding complexity affects scrolling performance.
+
+## Core binding model
+
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): Highest-value guidance for compile-time validation and better performance.
+- [Data binding overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/index.md): End-to-end overview of MAUI binding concepts.
+- [Basic bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/basic-bindings.md): Bind properties in common page scenarios.
+- [Binding path](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/binding-path.md): Property path resolution and nested bindings.
+- [Binding mode](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/binding-mode.md): OneWay, TwoWay, OneTime, and related tradeoffs.
+
+## Commands and value transformation
+
+- [Commanding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/commanding.md): Bind UI actions to ICommand implementations.
+- [Value converters](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/converters.md): Transform values between source and target.
+- [String formatting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/string-formatting.md): Format bound values in the UI.
+
+## Advanced binding scenarios
+
+- [Relative bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/relative-bindings.md): Bind to ancestors, self, and templated parents.
+- [Multibinding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/multibinding.md): Combine multiple source values into one target.
+- [Binding fallbacks](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/binding-fallbacks.md): Handle missing or null values predictably.
+
+## Optional
+
+- [Data templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/datatemplate.md): Template lists and repeating data with bindings.
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Binding-heavy list UI and item-template behavior.
diff --git a/docs/fundamentals/llms.txt b/docs/fundamentals/llms.txt
new file mode 100644
index 0000000000..b7b5ac9516
--- /dev/null
+++ b/docs/fundamentals/llms.txt
@@ -0,0 +1,53 @@
+# .NET MAUI Fundamentals
+
+> Core MAUI concepts: app lifecycle, MVVM and binding, dependency injection, Shell navigation, resources, and localization.
+
+Use this index for architecture and everyday app-building decisions.
+
+Use this file when the question is about app structure, view models, navigation flow, binding behavior, or shared app-wide patterns rather than a specific control.
+
+## Guidance for AI assistants
+
+- Assume BindingContext and x:DataType issues first when bindings appear broken.
+- Use Shell for new navigation flows unless the app structure requires something else.
+- Put x:DataType on every page and every DataTemplate when showing binding examples.
+- Keep DI registration in MauiProgram and keep view logic out of code-behind when MVVM is intended.
+
+## Deep dive subtopics
+
+- [Data binding deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Binding modes, compiled bindings, converters, relative bindings, and troubleshooting.
+- [Shell deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/llms.txt): Route registration, tabs, flyout, lifecycle, and navigation behavior.
+
+## Data binding and MVVM
+
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): Use x:DataType for compile-time validation and significantly better performance.
+- [Data binding overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/index.md): Binding model, paths, modes, relative binding, and diagnostics.
+- [Commanding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/commanding.md): Bind user actions to view model logic.
+- [Value converters](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/converters.md): Adapt values between source and target.
+
+## App architecture
+
+- [Dependency injection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/dependency-injection.md): Register and resolve services, view models, and pages.
+- [App lifecycle](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/app-lifecycle.md): App and window lifecycle events.
+- [Bindable properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/bindable-properties.md): Build reusable controls with bindable APIs.
+- [Data templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/datatemplate.md): Template data items for collection-based UI.
+
+## Shell and navigation
+
+- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): Route registration, parameters, and navigation patterns.
+- [Shell overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/index.md): App structure using routes, flyout, and tabs.
+- [Shell tabs](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/tabs.md): Top and bottom tab organization.
+- [Shell flyout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/flyout.md): App menu behavior and customization.
+
+## Resources and UX foundations
+
+- [Resource dictionaries](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/resource-dictionaries.md): Shared styles, colors, templates, and visual resources.
+- [Localization](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/localization.md): Localize strings and assets.
+- [Accessibility](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/accessibility.md): Build accessible controls and flows.
+- [Single project](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/single-project.md): Platform assets and source layout.
+
+## Optional
+
+- [Behaviors](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/behaviors.md): Reusable interaction logic for controls.
+- [Triggers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/triggers.md): Conditional UI behavior.
+- [Control templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/controltemplate.md): Re-template control visuals while preserving behavior.
diff --git a/docs/fundamentals/shell/llms.txt b/docs/fundamentals/shell/llms.txt
new file mode 100644
index 0000000000..c084d735b1
--- /dev/null
+++ b/docs/fundamentals/shell/llms.txt
@@ -0,0 +1,34 @@
+# .NET MAUI Shell
+
+> Shell in .NET MAUI: route-based navigation, flyout and tabs, page hierarchy, lifecycle, and common Shell app structure decisions.
+
+Use this file when the question is specifically about Shell behavior, route registration, page flow, query parameters, or app-level navigation structure.
+
+## Guidance for AI assistants
+
+- Treat Shell as the default navigation model for new MAUI apps.
+- Register routes explicitly when navigating to detail pages outside the visual hierarchy.
+- Use Shell query parameters for simple navigation state; move to stronger patterns if state becomes complex.
+- Do not mix Shell with NavigationPage, TabbedPage, or FlyoutPage as peer app structures unless the docs explicitly require it.
+
+## Core Shell architecture
+
+- [Shell overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/index.md): App structure, route model, and key Shell concepts.
+- [Create a Shell app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/create.md): Build the initial Shell hierarchy.
+- [Shell pages](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/pages.md): Configure page hierarchy and content presentation.
+
+## Navigation and state
+
+- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): Route registration, URI navigation, back navigation, and parameters.
+- [Shell lifecycle](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/lifecycle.md): Page and navigation lifecycle behavior in Shell apps.
+- [Shell search](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/search.md): Add search UI and query behavior.
+
+## Flyout and tabs
+
+- [Shell tabs](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/tabs.md): Top tabs, bottom tabs, and organization of tabbed navigation.
+- [Shell flyout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/flyout.md): Flyout layout, items, header, footer, and behavior.
+
+## Optional
+
+- [App lifecycle](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/app-lifecycle.md): Broader app lifecycle behavior around Shell-hosted UI.
+- [Dependency injection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/dependency-injection.md): Resolve pages and view models used in Shell navigation flows.
diff --git a/docs/get-started/llms.txt b/docs/get-started/llms.txt
new file mode 100644
index 0000000000..b0700f31d9
--- /dev/null
+++ b/docs/get-started/llms.txt
@@ -0,0 +1,30 @@
+# .NET MAUI Getting Started
+
+> Start here for setup, first app flow, and core prerequisites for .NET MAUI development on Windows and Mac.
+
+Use this index when a user is new to MAUI or blocked on environment setup.
+
+Use this before deeper troubleshooting when the real problem may still be installation, workload, emulator, SDK, or supported-platform mismatch.
+
+## Guidance for AI assistants
+
+- Verify the user's IDE, SDK, and target platform before debugging app code.
+- Check supported-platform requirements before recommending packages, APIs, or deployment steps.
+- Treat installation and environment issues separately from runtime or XAML issues.
+
+## Core onboarding
+
+- [Installation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/installation.md): Install workloads, IDE tools, and required platform dependencies.
+- [Build your first app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/first-app.md): End-to-end first app walkthrough.
+- [What is .NET MAUI](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/what-is-maui.md): Framework architecture and app model.
+- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): OS and SDK support matrix.
+
+## Setup and troubleshooting
+
+- [Resources for beginners](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/resources.md): Learning resources and next learning paths.
+- [Troubleshooting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/troubleshooting.md): Common build, workload, emulator, device, and tooling issues.
+
+## Optional
+
+- [Single project architecture](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/single-project.md): Understand the MAUI single project structure.
+- [Visual Studio project properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/visual-studio-properties.md): IDE project settings for targets and packaging.
diff --git a/docs/llms-full.txt b/docs/llms-full.txt
new file mode 100644
index 0000000000..3d1fd7cc13
--- /dev/null
+++ b/docs/llms-full.txt
@@ -0,0 +1,405 @@
+# .NET MAUI Documentation
+
+> .NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for building native mobile and desktop apps using C# and XAML from a shared codebase.
+
+This expanded llms context file aggregates the root, subtopic, and nested llms indexes into one document for tools that need broader retrieval context.
+
+Prefer a smaller llms file when the question is isolated to one area. Use this file when the question spans multiple MAUI areas such as navigation plus bindings plus controls, or when the consuming tool cannot recursively follow subtopic links.
+
+## Routing guide
+
+- Use the root file for multi-area routing.
+- Use a subtopic file when the question stays within one major area.
+- Use a nested deep-dive file when the question is about one dense topic such as CollectionView, layouts, data binding, Shell, app model, or storage.
+- Use this expanded file when the consumer cannot follow subtopic links or the question spans several MAUI areas at once.
+
+## Included indexes
+
+- [Root index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/llms.txt): Compact top-level navigator for the MAUI docs set.
+- [Getting started](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/llms.txt): Setup, first app, prerequisites, and environment issues.
+- [Fundamentals](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/llms.txt): Architecture, MVVM, Shell, lifecycle, resources.
+- [Data binding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Binding correctness, modes, converters, and performance.
+- [Shell](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/llms.txt): Route-based navigation and app structure.
+- [User interface](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/llms.txt): Controls, layouts, handlers, styles, and theming.
+- [Controls](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Control choice, list behavior, and obsolete control replacements.
+- [CollectionView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): CollectionView-specific data, layout, grouping, selection, and scrolling guidance.
+- [Layouts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/llms.txt): Layout choice, scrolling constraints, responsiveness, and performance.
+- [Handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/llms.txt): Native control customization and custom controls.
+- [Platform integration](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/llms.txt): Permissions, storage, sensors, networking, and auth.
+- [App model](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/llms.txt): Permissions, main thread, launcher, browser, and app metadata.
+- [Storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/llms.txt): File picker, app directories, preferences, and secure storage.
+- [Communication](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/llms.txt): Networking, web authenticator, email, SMS, phone dialer, and contacts.
+- [XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/llms.txt): XAML syntax, namespaces, markup extensions, compilation, and source generation.
+- [What's new](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/llms.txt): .NET 10 and .NET 11 changes, deprecations, and migration guidance.
+- [Data and cloud](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/llms.txt): REST, SQLite, push notifications, and Aspire.
+- [Deployment and performance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/llms.txt): Publish, performance, trimming, Native AOT, and release guidance.
+
+## Root index
+
+Use the root file to route to the right area first. Use a subtopic llms file when the question is implementation-specific and you want higher signal with less unrelated context.
+
+### Guidance for AI assistants
+
+- Prefer .NET MAUI patterns over Xamarin.Forms-era guidance.
+- Use CollectionView instead of ListView for new list UI.
+- Use Border instead of Frame for new container UI.
+- Use handlers for control customization instead of custom renderers or effects.
+- Use compiled bindings with x:DataType on pages and DataTemplate instances.
+- Keep platform-specific code in platform integration patterns, not scattered in shared UI logic.
+- Treat Shell as the default app structure unless the scenario explicitly requires another navigation model.
+- Prefer markdown subtopic indexes over the full context file unless broad cross-area context is required.
+
+### Start here
+
+- [What is .NET MAUI](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/what-is-maui.md): Framework overview and architecture.
+- [Installation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/installation.md): Setup and prerequisites.
+- [Build your first app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/first-app.md): End-to-end starter app.
+- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): Platform and OS support matrix.
+
+### High-value implementation guides
+
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): First stop for slow UI, startup issues, layout thrash, and binding overhead.
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): First stop for list UI, virtualization, scrolling, grouping, and selection behavior.
+- [Handler architecture guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): First stop for native control customization and renderer migration.
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): First stop for binding correctness and performance problems.
+- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): First stop for route-based navigation, query parameters, and page flow.
+
+## Getting started index
+
+Use this before deeper troubleshooting when the real problem may still be installation, workload, emulator, SDK, or supported-platform mismatch.
+
+### Guidance for AI assistants
+
+- Verify the user's IDE, SDK, and target platform before debugging app code.
+- Check supported-platform requirements before recommending packages, APIs, or deployment steps.
+- Treat installation and environment issues separately from runtime or XAML issues.
+
+### Core onboarding
+
+- [Installation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/installation.md): Install workloads, IDE tools, and required platform dependencies.
+- [Build your first app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/first-app.md): End-to-end first app walkthrough.
+- [What is .NET MAUI](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/what-is-maui.md): Framework architecture and app model.
+- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): OS and SDK support matrix.
+
+## Fundamentals index
+
+Use this file when the question is about app structure, view models, navigation flow, binding behavior, or shared app-wide patterns rather than a specific control.
+
+### Guidance for AI assistants
+
+- Assume BindingContext and x:DataType issues first when bindings appear broken.
+- Use Shell for new navigation flows unless the app structure requires something else.
+- Put x:DataType on every page and every DataTemplate when showing binding examples.
+- Keep DI registration in MauiProgram and keep view logic out of code-behind when MVVM is intended.
+
+### Deep dive subtopics
+
+- [Data binding deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Binding modes, compiled bindings, converters, relative bindings, and troubleshooting.
+- [Shell deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/llms.txt): Route registration, tabs, flyout, lifecycle, and navigation behavior.
+
+### App architecture
+
+- [Dependency injection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/dependency-injection.md): Register and resolve services, view models, and pages.
+- [App lifecycle](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/app-lifecycle.md): App and window lifecycle events.
+- [Bindable properties](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/bindable-properties.md): Build reusable controls with bindable APIs.
+- [Data templates](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/datatemplate.md): Template data items for collection-based UI.
+
+## Data binding index
+
+### Guidance for AI assistants
+
+- Prefer compiled bindings with x:DataType whenever possible.
+- Suspect BindingContext or wrong data type first when bindings do not resolve.
+- Use TwoWay only for editable scenarios; do not default everything to TwoWay.
+- Keep bindings simple in item templates because binding complexity affects scrolling performance.
+
+### Core binding model
+
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): Highest-value guidance for compile-time validation and better performance.
+- [Data binding overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/index.md): End-to-end overview of MAUI binding concepts.
+- [Binding mode](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/binding-mode.md): OneWay, TwoWay, OneTime, and related tradeoffs.
+- [Relative bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/relative-bindings.md): Bind to ancestors, self, and templated parents.
+
+## Shell index
+
+### Guidance for AI assistants
+
+- Treat Shell as the default navigation model for new MAUI apps.
+- Register routes explicitly when navigating to detail pages outside the visual hierarchy.
+- Use Shell query parameters for simple navigation state; move to stronger patterns if state becomes complex.
+- Do not mix Shell with NavigationPage, TabbedPage, or FlyoutPage as peer app structures unless the docs explicitly require it.
+
+### Core Shell architecture
+
+- [Shell overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/index.md): App structure, route model, and key Shell concepts.
+- [Create a Shell app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/create.md): Build the initial Shell hierarchy.
+- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): Route registration, URI navigation, back navigation, and parameters.
+- [Shell tabs](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/tabs.md): Top tabs, bottom tabs, and organization of tabbed navigation.
+- [Shell flyout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/flyout.md): Flyout layout, items, header, footer, and behavior.
+
+## User interface index
+
+Use this file when the question is about choosing controls, fixing layout behavior, improving scrolling performance, styling visuals, or customizing native UI behavior.
+
+### Guidance for AI assistants
+
+- Prefer CollectionView over ListView for new list UI.
+- Prefer Border over Frame for new container UI.
+- Prefer Grid over deeply nested StackLayout trees for non-trivial layout.
+- Do not place CollectionView or ScrollView inside StackLayout when constrained scrolling or virtualization matters.
+- Use handlers for control customization; do not recommend effects or custom renderers for new code.
+
+### Deep dive subtopics
+
+- [Controls deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Control selection, list behavior, input, web, and obsolete control replacements.
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): CollectionView data, layout, selection, grouping, empty views, and scrolling.
+- [Layouts deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/llms.txt): Grid, stack layouts, FlexLayout, BindableLayout, and layout performance tradeoffs.
+- [Handlers deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/llms.txt): Handler lifecycle, customization, and custom control creation.
+
+### Layout and visual structure
+
+- [Grid](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/grid.md): Preferred layout for complex UI.
+- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Select the right layout container for sizing, scrolling, and responsiveness.
+- [BindableLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/bindablelayout.md): Simple item rendering without virtualization.
+- [Styles](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/styles/xaml.md): Centralized style definitions.
+- [Theming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/theming.md): Light and dark theme support.
+
+## Controls index
+
+### Guidance for AI assistants
+
+- Prefer CollectionView over ListView for new list UI.
+- Prefer Border over Frame for new container UI.
+- Do not use ViewCell inside CollectionView templates.
+- Constrain image size explicitly in scrolling or templated UI when performance matters.
+- Use RefreshView or SwipeView as companion controls around list content when appropriate.
+
+### Deep dive subtopics
+
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): Narrow retrieval for CollectionView behavior, templates, layout, selection, grouping, and scrolling.
+
+### Lists and item presentation
+
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Highest-value guide for list UI, virtualization, grouping, empty views, and selection.
+- [Populate CollectionView data](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/populate-data.md): Bind data sources and item templates.
+- [CollectionView layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/layout.md): List and grid layout options.
+- [CollectionView selection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/selection.md): Single and multiple selection behavior.
+- [CollectionView scrolling](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/scrolling.md): Scroll behavior, snapping, and scrolling APIs.
+
+### Obsolete or avoid-for-new-work
+
+- [ListView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/listview.md): Older list control; use CollectionView for new work.
+- [Frame](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/frame.md): Older container; use Border for new work.
+- [TableView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/tableview.md): Older settings-form style control with narrower modern use.
+
+## CollectionView index
+
+### Guidance for AI assistants
+
+- Use CollectionView for new list UI instead of ListView.
+- Do not place CollectionView inside StackLayout or VerticalStackLayout when constrained scrolling or virtualization matters.
+- Do not use ViewCell in CollectionView templates.
+- Use compiled bindings and simple visual trees in item templates when performance matters.
+- Use BindableLayout instead of CollectionView only when the item count is small and virtualization is unnecessary.
+
+### Core CollectionView guidance
+
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Highest-value guide covering data, templates, layout, selection, grouping, empty views, scrolling, and performance.
+- [CollectionView overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/index.md): Core CollectionView concepts.
+- [Populate CollectionView data](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/populate-data.md): ItemsSource, templates, selectors, refresh, and incremental loading.
+- [CollectionView layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/layout.md): Vertical lists, horizontal lists, and grids.
+- [CollectionView selection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/selection.md): Selection modes and selection change handling.
+- [CollectionView grouping](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/grouping.md): Group headers, grouped sources, and grouped templates.
+- [CollectionView empty views](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/emptyview.md): Empty-state presentation.
+- [CollectionView scrolling](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/scrolling.md): ScrollTo, snap points, and update-scroll behavior.
+
+## Layouts index
+
+### Guidance for AI assistants
+
+- Prefer Grid over deeply nested StackLayout trees for non-trivial layouts.
+- Prefer VerticalStackLayout or HorizontalStackLayout over StackLayout when the layout direction is fixed.
+- Do not place CollectionView or ScrollView inside StackLayout when constrained scrolling or virtualization matters.
+- Use BindableLayout only for small collections where virtualization is unnecessary.
+- Treat layout simplification as a primary performance lever in MAUI UI.
+
+### Core layout guidance
+
+- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Choose the right layout container for structure, alignment, and responsiveness.
+- [Grid](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/grid.md): Preferred layout for complex UI, rows and columns, and responsive structure.
+- [VerticalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/verticalstacklayout.md): Lightweight vertical stacking.
+- [HorizontalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/horizontalstacklayout.md): Lightweight horizontal stacking.
+- [FlexLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/flexlayout.md): Flexible wrapping and adaptive item arrangement.
+- [AbsoluteLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/absolutelayout.md): Position items with explicit bounds when required.
+- [BindableLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/bindablelayout.md): Small-item data rendering without CollectionView.
+
+## Handlers index
+
+### Guidance for AI assistants
+
+- Use handlers instead of Xamarin.Forms renderers or effects for new code.
+- Reach for AppendToMapping, PrependToMapping, or ModifyMapping before inventing a custom handler.
+- Remember handler customizations are global unless scoped to a subclassed control.
+- Access PlatformView only after the handler lifecycle makes it available.
+
+### Core handler model
+
+- [Handler architecture guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): Most complete guide to handler concepts, lifecycle, and customization.
+- [Handlers overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/index.md): High-level model for virtual view to native view mapping.
+- [Customize controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/customize.md): Append, prepend, and modify existing mappings.
+- [Create controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/create.md): Define custom controls with platform-specific native implementations.
+
+## Platform integration index
+
+### Guidance for AI assistants
+
+- Prefer MAUI platform integration APIs before recommending custom native interop.
+- Request or verify permissions before using device capabilities that require them.
+- Use MainThread or Dispatcher when a device callback updates bound UI state.
+- Keep platform-specific code behind partial classes, handlers, or targeted platform integration patterns.
+
+### Deep dive subtopics
+
+- [App model deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/llms.txt): Permissions, main thread, launcher, browser, app metadata, and version tracking.
+- [Storage deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/llms.txt): File picker, app directories, preferences, and secure storage.
+
+### App model and permissions
+
+- [Invoke platform code](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/invoke-platform-code.md): Multi-targeting, partial classes, and per-platform implementations.
+- [Permissions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/permissions.md): Request and verify runtime permissions.
+- [Main thread](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/main-thread.md): Marshal work to the UI thread.
+- [File picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-picker.md): User file selection.
+- [Networking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/networking.md): Connectivity state, connection changes, and network access.
+
+## App model index
+
+### Guidance for AI assistants
+
+- Check permissions before using app model features that require user consent or platform declarations.
+- Use MainThread or Dispatcher when app model callbacks update UI state.
+- Prefer built-in launcher and browser APIs before recommending custom platform code.
+- Keep app metadata and version queries in shared code only when MAUI already exposes the required API.
+
+### Core app model guidance
+
+- [Permissions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/permissions.md): Request and verify runtime permissions.
+- [Main thread](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/main-thread.md): Marshal work to the UI thread.
+- [Open browser](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/open-browser.md): Launch browser links.
+- [Launcher](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/launcher.md): Launch URIs and other apps.
+- [App information](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/app-information.md): App metadata and package information.
+- [Version tracking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/version-tracking.md): Detect first launch and version changes.
+- [App actions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/app-actions.md): Expose app shortcuts and quick actions.
+
+## Storage index
+
+### Guidance for AI assistants
+
+- Use app directories and helpers for app-owned files before reaching for custom absolute paths.
+- Use preferences for simple local settings and secure storage for secrets or tokens.
+- Use file picker only when the user must choose external files.
+- Distinguish local app storage from user-selected or shared external files.
+
+### Core storage guidance
+
+- [File picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-picker.md): User file selection.
+- [File system helpers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-system-helpers.md): App directories and file access.
+- [Preferences](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/preferences.md): Local key-value app settings.
+- [Secure storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/secure-storage.md): Encrypted key-value data.
+
+## Data and cloud index
+
+### Guidance for AI assistants
+
+- Prefer HttpClient-based REST patterns and DI-managed services for backend access.
+- Use SQLite when the app needs structured local relational storage.
+- Separate local development backend setup from production deployment guidance.
+- Treat push notifications as platform-aware integration work, not just a generic messaging feature.
+
+### Core data access
+
+- [Consume REST web services](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/rest.md): HttpClient patterns, serialization, and API integration.
+- [Local SQLite databases](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/database-sqlite.md): Local relational data storage with SQLite.
+- [Local web services](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/local-web-services.md): Configure local API backends for development.
+- [Push notifications](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/push-notifications.md): Notification integration across platforms.
+- [Aspire integration](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/aspire-integration.md): Connect MAUI with .NET Aspire-based backends.
+
+## Deployment and performance index
+
+### Guidance for AI assistants
+
+- Measure first when diagnosing performance; do not guess.
+- Treat compiled bindings, layout simplification, and correct control choice as the first performance levers.
+- Recommend trimming and Native AOT only when code and dependencies are compatible.
+- Verify publishing guidance against the target platform rather than assuming Android, iOS, and Windows behave the same way.
+
+### Performance and optimization
+
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): Actionable guidance for bindings, layouts, images, startup, threading, and memory.
+- [Improve app performance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance.md): Performance concepts and measurement strategy.
+- [Trimming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/trimming.md): Reduce app size by removing unused code.
+- [Native AOT](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/nativeaot.md): Ahead-of-time compilation guidance and tradeoffs.
+- [Android deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/android/deployment/index.md): Build and publish Android artifacts.
+- [iOS deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/ios/deployment/index.md): Build and publish for iOS and TestFlight/App Store.
+- [Windows deployment](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/windows/deployment/overview.md): Package and distribute Windows apps.
+
+## Communication index
+
+### Guidance for AI assistants
+
+- Check network connectivity before making remote calls; handle offline states gracefully.
+- Web authenticator handles browser-based OAuth/OIDC flows; don't implement custom browser redirects.
+- Email, SMS, and phone dialer open native OS apps — check IsComposeSupported or IsSupported before calling.
+- Contacts access requires the ContactsRead permission; check and request it before reading.
+- Keep communication calls off the UI thread; marshal results back via MainThread or Dispatcher.
+
+### Core communication guidance
+
+- [Networking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/networking.md): Connectivity state, connection type, and network access change events.
+- [Web authenticator](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/authentication.md): Browser-based OAuth and OIDC flows with secure redirect handling.
+- [Email](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/email.md): Compose email via native mail apps with recipients, subject, and body.
+- [SMS](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/sms.md): Compose SMS messages via native messaging apps.
+- [Phone dialer](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/phone-dialer.md): Open the native phone dialer with a pre-filled number.
+- [Contacts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/contacts.md): Read device contacts with permission.
+
+## XAML index
+
+### Guidance for AI assistants
+
+- Always declare x:DataType on data templates and binding-heavy pages to enable compiled bindings.
+- Use StaticResource for resources in a ResourceDictionary; use DynamicResource only when the value changes at runtime.
+- XAML source generation (MauiXamlInflator=SourceGen) is the recommended path in .NET 10 — significantly faster Debug inflation.
+- Don't use XamlCompilation attributes to disable compilation; fix the underlying XAML errors instead.
+- Namespace declarations at the root element are inherited by all child elements — declare shared namespaces once.
+
+### XAML fundamentals
+
+- [XAML overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/index.md): XAML basics, property elements, attached properties, and when to use XAML vs code.
+- [Essential XAML syntax](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/essential-syntax.md): Property elements, attached properties, and syntax patterns.
+- [XAML markup extensions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/markup-extensions/consume.md): StaticResource, DynamicResource, Binding, RelativeSource, and x:Static.
+- [Pass arguments in XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/pass-arguments.md): x:Arguments and x:FactoryMethod for non-default constructors.
+
+### Namespaces and compilation
+
+- [XAML namespaces](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/namespaces/index.md): Default namespace, x: prefix, clr-namespace declarations, and x:DataType.
+- [XAML compilation and source generation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/xamlc.md): XamlC, XAML source generation (SourceGen), and per-file inflator control.
+- [XAML hot reload](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/hot-reload.md): Live UI editing during debug sessions.
+
+## What's new index
+
+### Guidance for AI assistants
+
+- For .NET 10 projects: use DisplayAlertAsync and DisplayActionSheetAsync, not the non-Async variants.
+- ClickGestureRecognizer is removed in .NET 10 — use TapGestureRecognizer.
+- ListView, TableView, and their cell types are deprecated — use CollectionView.
+- Frame is deprecated — use Border.
+- MessagingCenter is internal in .NET 10 — recommend WeakReferenceMessenger from CommunityToolkit.Mvvm.
+- Animation methods (FadeTo, RotateTo, etc.) are deprecated — use the Async variants.
+
+### .NET 10 changes
+
+- [What's new in .NET MAUI for .NET 10](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-10.md): Full list of new APIs, deprecations, and breaking changes.
+
+### .NET 9 and earlier
+
+- [What's new in .NET MAUI for .NET 9](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-9.md): New controls and APIs in .NET 9.
+- [What's new in .NET MAUI for .NET 8](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-8.md): New controls and APIs in .NET 8.
diff --git a/docs/llms.txt b/docs/llms.txt
new file mode 100644
index 0000000000..99ca01f6fa
--- /dev/null
+++ b/docs/llms.txt
@@ -0,0 +1,71 @@
+# .NET MAUI Documentation
+
+> .NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for building native mobile and desktop apps using C# and XAML from a shared codebase.
+
+This root llms index is intentionally compact. Use the subtopic llms indexes for deeper coverage.
+
+Use the root file to route to the right area first. Use a subtopic llms file when the question is implementation-specific and you want higher signal with less unrelated context.
+
+## Routing guide
+
+- Use the root file when the question spans multiple MAUI areas.
+- Use a subtopic file when the question stays within one area such as fundamentals, user interface, XAML, platform integration, data, or deployment.
+- Use a nested deep-dive file when the question is about one busy topic such as data binding, Shell, controls, CollectionView, handlers, layouts, app model, storage, or communication.
+- Use llms-full only when the consuming tool cannot follow subtopic links or when the question needs broad cross-area context.
+
+## Guidance for AI assistants
+
+- Prefer .NET MAUI patterns over Xamarin.Forms-era guidance.
+- Use CollectionView instead of ListView for new list UI.
+- Use Border instead of Frame for new container UI.
+- Use handlers for control customization instead of custom renderers or effects.
+- Use compiled bindings with x:DataType on pages and DataTemplate instances.
+- Keep platform-specific code in platform integration patterns, not scattered in shared UI logic.
+- Treat Shell as the default app structure unless the scenario explicitly requires another navigation model.
+- Prefer markdown subtopic indexes over the full context file unless broad cross-area context is required.
+
+## Start here
+
+- [What is .NET MAUI](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/what-is-maui.md): Framework overview and architecture.
+- [Installation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/installation.md): Setup and prerequisites.
+- [Build your first app](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/first-app.md): End-to-end starter app.
+- [Supported platforms](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/supported-platforms.md): Platform and OS support matrix.
+
+## High-value implementation guides
+
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): First stop for slow UI, startup issues, layout thrash, and binding overhead.
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): First stop for list UI, virtualization, scrolling, grouping, and selection behavior.
+- [Handler architecture guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): First stop for native control customization and renderer migration.
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): First stop for binding correctness and performance problems.
+- [Shell navigation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/navigation.md): First stop for route-based navigation, query parameters, and page flow.
+
+## Subtopics
+
+- [Getting started](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/get-started/llms.txt): Setup and first app onboarding.
+- [Fundamentals](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/llms.txt): Architecture, MVVM, Shell, lifecycle, resources.
+- [User interface](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/llms.txt): Controls, layouts, handlers, styles, theming.
+- [XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/llms.txt): XAML syntax, namespaces, markup extensions, compilation, and source generation.
+- [Platform integration](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/llms.txt): Permissions, storage, sensors, networking, auth.
+- [Data and cloud](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/llms.txt): REST, SQLite, push notifications, Aspire.
+- [Deployment and performance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/llms.txt): Publish, trimming, Native AOT, optimization.
+- [What's new](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/llms.txt): .NET 10 and .NET 11 changes, deprecations, and migration guidance.
+
+## Nested deep dives
+
+- [Data binding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Narrow binding-specific retrieval with less unrelated architecture context.
+- [Shell](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/shell/llms.txt): Narrow routing and app-structure retrieval.
+- [Controls](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Narrow control-selection and list-UI retrieval.
+- [CollectionView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): Narrow list virtualization, grouping, selection, empty view, and scrolling retrieval.
+- [Layouts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/llms.txt): Narrow layout-choice, responsiveness, scrolling, and visual-tree performance retrieval.
+- [Handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/llms.txt): Narrow handler customization and native-view retrieval.
+- [App model](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/llms.txt): Narrow permissions, launcher, browser, main-thread, and app metadata retrieval.
+- [Storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/llms.txt): Narrow file picker, app directories, preferences, and secure storage retrieval.
+- [Communication](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/llms.txt): Narrow networking, web auth, email, SMS, phone dialer, and contacts retrieval.
+
+## Related references
+
+- [Troubleshooting](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/troubleshooting.md): Common issues and resolutions.
+
+## Optional
+
+- [Full llms context file](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/llms-full.txt): Expanded context file that aggregates the root, subtopic, and nested llms indexes.
diff --git a/docs/platform-integration/appmodel/llms.txt b/docs/platform-integration/appmodel/llms.txt
new file mode 100644
index 0000000000..add68a3384
--- /dev/null
+++ b/docs/platform-integration/appmodel/llms.txt
@@ -0,0 +1,27 @@
+# .NET MAUI App Model
+
+> App model APIs in .NET MAUI: permissions, main-thread access, launcher, browser launch, app metadata, app actions, and version tracking.
+
+Use this file when the question is specifically about app model APIs rather than storage, sensors, or broader platform integration.
+
+## Guidance for AI assistants
+
+- Check permissions before using app model features that require user consent or platform declarations.
+- Use MainThread or Dispatcher when app model callbacks update UI state.
+- Prefer built-in launcher and browser APIs before recommending custom platform code.
+- Keep app metadata and version queries in shared code only when MAUI already exposes the required API.
+
+## Core app model guidance
+
+- [Permissions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/permissions.md): Request and verify runtime permissions.
+- [Main thread](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/main-thread.md): Marshal work to the UI thread.
+- [Open browser](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/open-browser.md): Launch browser links.
+- [Launcher](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/launcher.md): Launch URIs and other apps.
+- [App information](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/app-information.md): App metadata and package information.
+- [Version tracking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/version-tracking.md): Detect first launch and version changes.
+- [App actions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/app-actions.md): Expose app shortcuts and quick actions.
+
+## Optional
+
+- [Invoke platform code](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/invoke-platform-code.md): Broader platform-specific patterns when built-in app model APIs are insufficient.
+- [Platform integration index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/llms.txt): Broader platform integration retrieval.
diff --git a/docs/platform-integration/communication/llms.txt b/docs/platform-integration/communication/llms.txt
new file mode 100644
index 0000000000..7cc6b8c964
--- /dev/null
+++ b/docs/platform-integration/communication/llms.txt
@@ -0,0 +1,27 @@
+# .NET MAUI Communication
+
+> Communication APIs in .NET MAUI: network connectivity, web authentication, email, SMS, phone dialer, contacts, and browser launch.
+
+Use this file when the question is about checking network access, performing browser-based OAuth flows, composing email or SMS, dialing phone numbers, or reading device contacts.
+
+## Guidance for AI assistants
+
+- Check network connectivity before making remote calls; handle offline states gracefully.
+- Use `WebAuthenticator` for browser-based OAuth and OIDC flows; do not implement custom browser redirect handling.
+- Check `IsComposeSupported` or `IsSupported` before calling email, SMS, or phone dialer — these open native OS apps and may not be available on all platforms.
+- Request the `ContactsRead` permission and verify it before attempting to read device contacts.
+- Keep communication calls off the UI thread; marshal results back via `MainThread.BeginInvokeOnMainThread` or `Dispatcher`.
+
+## Core communication guidance
+
+- [Networking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/networking.md): Connectivity state, connection type, and network access change events.
+- [Web authenticator](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/authentication.md): Browser-based OAuth and OIDC flows with secure redirect handling.
+- [Open browser](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/open-browser.md): Launch a URL in the system browser for non-auth navigation.
+- [Email](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/email.md): Compose email via native mail apps with recipients, subject, and body.
+- [SMS](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/sms.md): Compose SMS messages via native messaging apps.
+- [Phone dialer](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/phone-dialer.md): Open the native phone dialer with a pre-filled number.
+- [Contacts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/contacts.md): Read device contacts with permission.
+
+## Optional
+
+- [Platform integration index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/llms.txt): Broader platform integration retrieval.
diff --git a/docs/platform-integration/llms.txt b/docs/platform-integration/llms.txt
new file mode 100644
index 0000000000..ef7a6ee149
--- /dev/null
+++ b/docs/platform-integration/llms.txt
@@ -0,0 +1,53 @@
+# .NET MAUI Platform Integration
+
+> Access device capabilities and platform-specific APIs: permissions, storage, sensors, networking, authentication, and native integration.
+
+Use this file for code that crosses the boundary between shared MAUI code and platform behavior. It is the right entry point when the question is about permissions, device APIs, storage locations, browser and auth flows, or how to keep platform-specific behavior out of shared UI code.
+
+## Guidance for AI assistants
+
+- Prefer MAUI platform integration APIs before recommending custom native interop.
+- Request or verify permissions before using device capabilities that require them.
+- Use MainThread or Dispatcher when a device callback updates bound UI state.
+- Keep platform-specific code behind partial classes, handlers, or targeted platform integration patterns.
+
+## Deep dive subtopics
+
+- [App model deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/llms.txt): Permissions, main thread, launcher, browser, app metadata, and version tracking.
+- [Storage deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/llms.txt): File picker, app directories, preferences, and secure storage.
+- [Communication deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/llms.txt): Networking, web authenticator, email, SMS, phone dialer, and contacts.
+
+## App model and permissions
+
+- [Invoke platform code](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/invoke-platform-code.md): Multi-targeting, partial classes, and per-platform implementations.
+- [Permissions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/permissions.md): Request and verify runtime permissions.
+- [App information](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/app-information.md): App metadata and package information.
+- [Main thread](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/main-thread.md): Marshal work to the UI thread.
+
+## Storage and files
+
+- [File picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-picker.md): User file selection.
+- [File system helpers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-system-helpers.md): App directories and file access.
+- [Preferences](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/preferences.md): Local key-value app settings.
+- [Secure storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/secure-storage.md): Encrypted key-value data.
+
+## Device capabilities
+
+- [Device information](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/information.md): Device and platform metadata.
+- [Battery](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/battery.md): Battery state and power source.
+- [Geolocation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/geolocation.md): Current location retrieval.
+- [Sensors](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/sensors.md): Motion and environment sensor access.
+- [Haptic feedback](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/device/haptic-feedback.md): Trigger tactile feedback.
+
+## Communication and auth
+
+- [Networking](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/networking.md): Connectivity state, connection changes, and network access.
+- [Web authenticator](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/authentication.md): Browser-based OAuth and OIDC flows.
+- [Open browser](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/appmodel/open-browser.md): Launch browser links.
+- [Email](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/communication/email.md): Compose email via native apps.
+
+## Optional
+
+- [Customize UI appearance](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/customize-ui-appearance.md): Per-platform visual tuning.
+- [Native embedding](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/native-embedding.md): Embed native views into MAUI.
+- [Platform helpers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/platform-helpers.md): Platform detection helpers.
diff --git a/docs/platform-integration/storage/llms.txt b/docs/platform-integration/storage/llms.txt
new file mode 100644
index 0000000000..d3019fb71e
--- /dev/null
+++ b/docs/platform-integration/storage/llms.txt
@@ -0,0 +1,24 @@
+# .NET MAUI Storage
+
+> Storage APIs in .NET MAUI: file picker, app directories, preferences, and secure storage.
+
+Use this file when the question is specifically about storing data on device, reading and writing local files, or letting the user pick files.
+
+## Guidance for AI assistants
+
+- Use app directories and helpers for app-owned files before reaching for custom absolute paths.
+- Use preferences for simple local settings and secure storage for secrets or tokens.
+- Use file picker only when the user must choose external files.
+- Distinguish local app storage from user-selected or shared external files.
+
+## Core storage guidance
+
+- [File picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-picker.md): User file selection.
+- [File system helpers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/file-system-helpers.md): App directories and file access.
+- [Preferences](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/preferences.md): Local key-value app settings.
+- [Secure storage](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/storage/secure-storage.md): Encrypted key-value data.
+
+## Optional
+
+- [Data and cloud index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/data-cloud/llms.txt): Higher-level data architecture and backend concerns.
+- [Platform integration index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/llms.txt): Broader platform integration retrieval.
diff --git a/docs/user-interface/controls/collectionview/collectionview-guide.md b/docs/user-interface/controls/collectionview/collectionview-guide.md
new file mode 100644
index 0000000000..63c90d7ee9
--- /dev/null
+++ b/docs/user-interface/controls/collectionview/collectionview-guide.md
@@ -0,0 +1,816 @@
+---
+title: "CollectionView guide for .NET MAUI"
+description: "A comprehensive guide to using CollectionView in .NET MAUI — the recommended control for displaying lists of data with virtualization, flexible layouts, selection, grouping, and empty views."
+ms.date: 02/10/2026
+ms.topic: conceptual
+---
+
+# CollectionView guide for .NET MAUI
+
+## Overview and when to use CollectionView
+
+ is the recommended control for displaying lists of data in .NET MAUI. It replaces , which is obsolete and should not be used in new projects.
+
+Key advantages of `CollectionView` over `ListView`:
+
+- **Flexible layouts** — vertical lists, horizontal lists, vertical grids, and horizontal grids.
+- **No cells required** — uses directly instead of `ViewCell`.
+- **Single and multiple selection** — built-in support via `SelectionMode`.
+- **Headers, footers, and empty views** — declarative support without custom renderers.
+- **Virtualization** — efficient recycling of item views for large data sets.
+
+> [!WARNING]
+> **Never place `CollectionView` inside a `StackLayout` or `VerticalStackLayout`.** These layouts give `CollectionView` infinite space, which disables virtualization and causes severe performance degradation or blank rendering. Always use `Grid` or another constrained layout as the parent.
+
+> [!WARNING]
+> Updating `ItemsSource` from a background thread throws an exception. Always update the collection on the UI thread using `MainThread.BeginInvokeOnMainThread`.
+
+> [!TIP]
+> For small collections (≤20 items), consider using `BindableLayout` instead. It doesn't virtualize but is simpler to set up and avoids the overhead of a full `CollectionView`.
+
+## Populating with data
+
+### Basic ItemsSource binding
+
+Bind `ItemsSource` to an `ObservableCollection` or any `IEnumerable` in your view model. Define the appearance of each item with an `ItemTemplate`.
+
+In XAML:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+var collectionView = new CollectionView
+{
+ ItemsSource = viewModel.Monkeys,
+ ItemTemplate = new DataTemplate(() =>
+ {
+ var grid = new Grid
+ {
+ Padding = 10,
+ ColumnDefinitions =
+ {
+ new ColumnDefinition(GridLength.Auto),
+ new ColumnDefinition(GridLength.Star)
+ },
+ ColumnSpacing = 10
+ };
+
+ var image = new Image { HeightRequest = 60, WidthRequest = 60, Aspect = Aspect.AspectFill };
+ image.SetBinding(Image.SourceProperty, nameof(Monkey.ImageUrl));
+
+ var nameLabel = new Label { FontAttributes = FontAttributes.Bold };
+ nameLabel.SetBinding(Label.TextProperty, nameof(Monkey.Name));
+
+ var locationLabel = new Label { FontSize = 12, TextColor = Colors.Gray };
+ locationLabel.SetBinding(Label.TextProperty, nameof(Monkey.Location));
+
+ var stack = new VerticalStackLayout { VerticalOptions = LayoutOptions.Center };
+ stack.Children.Add(nameLabel);
+ stack.Children.Add(locationLabel);
+
+ grid.Add(image);
+ grid.Add(stack, 1);
+
+ return grid;
+ })
+};
+```
+
+> [!IMPORTANT]
+> Always use `x:DataType` on both the page and the `DataTemplate` for compiled bindings. This enables compile-time validation and improves performance.
+
+> [!WARNING]
+> Never use `ViewCell` as the `DataTemplate` root. `CollectionView` does not use cells — place your layout element (such as `Grid`) directly inside the `DataTemplate`.
+
+### DataTemplateSelector
+
+Use a to choose different templates based on item data:
+
+```csharp
+public class AnimalTemplateSelector : DataTemplateSelector
+{
+ public DataTemplate MonkeyTemplate { get; set; }
+ public DataTemplate CatTemplate { get; set; }
+
+ protected override DataTemplate OnSelectTemplate(object item, BindableObject container)
+ {
+ return ((Animal)item).Type == "Monkey" ? MonkeyTemplate : CatTemplate;
+ }
+}
+```
+
+Reference it in XAML:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Pull-to-refresh
+
+Wrap `CollectionView` in a to enable pull-to-refresh:
+
+```xaml
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+var refreshView = new RefreshView
+{
+ Content = collectionView
+};
+refreshView.SetBinding(RefreshView.IsRefreshingProperty, nameof(ViewModel.IsRefreshing));
+refreshView.SetBinding(RefreshView.CommandProperty, nameof(ViewModel.RefreshCommand));
+```
+
+### Incremental loading
+
+Use `RemainingItemsThreshold` and `RemainingItemsThresholdReachedCommand` to load more items as the user scrolls toward the end of the list:
+
+```xaml
+
+
+
+
+
+
+
+```
+
+When fewer than 5 items remain below the visible area, `LoadMoreCommand` executes. In your view model:
+
+```csharp
+[RelayCommand]
+private async Task LoadMoreAsync()
+{
+ var nextPage = await dataService.GetItemsAsync(currentPage + 1);
+ foreach (var item in nextPage)
+ {
+ Items.Add(item);
+ }
+ currentPage++;
+}
+```
+
+## Layout options
+
+`CollectionView` supports four layout modes controlled by the `ItemsLayout` property.
+
+### Vertical list (default)
+
+Items are arranged in a single-column vertical list. This is the default when no `ItemsLayout` is specified.
+
+```xaml
+
+```
+
+```csharp
+var collectionView = new CollectionView
+{
+ ItemsSource = viewModel.Items,
+ ItemsLayout = LinearItemsLayout.Vertical
+};
+```
+
+### Horizontal list
+
+Items are arranged in a single-row horizontal list.
+
+```xaml
+
+```
+
+```csharp
+var collectionView = new CollectionView
+{
+ ItemsSource = viewModel.Items,
+ ItemsLayout = LinearItemsLayout.Horizontal
+};
+```
+
+### Vertical grid
+
+Items are arranged in a multi-column vertical grid. Set `Span` to control the number of columns.
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+```csharp
+var collectionView = new CollectionView
+{
+ ItemsSource = viewModel.Items,
+ ItemsLayout = new GridItemsLayout(2, ItemsLayoutOrientation.Vertical)
+ {
+ VerticalItemSpacing = 5,
+ HorizontalItemSpacing = 5
+ }
+};
+```
+
+### Horizontal grid
+
+Items are arranged in a multi-row horizontal grid. Set `Span` to control the number of rows.
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+```csharp
+var collectionView = new CollectionView
+{
+ ItemsSource = viewModel.Items,
+ ItemsLayout = new GridItemsLayout(3, ItemsLayoutOrientation.Horizontal)
+};
+```
+
+### Item sizing strategy
+
+The `ItemSizingStrategy` property controls how items are measured:
+
+| Strategy | Description | When to use |
+|---|---|---|
+| `MeasureAllItems` | Measures every item individually. This is the default. | Variable-height items. |
+| `MeasureFirstItem` | Measures only the first item and applies its size to all items. | Uniform-height items — provides better scroll performance. |
+
+```xaml
+
+```
+
+```csharp
+collectionView.ItemSizingStrategy = ItemSizingStrategy.MeasureFirstItem;
+```
+
+## Headers and footers
+
+`CollectionView` supports headers and footers via the `Header`, `Footer`, `HeaderTemplate`, and `FooterTemplate` properties.
+
+### As a string
+
+```xaml
+
+```
+
+### As a View
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### As a DataTemplate
+
+Use `HeaderTemplate` or `FooterTemplate` when the header or footer content is data-bound:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+collectionView.Header = "Monkeys of the World";
+collectionView.Footer = new Label
+{
+ Text = "End of list",
+ Padding = 10,
+ HorizontalTextAlignment = TextAlignment.Center
+};
+```
+
+## Selection
+
+`CollectionView` provides built-in selection support through the `SelectionMode` property.
+
+### SelectionMode
+
+| Mode | Description | Properties |
+|---|---|---|
+| `None` | No item can be selected. This is the default. | — |
+| `Single` | One item at a time can be selected. | `SelectedItem` |
+| `Multiple` | Multiple items can be selected. | `SelectedItems` |
+
+### Single selection
+
+Bind `SelectedItem` with `Mode=TwoWay` to keep the view model in sync:
+
+```xaml
+
+
+
+
+
+
+
+```
+
+```csharp
+var collectionView = new CollectionView
+{
+ SelectionMode = SelectionMode.Single
+};
+collectionView.SetBinding(CollectionView.ItemsSourceProperty, nameof(ViewModel.Monkeys));
+collectionView.SetBinding(CollectionView.SelectedItemProperty, nameof(ViewModel.SelectedMonkey), BindingMode.TwoWay);
+```
+
+### SelectionChanged event and command
+
+Handle selection changes with the `SelectionChanged` event or `SelectionChangedCommand`:
+
+```xaml
+
+```
+
+Or in code-behind:
+
+```csharp
+collectionView.SelectionChanged += (sender, args) =>
+{
+ var selected = args.CurrentSelection.FirstOrDefault() as Monkey;
+ if (selected != null)
+ {
+ // Navigate or update details
+ }
+};
+```
+
+### Visual feedback for selected items
+
+Use `VisualStateManager` with the `Selected` visual state to style selected items:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+To programmatically clear the selection, set `SelectedItem` to `null` or call `SelectedItems.Clear()`.
+
+## Empty views
+
+When `ItemsSource` is empty or `null`, `CollectionView` can display an empty state using the `EmptyView` property.
+
+### As a string
+
+```xaml
+
+```
+
+### As a custom View
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### EmptyViewTemplate
+
+Use `EmptyViewTemplate` for dynamic empty states that are data-bound:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+collectionView.EmptyView = "No results found.";
+```
+
+## Grouping
+
+`CollectionView` can display grouped data by setting `IsGrouped="true"` and providing `GroupHeaderTemplate` and optionally `GroupFooterTemplate`.
+
+### Step 1: Define a group model
+
+Create a group class that extends `List`:
+
+```csharp
+public class AnimalGroup : List
+{
+ public string Name { get; }
+ public int Count => this.Count();
+
+ public AnimalGroup(string name, List animals)
+ : base(animals)
+ {
+ Name = name;
+ }
+}
+```
+
+### Step 2: Create grouped data in the view model
+
+```csharp
+public ObservableCollection GroupedAnimals { get; } = new()
+{
+ new AnimalGroup("Primates", new List
+ {
+ new Animal { Name = "Capuchin" },
+ new Animal { Name = "Gorilla" }
+ }),
+ new AnimalGroup("Felines", new List
+ {
+ new Animal { Name = "Lion" },
+ new Animal { Name = "Tiger" }
+ })
+};
+```
+
+### Step 3: Configure CollectionView
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+var collectionView = new CollectionView
+{
+ IsGrouped = true,
+ ItemsSource = viewModel.GroupedAnimals,
+ GroupHeaderTemplate = new DataTemplate(() =>
+ {
+ var label = new Label
+ {
+ FontAttributes = FontAttributes.Bold,
+ FontSize = 16,
+ Padding = 10,
+ BackgroundColor = Colors.LightGray
+ };
+ label.SetBinding(Label.TextProperty, nameof(AnimalGroup.Name));
+ return label;
+ }),
+ ItemTemplate = new DataTemplate(() =>
+ {
+ var label = new Label { Padding = new Thickness(20, 5) };
+ label.SetBinding(Label.TextProperty, nameof(Animal.Name));
+ return label;
+ })
+};
+```
+
+## Scrolling
+
+### ScrollTo by index
+
+Scroll to a specific item index:
+
+```csharp
+// Scroll to the 10th item with animation
+collectionView.ScrollTo(9, animate: true);
+
+// Scroll to the 5th item in the 2nd group
+collectionView.ScrollTo(4, 1, animate: true);
+```
+
+### ScrollTo by item
+
+Scroll to a specific item object:
+
+```csharp
+collectionView.ScrollTo(selectedMonkey, animate: true);
+
+// Scroll to an item within a group
+collectionView.ScrollTo(selectedAnimal, animalGroup, animate: true);
+```
+
+The `ScrollToPosition` parameter controls where the item appears on screen:
+
+| Value | Description |
+|---|---|
+| `MakeVisible` | Scrolls the minimum amount to make the item visible. This is the default. |
+| `Start` | Scrolls the item to the start of the visible area. |
+| `Center` | Scrolls the item to the center of the visible area. |
+| `End` | Scrolls the item to the end of the visible area. |
+
+```csharp
+collectionView.ScrollTo(item, position: ScrollToPosition.Center, animate: true);
+```
+
+### ScrollBarVisibility
+
+Control scroll bar visibility on each axis:
+
+```xaml
+
+```
+
+### Snap points
+
+Snap points control how items align after a scroll gesture completes.
+
+```xaml
+
+
+
+
+
+```
+
+| SnapPointsType | Description |
+|---|---|
+| `None` | No snapping. This is the default. |
+| `Mandatory` | Snaps to the nearest snap point. |
+| `MandatorySingle` | Snaps to the nearest snap point, one item at a time. |
+
+| SnapPointsAlignment | Description |
+|---|---|
+| `Start` | Snap points align to the leading edge of items. |
+| `Center` | Snap points align to the center of items. |
+| `End` | Snap points align to the trailing edge of items. |
+
+### ItemsUpdatingScrollMode
+
+The `ItemsUpdatingScrollMode` property controls scroll behavior when new items are added:
+
+| Value | Description |
+|---|---|
+| `KeepItemsInView` | Adjusts the scroll offset to keep the first visible item in view. This is the default. |
+| `KeepScrollOffset` | Maintains the current scroll offset. |
+| `KeepLastItemInView` | Adjusts the scroll offset to keep the last visible item in view — useful for chat-style lists. |
+
+```xaml
+
+```
+
+## Context actions with SwipeView
+
+Wrap item content in a to add swipe-based context actions such as delete or favorite:
+
+```xaml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+In C#:
+
+```csharp
+var itemTemplate = new DataTemplate(() =>
+{
+ var swipeView = new SwipeView();
+
+ var deleteItem = new SwipeItem
+ {
+ Text = "Delete",
+ BackgroundColor = Colors.Red
+ };
+ deleteItem.SetBinding(SwipeItem.CommandProperty,
+ new Binding(nameof(MonkeysViewModel.DeleteCommand),
+ source: new RelativeBindingSource(RelativeBindingSourceMode.FindAncestorBindingContext,
+ typeof(MonkeysViewModel))));
+ deleteItem.SetBinding(SwipeItem.CommandParameterProperty, ".");
+
+ swipeView.RightItems = new SwipeItems { deleteItem };
+
+ var grid = new Grid
+ {
+ Padding = 10,
+ ColumnDefinitions =
+ {
+ new ColumnDefinition(GridLength.Auto),
+ new ColumnDefinition(GridLength.Star)
+ },
+ ColumnSpacing = 10
+ };
+
+ var image = new Image { HeightRequest = 60, WidthRequest = 60 };
+ image.SetBinding(Image.SourceProperty, nameof(Monkey.ImageUrl));
+
+ var label = new Label { VerticalOptions = LayoutOptions.Center };
+ label.SetBinding(Label.TextProperty, nameof(Monkey.Name));
+
+ grid.Add(image);
+ grid.Add(label, 1);
+
+ swipeView.Content = grid;
+ return swipeView;
+});
+```
+
+## Performance tips
+
+Follow these guidelines to maximize `CollectionView` performance:
+
+1. **Always use compiled bindings** — set `x:DataType` on the `DataTemplate` to enable compile-time binding resolution.
+2. **Use `MeasureFirstItem`** for uniform-height items to avoid measuring every item individually.
+3. **Never place `CollectionView` in `StackLayout`** — use `Grid` or a constrained layout to preserve virtualization.
+4. **Keep the `DataTemplate` visual tree flat** — prefer a single `Grid` over nested `StackLayout` containers. Fewer layout passes mean faster rendering.
+5. **Use `ObservableCollection`** — changes to the collection are reflected automatically without resetting the entire view.
+6. **Avoid complex bindings in templates** — use simple property bindings instead of multi-bindings or converters where possible.
+7. **Set a fixed `HeightRequest` or `WidthRequest`** on item templates when the size is known, to reduce layout calculations.
+
+> [!NOTE]
+> If you're migrating from `ListView`, note that `ListView.CachingStrategy` does not apply to `CollectionView`. Virtualization in `CollectionView` is always enabled when the parent layout provides constrained space.
+
+## See also
+
+- [CollectionView overview](index.md)
+- [CollectionView data](populate-data.md)
+- [CollectionView layout](layout.md)
+- [CollectionView selection](selection.md)
+- [CollectionView empty views](emptyview.md)
+- [CollectionView scrolling](scrolling.md)
+- [CollectionView grouping](grouping.md)
diff --git a/docs/user-interface/controls/collectionview/llms.txt b/docs/user-interface/controls/collectionview/llms.txt
new file mode 100644
index 0000000000..ca7c1d3cac
--- /dev/null
+++ b/docs/user-interface/controls/collectionview/llms.txt
@@ -0,0 +1,37 @@
+# .NET MAUI CollectionView
+
+> CollectionView in .NET MAUI: data templates, layouts, selection, grouping, empty views, scrolling, and performance-sensitive list UI behavior.
+
+Use this file when the question is specifically about CollectionView behavior rather than general control choice.
+
+## Guidance for AI assistants
+
+- Use CollectionView for new list UI instead of ListView.
+- Do not place CollectionView inside StackLayout or VerticalStackLayout when constrained scrolling or virtualization matters.
+- Do not use ViewCell in CollectionView templates.
+- Use compiled bindings and simple visual trees in item templates when performance matters.
+- Use BindableLayout instead of CollectionView only when the item count is small and virtualization is unnecessary.
+- Update bound collections on the UI thread.
+
+## Core CollectionView guidance
+
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Highest-value guide covering data, templates, layout, selection, grouping, empty views, scrolling, and performance.
+- [CollectionView overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/index.md): Core CollectionView concepts.
+- [Populate CollectionView data](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/populate-data.md): ItemsSource, templates, selectors, refresh, and incremental loading.
+- [CollectionView layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/layout.md): Vertical lists, horizontal lists, and grids.
+- [CollectionView selection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/selection.md): Selection modes and selection change handling.
+- [CollectionView grouping](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/grouping.md): Group headers, grouped sources, and grouped templates.
+- [CollectionView empty views](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/emptyview.md): Empty-state presentation.
+- [CollectionView scrolling](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/scrolling.md): ScrollTo, snap points, and update-scroll behavior.
+
+## Related patterns
+
+- [Compiled bindings](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/compiled-bindings.md): Improve list template binding correctness and performance.
+- [BindableLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/bindablelayout.md): Simpler alternative when the collection is small and virtualization is unnecessary.
+- [RefreshView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/refreshview.md): Add pull-to-refresh around CollectionView content.
+- [SwipeView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/swipeview.md): Add swipe actions to items.
+
+## Optional
+
+- [Controls deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Broader control-selection guidance around CollectionView.
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): Broader UI performance guidance that affects list scenarios.
diff --git a/docs/user-interface/controls/llms.txt b/docs/user-interface/controls/llms.txt
new file mode 100644
index 0000000000..24f89a2e3e
--- /dev/null
+++ b/docs/user-interface/controls/llms.txt
@@ -0,0 +1,57 @@
+# .NET MAUI Controls
+
+> Control selection and usage in .NET MAUI: lists, input controls, content containers, images, web content, and obsolete control replacements.
+
+Use this file when the question is specifically about choosing or configuring a control rather than overall layout or handler customization.
+
+## Deep dive subtopics
+
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): Narrow retrieval for CollectionView behavior, templates, layout, selection, grouping, and scrolling.
+
+## Guidance for AI assistants
+
+- Prefer CollectionView over ListView for new list UI.
+- Prefer Border over Frame for new container UI.
+- Do not use ViewCell inside CollectionView templates.
+- Constrain image size explicitly in scrolling or templated UI when performance matters.
+- Use RefreshView or SwipeView as companion controls around list content when appropriate.
+
+## Lists and item presentation
+
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Highest-value guide for list UI, virtualization, grouping, empty views, and selection.
+- [CollectionView overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/index.md): Core CollectionView concepts.
+- [Populate CollectionView data](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/populate-data.md): Bind data sources and item templates.
+- [CollectionView layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/layout.md): List and grid layout options.
+- [CollectionView selection](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/selection.md): Single and multiple selection behavior.
+- [CollectionView scrolling](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/scrolling.md): Scroll behavior, snapping, and scrolling APIs.
+- [CollectionView grouping](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/grouping.md): Grouped list behavior.
+- [CollectionView empty views](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/emptyview.md): Empty-state presentation.
+
+## Input and content controls
+
+- [Entry](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/entry.md): Single-line text input.
+- [Editor](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/editor.md): Multi-line text input.
+- [Picker](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/picker.md): Select from a list of options.
+- [Button](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/button.md): Tap or click actions.
+- [Label](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/label.md): Display formatted text.
+- [ContentView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/contentview.md): Build reusable composite UI.
+- [Border](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/border.md): Preferred modern container with stroke and corner customization.
+
+## Images, web, and companion controls
+
+- [Image](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/image.md): Display local or remote images.
+- [WebView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/webview.md): Display web content.
+- [BlazorWebView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/blazorwebview.md): Host Blazor UI inside a native MAUI app.
+- [RefreshView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/refreshview.md): Pull-to-refresh behavior.
+- [SwipeView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/swipeview.md): Swipe actions for list items and content.
+
+## Obsolete or avoid-for-new-work
+
+- [ListView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/listview.md): Older list control; use CollectionView for new work.
+- [Frame](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/frame.md): Older container; use Border for new work.
+- [TableView](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/tableview.md): Older settings-form style control with narrower modern use.
+
+## Optional
+
+- [Controls overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/index.md): Full catalog of built-in controls.
+- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Pair control selection with the right layout container.
diff --git a/docs/user-interface/handlers/handler-architecture.md b/docs/user-interface/handlers/handler-architecture.md
new file mode 100644
index 0000000000..11dfbcfe26
--- /dev/null
+++ b/docs/user-interface/handlers/handler-architecture.md
@@ -0,0 +1,590 @@
+---
+title: "Handler architecture in .NET MAUI"
+description: "Understand the .NET MAUI handler architecture — how handlers map cross-platform controls to native views, how to create custom controls, and how to customize existing controls."
+ms.date: 02/10/2026
+ms.topic: conceptual
+---
+
+# Handler architecture in .NET MAUI
+
+.NET Multi-platform App UI (.NET MAUI) uses a **handler architecture** to map cross-platform controls to native platform views. This guide explains the full architecture: what handlers are, how they work, how to create custom controls, and how to customize existing controls.
+
+## What are handlers
+
+Handlers are the bridge between cross-platform .NET MAUI controls and native platform views. Each .NET MAUI control has a corresponding handler that creates and manages the native control on each platform. For example, a .NET MAUI maps to:
+
+| Platform | Native view |
+|---|---|
+| Android | `MaterialButton` |
+| iOS / Mac Catalyst | `UIButton` |
+| Windows | `Microsoft.UI.Xaml.Controls.Button` |
+
+The key architecture is a three-layer pipeline:
+
+```
+Virtual View (cross-platform control) → Handler → Platform View (native control)
+```
+
+The cross-platform control is known as the **virtual view**. It defines the public API (properties, events, commands) that developers use. The handler translates that API into calls on the **platform view** — the actual native control rendered on screen. Each handler exposes:
+
+- `VirtualView` — the cross-platform control instance.
+- `PlatformView` — the underlying native control.
+
+```csharp
+// Access the native Android EditText from an Entry handler
+#if ANDROID
+var nativeEditText = entry.Handler?.PlatformView as Android.Widget.EditText;
+if (nativeEditText is not null)
+{
+ nativeEditText.SetHintTextColor(Android.Graphics.Color.Gray);
+}
+#endif
+```
+
+> [!IMPORTANT]
+> Handlers replaced Xamarin.Forms renderers. If you are migrating from Xamarin.Forms, always use handlers — never use the legacy renderer compatibility infrastructure for new code.
+
+## How handlers work
+
+A handler inherits from `ViewHandler`, where `TVirtualView` is the cross-platform control type and `TPlatformView` is the native view type. The handler uses two mapper dictionaries to keep the virtual view and platform view synchronized.
+
+### Property mappers
+
+A **property mapper** is a dictionary that maps cross-platform property names to static methods. When a property changes on the virtual view, the handler looks up the property name in the mapper and invokes the corresponding method to update the native view.
+
+```csharp
+public static IPropertyMapper Mapper =
+ new PropertyMapper(ViewMapper)
+ {
+ [nameof(IRatingControl.Value)] = MapValue,
+ [nameof(IRatingControl.Maximum)] = MapMaximum,
+ };
+```
+
+Each mapped method receives the handler and virtual view, then updates the platform view:
+
+```csharp
+public static void MapValue(RatingControlHandler handler, IRatingControl control)
+{
+ handler.PlatformView.UpdateValue(control.Value);
+}
+```
+
+### Command mappers
+
+A **command mapper** works similarly but handles imperative actions (commands) rather than property changes. Commands can carry optional arguments.
+
+```csharp
+public static ICommandMapper CommandMapper =
+ new CommandMapper(ViewCommandMapper)
+ {
+ [nameof(IRatingControl.Reset)] = MapReset,
+ };
+
+public static void MapReset(RatingControlHandler handler, IRatingControl control, object? args)
+{
+ handler.PlatformView.UpdateValue(0);
+}
+```
+
+### Key handler overrides
+
+When implementing a handler, you typically override:
+
+| Method | Purpose |
+|---|---|
+| `CreatePlatformView()` | Creates and returns the native view instance. |
+| `ConnectHandler()` | Subscribes to native events after the native view is created. |
+| `DisconnectHandler()` | Unsubscribes from native events and performs cleanup. |
+
+```csharp
+protected override PlatformRatingView CreatePlatformView()
+{
+ return new PlatformRatingView(Context);
+}
+
+protected override void ConnectHandler(PlatformRatingView platformView)
+{
+ base.ConnectHandler(platformView);
+ platformView.ValueChanged += OnPlatformValueChanged;
+}
+
+protected override void DisconnectHandler(PlatformRatingView platformView)
+{
+ platformView.ValueChanged -= OnPlatformValueChanged;
+ base.DisconnectHandler(platformView);
+}
+```
+
+## Creating a custom control with a handler
+
+Building a custom control requires four pieces: a cross-platform control, an interface, a handler, and platform implementations. The following example creates a `RatingControl` that displays a star rating.
+
+### Step 1 — Define the cross-platform control
+
+Create the control class with declarations:
+
+```csharp
+namespace MyApp.Controls;
+
+public class RatingControl : View
+{
+ public static readonly BindableProperty ValueProperty =
+ BindableProperty.Create(nameof(Value), typeof(double), typeof(RatingControl), 0.0);
+
+ public static readonly BindableProperty MaximumProperty =
+ BindableProperty.Create(nameof(Maximum), typeof(double), typeof(RatingControl), 5.0);
+
+ public double Value
+ {
+ get => (double)GetValue(ValueProperty);
+ set => SetValue(ValueProperty, value);
+ }
+
+ public double Maximum
+ {
+ get => (double)GetValue(MaximumProperty);
+ set => SetValue(MaximumProperty, value);
+ }
+}
+```
+
+Define an interface so the handler can work against an abstraction:
+
+```csharp
+namespace MyApp.Controls;
+
+public interface IRatingControl : IView
+{
+ double Value { get; }
+ double Maximum { get; }
+}
+```
+
+Update the control to implement the interface:
+
+```csharp
+public class RatingControl : View, IRatingControl
+{
+ // ... BindableProperty declarations unchanged ...
+}
+```
+
+### Step 2 — Create the partial handler class
+
+The handler is a `partial` class. The shared file declares the property mapper and constructor, while platform-specific files provide `CreatePlatformView()` and mapper methods.
+
+**Shared handler (all platforms):**
+
+```csharp
+#if ANDROID
+using PlatformView = Android.Widget.ProgressBar;
+#elif IOS || MACCATALYST
+using PlatformView = UIKit.UIProgressView;
+#elif WINDOWS
+using PlatformView = Microsoft.UI.Xaml.Controls.ProgressBar;
+#endif
+
+namespace MyApp.Handlers;
+
+public partial class RatingControlHandler : ViewHandler
+{
+ public static IPropertyMapper Mapper =
+ new PropertyMapper(ViewMapper)
+ {
+ [nameof(IRatingControl.Value)] = MapValue,
+ [nameof(IRatingControl.Maximum)] = MapMaximum,
+ };
+
+ public RatingControlHandler() : base(Mapper)
+ {
+ }
+}
+```
+
+### Step 3 — Platform implementations
+
+Each platform file provides `CreatePlatformView()` and the static mapper methods.
+
+**Android** (`Platforms/Android/RatingControlHandler.cs`):
+
+```csharp
+namespace MyApp.Handlers;
+
+public partial class RatingControlHandler
+{
+ protected override Android.Widget.ProgressBar CreatePlatformView()
+ {
+ return new Android.Widget.ProgressBar(Context, null, Android.Resource.Attribute.ProgressBarStyleHorizontal)
+ {
+ Max = (int)VirtualView.Maximum,
+ Progress = (int)VirtualView.Value,
+ };
+ }
+
+ public static void MapValue(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Progress = (int)control.Value;
+ }
+
+ public static void MapMaximum(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Max = (int)control.Maximum;
+ }
+}
+```
+
+**iOS / Mac Catalyst** (`Platforms/iOS/RatingControlHandler.cs`):
+
+```csharp
+namespace MyApp.Handlers;
+
+public partial class RatingControlHandler
+{
+ protected override UIKit.UIProgressView CreatePlatformView()
+ {
+ return new UIKit.UIProgressView(UIKit.UIProgressViewStyle.Default);
+ }
+
+ public static void MapValue(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Progress = (float)(control.Value / control.Maximum);
+ }
+
+ public static void MapMaximum(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Progress = (float)(control.Value / control.Maximum);
+ }
+}
+```
+
+**Windows** (`Platforms/Windows/RatingControlHandler.cs`):
+
+```csharp
+namespace MyApp.Handlers;
+
+public partial class RatingControlHandler
+{
+ protected override Microsoft.UI.Xaml.Controls.ProgressBar CreatePlatformView()
+ {
+ return new Microsoft.UI.Xaml.Controls.ProgressBar
+ {
+ Minimum = 0,
+ Maximum = VirtualView.Maximum,
+ Value = VirtualView.Value,
+ };
+ }
+
+ public static void MapValue(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Value = control.Value;
+ }
+
+ public static void MapMaximum(RatingControlHandler handler, IRatingControl control)
+ {
+ handler.PlatformView.Maximum = control.Maximum;
+ }
+}
+```
+
+### Step 4 — Register the handler
+
+Register the handler in `MauiProgram.cs` using :
+
+```csharp
+using MyApp.Controls;
+using MyApp.Handlers;
+
+public static class MauiProgram
+{
+ public static MauiApp CreateMauiApp()
+ {
+ var builder = MauiApp.CreateBuilder();
+ builder
+ .UseMauiApp()
+ .ConfigureMauiHandlers(handlers =>
+ {
+ handlers.AddHandler();
+ });
+
+ return builder.Build();
+ }
+}
+```
+
+After registration, use the control in XAML:
+
+```xaml
+
+
+
+```
+
+## Customizing existing controls
+
+The most common use of handlers is customizing existing .NET MAUI controls to apply platform-specific tweaks. You do this by modifying a handler's property mapper — no subclassing of the handler is required.
+
+> [!IMPORTANT]
+> Handler customizations are global. Once you modify a handler's mapper, the change affects **every** instance of that control type throughout your app.
+
+### AppendToMapping
+
+ runs your customization **after** .NET MAUI's own property mapping. Use it for platform-specific tweaks that build on top of the default behavior.
+
+```csharp
+Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("MyCustomization", (handler, view) =>
+{
+#if ANDROID
+ handler.PlatformView.SetSelectAllOnFocus(true);
+#elif IOS || MACCATALYST
+ handler.PlatformView.EditingDidBegin += (s, e) =>
+ {
+ handler.PlatformView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
+ };
+#elif WINDOWS
+ handler.PlatformView.GotFocus += (s, e) =>
+ {
+ handler.PlatformView.SelectAll();
+ };
+#endif
+});
+```
+
+### PrependToMapping
+
+ runs your customization **before** .NET MAUI's own property mapping. Use it when you need to set platform defaults before .NET MAUI applies its mappings.
+
+```csharp
+Microsoft.Maui.Handlers.EntryHandler.Mapper.PrependToMapping("DefaultPlaceholderColor", (handler, view) =>
+{
+#if ANDROID
+ handler.PlatformView.SetHintTextColor(Android.Graphics.Color.LightGray);
+#elif IOS || MACCATALYST
+ // Set a default attributed placeholder before MAUI applies its own
+ handler.PlatformView.AttributedPlaceholder = new Foundation.NSAttributedString(
+ handler.PlatformView.Placeholder ?? string.Empty,
+ new UIKit.UIStringAttributes { ForegroundColor = UIKit.UIColor.LightGray });
+#endif
+});
+```
+
+### ModifyMapping
+
+ replaces or wraps an existing mapping. The third parameter gives you access to the original mapping action so you can call it conditionally.
+
+```csharp
+Microsoft.Maui.Handlers.EntryHandler.Mapper.ModifyMapping(
+ nameof(IEntry.Background), (handler, view, action) =>
+{
+ // Call the default mapping first
+ action?.Invoke(handler, view);
+
+ // Then apply additional behavior
+#if ANDROID
+ handler.PlatformView.SetBackgroundColor(Android.Graphics.Color.AliceBlue);
+#endif
+});
+```
+
+### Scoping customization to a specific control instance
+
+Because handler customizations are global, use a type check to limit the customization to a subclassed control:
+
+```csharp
+public class BorderlessEntry : Entry { }
+```
+
+Then check the type inside the mapping action:
+
+```csharp
+Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("Borderless", (handler, view) =>
+{
+ if (view is BorderlessEntry)
+ {
+#if ANDROID
+ handler.PlatformView.Background = null;
+ handler.PlatformView.SetBackgroundColor(Android.Graphics.Color.Transparent);
+#elif IOS || MACCATALYST
+ handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
+#elif WINDOWS
+ handler.PlatformView.BorderThickness = new Microsoft.UI.Xaml.Thickness(0);
+#endif
+ }
+});
+```
+
+Use the subclassed control in XAML just like the original:
+
+```xaml
+
+```
+
+### Global handler customization in MauiProgram.cs
+
+Register all handler customizations during app startup in `MauiProgram.cs` to ensure they apply before any UI is rendered:
+
+```csharp
+public static class MauiProgram
+{
+ public static MauiApp CreateMauiApp()
+ {
+ var builder = MauiApp.CreateBuilder();
+ builder
+ .UseMauiApp()
+ .ConfigureMauiHandlers(handlers =>
+ {
+ // Register custom handlers
+ handlers.AddHandler();
+ });
+
+ // Customize existing handlers after the builder is configured
+ EntryHandler.Mapper.AppendToMapping("NoUnderline", (handler, view) =>
+ {
+#if ANDROID
+ handler.PlatformView.BackgroundTintList =
+ Android.Content.Res.ColorStateList.ValueOf(Android.Graphics.Color.Transparent);
+#endif
+ });
+
+ return builder.Build();
+ }
+}
+```
+
+> [!NOTE]
+> You can place `AppendToMapping` / `PrependToMapping` calls anywhere that runs before the control is displayed, but `MauiProgram.cs` is the conventional and recommended location for global customizations.
+
+## Handler lifecycle
+
+Every handler-based .NET MAUI control raises two lifecycle events.
+
+### HandlerChanging
+
+Raised when a new handler is about to be set, or when the current handler is about to be removed. Use `HandlerChangingEventArgs` to inspect `NewHandler` and `OldHandler`:
+
+```csharp
+myControl.HandlerChanging += (s, e) =>
+{
+ if (e.OldHandler is not null)
+ {
+ // Unwire native events from the old handler
+ // This is your cleanup opportunity
+ }
+
+ if (e.NewHandler is not null)
+ {
+ // A new handler is about to be assigned
+ }
+};
+```
+
+### HandlerChanged
+
+Raised after the handler is fully created and all cross-platform property values have been applied to the native view. This is the safe point to access `PlatformView`:
+
+```csharp
+myEntry.HandlerChanged += (s, e) =>
+{
+ if (myEntry.Handler?.PlatformView is not null)
+ {
+#if ANDROID
+ var editText = (Android.Widget.EditText)myEntry.Handler.PlatformView;
+ editText.SetSelectAllOnFocus(true);
+#elif IOS || MACCATALYST
+ var textField = (UIKit.UITextField)myEntry.Handler.PlatformView;
+ textField.ClearButtonMode = UIKit.UITextFieldViewMode.WhileEditing;
+#endif
+ }
+};
+```
+
+> [!NOTE]
+> `HandlerChanging` is always raised before `HandlerChanged`.
+
+## Common handler customization recipes
+
+The following recipes demonstrate frequent platform-specific customizations.
+
+### Remove Entry underline / border
+
+```csharp
+Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoUnderline", (handler, view) =>
+{
+#if ANDROID
+ handler.PlatformView.BackgroundTintList =
+ Android.Content.Res.ColorStateList.ValueOf(Android.Graphics.Color.Transparent);
+#elif IOS || MACCATALYST
+ handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
+#elif WINDOWS
+ handler.PlatformView.BorderThickness = new Microsoft.UI.Xaml.Thickness(0);
+ handler.PlatformView.Padding = new Microsoft.UI.Xaml.Thickness(0);
+#endif
+});
+```
+
+### Set native button corner radius
+
+```csharp
+Microsoft.Maui.Handlers.ButtonHandler.Mapper.AppendToMapping("RoundedButton", (handler, view) =>
+{
+#if ANDROID
+ handler.PlatformView.CornerRadius = 20;
+#elif IOS || MACCATALYST
+ handler.PlatformView.Layer.CornerRadius = 20;
+ handler.PlatformView.ClipsToBounds = true;
+#endif
+});
+```
+
+### Customize Editor placeholder text
+
+```csharp
+Microsoft.Maui.Handlers.EditorHandler.Mapper.AppendToMapping("PlaceholderColor", (handler, view) =>
+{
+#if ANDROID
+ handler.PlatformView.SetHintTextColor(Android.Graphics.Color.Gray);
+#elif IOS || MACCATALYST
+ // iOS Editor (UITextView) doesn't have a built-in placeholder;
+ // use a custom overlay or set text attributes in the delegate.
+#endif
+});
+```
+
+### Access the native navigation bar on iOS
+
+```csharp
+Microsoft.Maui.Handlers.NavigationViewHandler.Mapper.AppendToMapping("TransparentNavBar", (handler, view) =>
+{
+#if IOS || MACCATALYST
+ var navController = handler.ViewController?.NavigationController;
+ if (navController is not null)
+ {
+ navController.NavigationBar.SetBackgroundImage(new UIKit.UIImage(), UIKit.UIBarMetrics.Default);
+ navController.NavigationBar.ShadowImage = new UIKit.UIImage();
+ navController.NavigationBar.Translucent = true;
+ }
+#endif
+});
+```
+
+## When to use handlers vs other approaches
+
+| Approach | When to use |
+|---|---|
+| **Handler customization** (`AppendToMapping` / `PrependToMapping`) | You need platform-specific visual or behavioral changes to an existing control. This is the most common scenario. |
+| **Custom control with handler** | No built-in .NET MAUI control fits your requirements, and you need full control over the native view on each platform. |
+| **Platform code via `#if`** | You need platform APIs that aren't related to UI controls, such as accessing sensors or platform services. See [Invoke platform code](../../platform-integration/invoke-platform-code.md). |
+| **Effects** | Deprecated in .NET MAUI. Always use handlers instead. |
+
+> [!NOTE]
+> If you are migrating from Xamarin.Forms, convert all custom renderers and effects to handlers. The handler architecture is more performant and decouples the cross-platform control from its native implementation.
+
+## See also
+
+- [Handlers overview](index.md)
+- [Create custom controls with handlers](create.md)
+- [Customize controls with handlers](customize.md)
+- [Invoke platform code](../../platform-integration/invoke-platform-code.md)
diff --git a/docs/user-interface/handlers/llms.txt b/docs/user-interface/handlers/llms.txt
new file mode 100644
index 0000000000..396c57d36e
--- /dev/null
+++ b/docs/user-interface/handlers/llms.txt
@@ -0,0 +1,30 @@
+# .NET MAUI Handlers
+
+> Handlers in .NET MAUI: architecture, property mappers, lifecycle, global customization, and creating custom controls backed by native views.
+
+Use this file when the question is specifically about native control customization, renderer migration, or building custom controls with platform implementations.
+
+## Guidance for AI assistants
+
+- Use handlers instead of Xamarin.Forms renderers or effects for new code.
+- Reach for AppendToMapping, PrependToMapping, or ModifyMapping before inventing a custom handler.
+- Remember handler customizations are global unless scoped to a subclassed control.
+- Access PlatformView only after the handler lifecycle makes it available.
+
+## Core handler model
+
+- [Handler architecture guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): Most complete guide to handler concepts, lifecycle, and customization.
+- [Handlers overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/index.md): High-level model for virtual view to native view mapping.
+
+## Customizing existing controls
+
+- [Customize controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/customize.md): Append, prepend, and modify existing mappings.
+
+## Creating custom controls
+
+- [Create controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/create.md): Define custom controls with platform-specific native implementations.
+
+## Optional
+
+- [Invoke platform code](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/platform-integration/invoke-platform-code.md): Related patterns when the need is platform code beyond control customization.
+- [Controls deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Pair control choice with handler customization where needed.
diff --git a/docs/user-interface/layouts/llms.txt b/docs/user-interface/layouts/llms.txt
new file mode 100644
index 0000000000..26ac1371ab
--- /dev/null
+++ b/docs/user-interface/layouts/llms.txt
@@ -0,0 +1,33 @@
+# .NET MAUI Layouts
+
+> Layout selection in .NET MAUI: Grid, VerticalStackLayout, HorizontalStackLayout, FlexLayout, AbsoluteLayout, BindableLayout, and layout performance tradeoffs.
+
+Use this file when the question is specifically about layout choice, sizing, alignment, scrolling constraints, responsiveness, or avoiding expensive visual trees.
+
+## Guidance for AI assistants
+
+- Prefer Grid over deeply nested StackLayout trees for non-trivial layouts.
+- Prefer VerticalStackLayout or HorizontalStackLayout over StackLayout when the layout direction is fixed.
+- Do not place CollectionView or ScrollView inside StackLayout when constrained scrolling or virtualization matters.
+- Use BindableLayout only for small collections where virtualization is unnecessary.
+- Treat layout simplification as a primary performance lever in MAUI UI.
+
+## Core layout guidance
+
+- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Choose the right layout container for structure, alignment, and responsiveness.
+- [Grid](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/grid.md): Preferred layout for complex UI, rows and columns, and responsive structure.
+- [VerticalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/verticalstacklayout.md): Lightweight vertical stacking.
+- [HorizontalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/horizontalstacklayout.md): Lightweight horizontal stacking.
+- [FlexLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/flexlayout.md): Flexible wrapping and adaptive item arrangement.
+- [AbsoluteLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/absolutelayout.md): Position items with explicit bounds when required.
+- [BindableLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/bindablelayout.md): Small-item data rendering without CollectionView.
+
+## Advanced or specialized layouts
+
+- [Custom layouts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/custom.md): Build custom layout containers.
+- [StackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/stacklayout.md): Older general stack layout; prefer directional stack layouts for new work.
+
+## Optional
+
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): Pair layout decisions with list virtualization and item-template behavior.
+- [Performance best practices](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/deployment/performance-best-practices.md): Broader guidance on reducing layout cost.
diff --git a/docs/user-interface/llms.txt b/docs/user-interface/llms.txt
new file mode 100644
index 0000000000..8d48b3de2c
--- /dev/null
+++ b/docs/user-interface/llms.txt
@@ -0,0 +1,58 @@
+# .NET MAUI User Interface
+
+> Controls, layouts, handlers, styling, and interaction patterns for building responsive MAUI UI across mobile and desktop.
+
+Use this file for control choice, layout performance, and platform-specific UI customization. It is the right entry point when the question is about choosing controls, fixing layout behavior, improving scrolling performance, styling visuals, or customizing native UI behavior.
+
+## Guidance for AI assistants
+
+- Prefer CollectionView over ListView for new list UI.
+- Prefer Border over Frame for new container UI.
+- Prefer Grid over deeply nested StackLayout trees for non-trivial layout.
+- Do not place CollectionView or ScrollView inside StackLayout when constrained scrolling or virtualization matters.
+- Use handlers for control customization; do not recommend effects or custom renderers for new code.
+
+## Deep dive subtopics
+
+- [Controls deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/llms.txt): Control selection, list behavior, input, web, and obsolete control replacements.
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): CollectionView data, layout, selection, grouping, empty views, and scrolling.
+- [Layouts deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/llms.txt): Grid, stack layouts, FlexLayout, BindableLayout, and layout performance tradeoffs.
+- [Handlers deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/llms.txt): Handler lifecycle, customization, and custom control creation.
+
+## Controls and lists
+
+- [CollectionView guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/collectionview-guide.md): Recommended list control patterns, virtualization, and performance.
+- [Controls overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/index.md): Catalog of built-in controls.
+- [CollectionView overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/index.md): Core CollectionView concepts.
+- [Entry](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/entry.md): Single-line text input.
+- [Editor](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/editor.md): Multi-line text input.
+- [Image](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/image.md): Local and remote image display.
+
+## Layout and visual structure
+
+- [Grid](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/grid.md): Preferred layout for complex UI.
+- [Layouts overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/index.md): Select the right layout container for sizing, scrolling, and responsiveness.
+- [VerticalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/verticalstacklayout.md): Lightweight vertical layout.
+- [HorizontalStackLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/horizontalstacklayout.md): Lightweight horizontal layout.
+- [BindableLayout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/layouts/bindablelayout.md): Simple item rendering without virtualization.
+
+## Handlers and customization
+
+- [Handler architecture guide](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/handler-architecture.md): Handler model, lifecycle, and customization patterns.
+- [Handlers overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/index.md): Mapping virtual views to native controls.
+- [Customize controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/customize.md): Append and modify handler mappings.
+- [Create controls with handlers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/handlers/create.md): Build custom controls with native implementations.
+
+## Styling, theming, and interaction
+
+- [Styles](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/styles/xaml.md): Centralized style definitions.
+- [Theming](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/theming.md): Light and dark theme support.
+- [Visual states](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/visual-states.md): UI state transitions and styling.
+- [Safe area layout](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/safe-area.md): Notches, insets, and system UI overlap.
+- [Pop-ups](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/pop-ups.md): Alerts, prompts, and action sheets.
+
+## Optional
+
+- [Graphics](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/graphics/index.md): Draw custom 2D graphics.
+- [Animations](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/animation/basic.md): Basic animation patterns.
+- [Fonts](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/fonts.md): Register and use custom fonts.
diff --git a/docs/whats-new/llms.txt b/docs/whats-new/llms.txt
new file mode 100644
index 0000000000..7243b71f9d
--- /dev/null
+++ b/docs/whats-new/llms.txt
@@ -0,0 +1,74 @@
+# .NET MAUI What's New
+
+> Breaking changes, deprecations, and new APIs in .NET MAUI by release version.
+
+Use this file when answering migration questions, identifying deprecated APIs, or understanding what changed between .NET MAUI versions. For API usage guidance, follow the links to the relevant deep-dive indexes.
+
+## Guidance for AI assistants
+
+- Use `DisplayAlertAsync` and `DisplayActionSheetAsync` in .NET 10 projects; the non-`Async` overloads are removed.
+- Use `TapGestureRecognizer` instead of `ClickGestureRecognizer` — the click recognizer is removed in .NET 10.
+- Use `CollectionView` instead of `ListView`, `TableView`, or the `*Cell` types — all are deprecated in .NET 10.
+- Use `Border` instead of `Frame` — `Frame` is deprecated.
+- Recommend `WeakReferenceMessenger` from `CommunityToolkit.Mvvm` when `MessagingCenter` is used — it is internal in .NET 10.
+- Use animation `*Async` methods (`FadeToAsync`, `RotateToAsync`, etc.) — the non-`Async` variants are deprecated.
+- Enable XAML source generation with `MauiXamlInflator=SourceGen` in .NET 10 for faster Debug inflation.
+- Treat `DatePicker.Date` and `TimePicker.Time` as nullable types in .NET 10.
+- For .NET 11 preview features, refer to the .NET 11 changes page; note that APIs may change before release.
+
+## .NET 10 changes
+
+- [What's new in .NET MAUI for .NET 10](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-10.md): Full list of new APIs, deprecations, and breaking changes.
+
+### Key .NET 10 deprecations and removals
+
+| Removed/deprecated | Replacement |
+|---|---|
+| `ClickGestureRecognizer` | `TapGestureRecognizer` |
+| `Accelerator` | `KeyboardAccelerator` |
+| `ListView`, `TableView` | `CollectionView` |
+| `EntryCell`, `ImageCell`, `SwitchCell`, `TextCell`, `ViewCell` | `CollectionView` with `DataTemplate` |
+| `Frame` | `Border` |
+| `MessagingCenter` | `WeakReferenceMessenger` (CommunityToolkit.Mvvm) |
+| `Page.IsBusy` | `ActivityIndicator` |
+| `FadeTo`, `RotateTo`, etc. | `FadeToAsync`, `RotateToAsync`, etc. |
+| `Compatibility.Layout` | .NET MAUI layouts |
+| Pop-up non-`Async` overloads | `DisplayAlertAsync`, `DisplayActionSheetAsync` |
+
+### .NET 10 new capabilities summary
+
+- **XAML source generation**: `MauiXamlInflator=SourceGen` — 100x faster Debug inflation, 25% faster Release.
+- **CollectionView and CarouselView**: New handlers are now the default on iOS and Mac Catalyst.
+- **HybridWebView**: `WebResourceRequested` event for request interception; `WebViewInitializing`/`WebViewInitialized` events.
+- **DatePicker / TimePicker**: Nullable `Date` and `Time` properties.
+- **SearchBar**: `SearchIconColor` and `ReturnType` bindable properties.
+- **Switch**: `OffColor` bindable property.
+- **Picker**: Programmatic open/close API.
+- **RefreshView**: `IsRefreshEnabled` property distinct from `IsEnabled`.
+- **SearchHandler**: `ShowSoftInputAsync` / `HideSoftInputAsync`.
+- **Shell**: `NavBarVisibilityAnimationEnabled` toggle.
+- **Window (Windows)**: Enable/disable minimize and maximize buttons.
+- **Geolocation**: `IsEnabled` read-only property.
+- **Media picker**: `PickPhotosAsync` / `PickVideosAsync` with `MediaPickerOptions` (SelectionLimit, MaximumWidth, MaximumHeight, CompressionQuality, RotateImage, PreserveMetaData, Title).
+- **Layout diagnostics**: ActivitySource and Metrics under `"Microsoft.Maui"` for measure/arrange performance tracking.
+- **.NET Aspire integration**: New project template with `AddServiceDefaults`.
+
+## .NET 11 changes (preview)
+
+- [What's new in .NET MAUI for .NET 11](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-11.md): Preview features and improvements in the upcoming .NET 11 release.
+
+## .NET 9 changes
+
+- [What's new in .NET MAUI for .NET 9](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-9.md): New controls and APIs in .NET 9.
+
+## .NET 8 changes
+
+- [What's new in .NET MAUI for .NET 8](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/whats-new/dotnet-8.md): New controls and APIs in .NET 8.
+
+## Optional
+
+- [Tap gesture](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/gestures/tap.md): TapGestureRecognizer usage replacing ClickGestureRecognizer.
+- [Pointer gesture](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/gestures/pointer.md): PointerGestureRecognizer for hover and pointer events.
+- [CollectionView deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/user-interface/controls/collectionview/llms.txt): Migration from ListView.
+- [Data binding deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Compiled bindings and x:DataType.
+- [XAML deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/llms.txt): XAML source generation and compilation details.
diff --git a/docs/xaml/llms.txt b/docs/xaml/llms.txt
new file mode 100644
index 0000000000..59efcbfb6a
--- /dev/null
+++ b/docs/xaml/llms.txt
@@ -0,0 +1,50 @@
+# .NET MAUI XAML
+
+> XAML syntax, compilation, source generation, markup extensions, namespaces, and XAML-specific features for .NET MAUI.
+
+Use this file for questions about XAML syntax, `x:DataType`, markup extensions, namespace declarations, XAML compilation behavior, hot reload, or how to structure XAML pages and resources. For data binding mechanics, use the data-binding deep dive.
+
+## Guidance for AI assistants
+
+- Always declare `x:DataType` on data templates and binding-heavy pages to enable compiled bindings and catch type errors at build time.
+- Use `StaticResource` for resources defined in a `ResourceDictionary`; use `DynamicResource` only when the resource value changes at runtime.
+- Prefer `x:Name` for named elements accessed in code-behind; avoid accessing them by type traversal.
+- XAML source generation (`MauiXamlInflator=SourceGen`) is the recommended path in .NET 10 — significantly faster inflation, especially in Debug.
+- Don't use XAML compilation attributes (`[XamlCompilation]`) to disable compilation; fix the underlying XAML errors instead.
+- Namespace declarations at the root element are inherited by all child elements — declare shared namespaces once at the root.
+
+## XAML fundamentals
+
+- [XAML overview](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/index.md): XAML basics, property elements, attached properties, and when to use XAML vs code.
+- [Essential XAML syntax](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/essential-syntax.md): Property elements, attached properties, and syntax patterns.
+- [XAML markup extensions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/markup-extensions/consume.md): StaticResource, DynamicResource, Binding, RelativeSource, and x:Static.
+- [Create markup extensions](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/markup-extensions/create.md): Implement custom markup extensions.
+- [Pass arguments in XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/pass-arguments.md): x:Arguments and x:FactoryMethod for non-default constructors.
+- [Generics in XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/generics.md): x:TypeArguments for generic type instantiation.
+
+## Namespaces and compilation
+
+- [XAML namespaces](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/namespaces/index.md): Default namespace, x: prefix, clr-namespace declarations, and x:DataType.
+- [Custom namespace schemas](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/namespaces/custom-namespace-schemas.md): Map CLR namespaces to XAML namespace URIs.
+- [Custom namespace prefixes](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/namespaces/custom-prefix.md): Declare and use custom namespace prefixes.
+- [XAML compilation and source generation](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/xamlc.md): XamlC, XAML source generation (SourceGen), and per-file inflator control.
+- [Runtime load](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/runtime-load.md): Load XAML at runtime with LoadFromXaml.
+
+## XAML authoring features
+
+- [XAML hot reload](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/hot-reload.md): Live UI editing during debug sessions.
+- [Field modifiers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/field-modifiers.md): Control access level of x:Name generated fields.
+- [Class modifiers](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/class-modifiers.md): Control access level of the generated partial class.
+- [XAML security](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/xaml-security.md): Loading XAML from untrusted sources.
+
+## XAML fundamentals tutorial series
+
+- [Get started with XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/get-started.md): First XAML page and code-behind connection.
+- [Data binding basics](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/data-binding-basics.md): Binding syntax and BindingContext from XAML.
+- [Markup extensions in context](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/markup-extensions.md): Using StaticResource, x:Static, and Binding together.
+- [MVVM in XAML](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/xaml/fundamentals/mvvm.md): Connecting XAML views to MVVM viewmodels.
+
+## Optional
+
+- [Data binding deep dive](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/data-binding/llms.txt): Compiled bindings, binding modes, converters, and relative source — the binding runtime detail beyond XAML syntax.
+- [Fundamentals index](https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/fundamentals/llms.txt): App architecture, MVVM patterns, resources, and triggers.