[copilot] update instructions file (#10355)

There is a new Copilot > Configure Chat... > Generate Instructions menu in VS Code.

I let it run and update the file, and accepted the parts that looked useful.

The most important thing, it found various links to `.md` files that were broken!

This makes the file about 50% smaller, which may give @copilot more context window to work with.

Author: jonathanpeppers

.github/copilot-instructions.md

@@ -1,99 +1,35 @@
 # Instructions for AIs
 
-This repository is **.NET for Android** (formerly Xamarin.Android), the open-source bindings and tooling for Android development using .NET languages like C#.
-
-This is the main branch targeting **.NET 10**.
-
-## Repository Overview
-
-.NET for Android provides:
-- Android SDK bindings in C# (`src/Mono.Android/`)
-- MSBuild tasks for building Android apps (`src/Xamarin.Android.Build.Tasks/`)
-- Native runtime components (`src/native/`)
-- Build tooling and infrastructure (`build-tools/`)
-- Comprehensive test suite (`tests/`)
-
-### Key Directories
-- `bin/`: Build output (Debug/Release configurations)
-- `src/`: Main redistributable source code
-- `tests/`: Unit tests and integration tests
-- `build-tools/`: Build-time-only tooling
-- `external/`: Git submodules (Java.Interop, mono, etc.)
-- `Documentation/`: Project documentation
-- `eng/`: .NET Arcade SDK build infrastructure
-
-### Project Types in this Repository
-- **Android API Bindings**: C# wrappers for Android Java APIs
-- **MSBuild Tasks**: Build logic for .NET Android projects
-- **Native Libraries**: C++ runtime components using CMake
-- **Java Support Code**: Java runtime classes
-- **Build Tools**: Custom tools for build process
-- **Tests**: NUnit tests, integration tests, and device tests
-
-## Build System
-
-This repository uses:
-- **MSBuild** as the primary build system with extensive `.targets` and `.props` files
-- **[.NET Arcade SDK](https://github.com/dotnet/arcade)** for consistent .NET build infrastructure  
-- **CMake** for native C++ components
-- **Gradle** for some Android-specific build tasks
-
-Common build commands:
-- `./build.sh` or `build.cmd` - Main build
-- `./dotnet-local.sh` or `dotnet-local.cmd` - Use locally built .NET tools
-- `make` - Various make targets for specific components
-
-## Development Guidelines
-
-**Always search Microsoft documentation (MS Learn) when working with .NET, Windows, or Microsoft features, APIs, or integrations.** Use the `microsoft_docs_search` tool to find the most current and authoritative information about capabilities, best practices, and implementation patterns before making changes.
-
-## Localization Files
-
-**DO NOT modify localization files that are automatically maintained by bots and build integrations:**
-
-- **Never modify `*.lcl` files** in the `Localize/loc/` directory - these are managed by localization automation
-- **Never modify non-English `*.resx` files** (e.g., `Resources.ja.resx`, `Resources.ko.resx`, etc.) - these are auto-generated from the main English resources
-- **Only modify the main English `*.resx` files** (e.g., `Resources.resx`) when updating user-facing strings
-- The localization bots will automatically update all translated versions based on changes to the main English resources
-
-When making changes to user-facing text:
-1. Only update the main English `*.resx` files
-2. Let the automated systems handle all translations and localized files
-3. Do not manually edit translated content as it will be overwritten
-
-## Android Development Patterns
-
-### API Bindings
-- Android Java APIs are bound to C# in `src/Mono.Android/`
-- Follow existing patterns for Android namespaces (e.g., `Android.App`, `Android.Content`)
-- Use `[Register]` attributes for Java type registration
-
-### MSBuild Integration
-- Build tasks extend `Microsoft.Build.Utilities.Task` or related base classes
-- Place custom MSBuild logic in `src/Xamarin.Android.Build.Tasks/Tasks/`
-- Follow existing error code patterns (e.g., `XA####` for errors, `XA####` for warnings)
-- Support incremental builds where possible
-- Follow patterns in [`Documentation/guides/MSBuildBestPractices.md`](Documentation/guides/MSBuildBestPractices.md)
-
-### Native Code
-- C++ code uses CMake build system
-- Native libraries are in `src/native/`
-- Follow Android NDK patterns and conventions
-- Use proper JNI patterns for Java interop
-
-### Testing Patterns
-- Unit tests go in `tests/` directory
-- Device integration tests in `tests/MSBuildDeviceIntegration/`
-- Use NUnit for C# tests
-- Mock Android APIs appropriately for unit testing
-- Follow patterns in [`Documentation/workflow/UnitTests.md`](Documentation/workflow/UnitTests.md) for comprehensive testing guidance
-
-### Development and Debugging
-- Use `MSBUILDDEBUGONSTART=2` environment variable to debug MSBuild tasks
-- Follow patterns in [`Documentation/workflow/DevelopmentTips.md`](Documentation/workflow/DevelopmentTips.md)
-- Use update directories for rapid testing of Debug builds on devices
-- Utilize `dotnet test --filter` for running specific unit tests
-- Reference [`Documentation/workflow/MSBuildBestPractices.md`](Documentation/workflow/MSBuildBestPractices.md) for MSBuild debugging techniques
+**.NET for Android** (formerly Xamarin.Android) - Open-source Android development bindings for .NET languages. `main` branch targets **.NET 10**.
+
+## Architecture
+- `src/Mono.Android/` - Android SDK bindings in C#
+- `src/Xamarin.Android.Build.Tasks/` - MSBuild tasks for Android apps  
+- `src/native/` - Native runtime (MonoVM/CoreCLR/NativeAOT)
+- `external/Java.Interop/` - JNI bindings and Java-to-.NET interop
+- `tests/` - NUnit tests, integration tests, device tests
+
+**Build System:** MSBuild + .NET Arcade SDK + CMake (native)
+
+## Essential Commands
+- **Build:** `./build.sh` or `build.cmd`
+- **Test with local build:** `dotnet-local.sh`/`dotnet-local.cmd` 
+- **Run tests:** `dotnet-local.cmd test bin/TestDebug/net9.0/Xamarin.Android.Build.Tests.dll --filter Name~TestName`
+- **Device tests:** `dotnet-local.cmd test bin/TestDebug/MSBuildDeviceIntegration/net9.0/MSBuildDeviceIntegration.dll`
+
+## Critical Rules
+
+**Only modify the main English `*.resx` files** (e.g., `Resources.resx`)
+
+**Never modify non-English localization files:** `*.lcl` files in `Localize/loc/` or non-English `*.resx` files are auto-generated.
+
+**Use Microsoft docs:** Search MS Learn before making .NET, Windows, or Microsoft features, APIs, or integrations. Use the `microsoft_docs_search` tool.
+
+**MSBuild Tasks:** Extend `AndroidTask` base class, use `XA####` error codes, test in isolation.
+
+**API Bindings:** Use `[Register]` attributes, follow `Android.*` namespace patterns.
+
+**Native Code:** Use CMake, handle multiple ABIs (arm64-v8a, armeabi-v7a, x86_64, x86).
 
 ## Nullable Reference Types
 
@@ -187,23 +123,11 @@ if (!UncompressedFileExtensions.IsNullOrWhiteSpace ()) {
 
 ## Formatting
 
-C# code uses tabs (not spaces) and the Mono code-formatting style defined in `.editorconfig`
-
-* Your mission is to make diffs as absolutely as small as possible, preserving existing code formatting.
-
-* If you encounter additional spaces or formatting within existing code blocks, LEAVE THEM AS-IS.
-
-* If you encounter code comments, LEAVE THEM AS-IS.
-
-* Place a space prior to any parentheses `(` or `[`
-
-* Use `""` for empty string and *not* `string.Empty`
-
-* Use `[]` for empty arrays and *not* `Array.Empty<T>()`
-
-* Do *NOT* leave random empty lines when removing code.
-
-Examples of properly formatted code:
+C# code uses tabs (not spaces) and Mono style (`.editorconfig`):
+- Preserve existing formatting and comments
+- Space before `(` and `[`: `Foo ()`, `array [0]`
+- Use `""` not `string.Empty`, `[]` not `Array.Empty<T>()`
+- Minimal diffs - don't leave random empty lines
 
 ```csharp
 Foo ();
@@ -221,99 +145,25 @@ try {
 }
 ```
 
-## Error and Warning Patterns
-
-### Error Codes
-- Use `XA####` for MSBuild errors (e.g., `XA1234`)
-- Use `XA####` for MSBuild warnings  
-- Use `APT####` for Android Asset Packaging Tool errors
-- Include clear, actionable error messages
-- Reference documentation when available
-
-### Logging
-- Use MSBuild logging (`Log.LogError`, `Log.LogWarning`, `Log.LogMessage`)
-- Every `LogCodedWarning` and `LogCodedError` needs an error/warning code
-- Include relevant context (file paths, line numbers when available)
-- Make error messages helpful for developers
-
-## Documentation Patterns
+## Error Patterns
+- **MSBuild Errors:** `XA####` (errors), `XA####` (warnings), `APT####` (Android tools)
+- **Logging:** Use `Log.LogError`, `Log.LogWarning` with error codes and context
 
-### Code Documentation
-- Use XML documentation comments for public APIs
-- Document Android API level requirements where relevant
-- Include `<example>` tags for complex APIs
-- Reference official Android documentation where helpful:
-  - [Android Developer Guide](https://developer.android.com/develop)
-  - [Android API Reference](https://developer.android.com/reference)
-
-### Project Documentation
-- Update relevant `.md` files in `Documentation/` when making significant changes
-- Follow existing documentation structure and formatting
-- Include code examples that actually work
-
-## Commit Message Guidelines
-
-Follow the patterns in `Documentation/workflow/commit-messages.md`:
-
-### Summary Format
+## Commit Format
 ```
 [Component] Summary
 ```
+Components: `[Mono.Android]`, `[Build.Tasks]`, `build`, `ci`, `docs`, `tests`
 
-Where Component is either:
-- Directory name (e.g., `[Mono.Android]`, `[Build.Tasks]`)
-- Broad category: `build`, `ci`, `docs`, `tests`
-
-### Dependency Bumps
 ```
 Bump to org/repo/branch@commit
 Bump to [Dependency Name] [Dependency Version]
 ```
 
-### Required Sections
-- **Changes**: What was modified
-- **Fixes**: Issues resolved (include GitHub issue numbers)
-- **Context**: Why the change was needed
-
-## Common Troubleshooting
-
-### Build Issues
-- Clean `bin/` and `obj/` directories
-- Ensure Android SDK/NDK are properly configured
-- Use `make clean` for complete rebuild
-
-### MSBuild Task Development
-- Test tasks in isolation first
-- Handle incremental build scenarios
-- Consider cross-platform compatibility (Windows/macOS/Linux)
-- Validate inputs and provide clear error messages
-- Use `MSBUILDDEBUGONSTART=2` for debugging MSBuild tasks
-
-### Device Testing
-- Use `tests/MSBuildDeviceIntegration/` for comprehensive device tests
-- Leverage update directories for rapid iteration on Debug builds
-- Use `dotnet test --filter` to run specific tests
-- Ensure proper Android emulator/device setup for testing
-
-### Performance and Diagnostics
-- Use profiling capabilities documented in [`Documentation/guides/profiling.md`](Documentation/guides/profiling.md)
-- Leverage tracing features documented in [`Documentation/guides/tracing.md`](Documentation/guides/tracing.md)
-- Monitor build performance and optimize accordingly
-
-### Native Development
-- Use appropriate CMake patterns from existing code
-- Handle different Android ABIs (arm64-v8a, armeabi-v7a, x86_64, x86)
-- Note: Native CoreCLR components in `src/native/clr` only target 64-bit platforms (arm64-v8a, x86_64)
-- Follow Android NDK security best practices
-- Test on multiple Android API levels when relevant
-
-### Android API Management
-- Follow [`Documentation/workflow/HowToAddNewApiLevel.md`](Documentation/workflow/HowToAddNewApiLevel.md) for adding new Android API levels
-- Use existing patterns for Java-to-C# API bindings
-- Understand Android backward/forward compatibility requirements
-
-## Contributing Guidelines
-
-### Updating AI Instructions
-- Always update `copilot-instructions.md` when making changes that would affect how AI assistants should work with the codebase
-- This includes new patterns, conventions, build processes, or significant structural changes
+Required sections: **Changes**, **Fixes** (#issue-numbers), **Context**
+
+## Troubleshooting
+- **Build:** Clean `bin/`+`obj/`, check Android SDK/NDK, `make clean`
+- **MSBuild:** Test in isolation, validate inputs
+- **Device:** Use update directories for rapid Debug iteration
+- **Performance:** See `../Documentation/guides/profiling.md` and `../Documentation/guides/tracing.md`