Add location-gated agent guidance

Add repository-wide instructions and scoped guidance for every source project, with Copilot using the root file as the canonical entry point.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: aaee9aa5-4a14-4da6-bf12-c8948e58e21c

Author: Nigusu-Allehu

.github/copilot-instructions.md

@@ -1,29 +1,5 @@
 # NuGet.Client Copilot instructions
 
-NuGet.Client is the .NET codebase for NuGet's client tooling and libraries across Visual Studio, the .NET CLI, MSBuild, and `nuget.exe`.
-
-## Development environment
-
-- Build and test only the projects relevant to the change.
-- On Windows:
-  - Run `.\configure.ps1` before the first build.
-  - Build with the `dotnet` or `msbuild` CLI.
-- On Linux and macOS:
-  - Run `. ./configure.sh` before the first build. It must be sourced, not executed.
-  - Build with `dotnet`, or run `./build.sh` to build all the cross-platform projects. Avoid building `NuGet.sln`, since it includes a few Windows-only projects.
-- Run `dotnet test` to execute tests. Use `--filter` to run a subset.
-- Use NuGet Central Package Management: declare package versions in `Directory.Packages.props` and add versionless `PackageReference` items to project files. Read the [package-update guidance](../docs/updating-packages.md) before changing dependency versions.
-
-## Task-specific guidance
-
-Before implementing code changes, identify and read the guidance relevant to the task. In particular:
-
-- For new features and behavior changes, read the [feature guide](../docs/feature-guide.md), including its requirements for feature configuration, `SdkAnalysisLevel` gating, and restore and pack considerations.
-- For public API additions, changes, removals, or shipping, read the [NuGet SDK guidance](../docs/nuget-sdk.md).
-- For C# implementation and error-handling patterns, read the [C# conventions and guidelines](agent_docs/csharp.md).
-- For localized resources, read the [localization guidance](agent_docs/localization.md).
-- For nullable migrations, read the [nullable migration guidance](agent_docs/nullable-migrations.md).
-- For performance measurements, read the [benchmarking guidance](agent_docs/benchmarking.md).
-- Before creating a branch or pull request, read the [Git and pull request guidance](agent_docs/git-workflow.md).
-
-The repository's broader development documentation is indexed in [CONTRIBUTING.md](../CONTRIBUTING.md).
+Read and follow [`../AGENTS.md`](../AGENTS.md) before making changes.
+The root file is the canonical repository-wide guidance; the nearest nested
+`AGENTS.md` applies additional instructions for files in its subtree.

AGENTS.md

@@ -0,0 +1,64 @@
+# NuGet.Client agent instructions
+
+NuGet.Client is the .NET codebase for NuGet tooling and libraries used by
+Visual Studio, the .NET CLI, MSBuild, and `nuget.exe`.
+
+## Scope and precedence
+
+- These instructions apply to the entire repository.
+- Read and follow the nearest nested `AGENTS.md` for the files being changed.
+- Preserve user changes and do not modify unrelated files.
+- Prefer the smallest complete change that addresses the root cause.
+
+## Before making changes
+
+1. Inspect the affected projects and tests, and search for existing patterns
+   before adding new helpers or abstractions.
+2. Read the guidance relevant to the task:
+
+   | Change | Required guidance |
+   | --- | --- |
+   | New feature or behavior change | [`docs/feature-guide.md`](docs/feature-guide.md) |
+   | Public API change | [`docs/nuget-sdk.md`](docs/nuget-sdk.md) |
+   | C# implementation | [`.github/agent_docs/csharp.md`](.github/agent_docs/csharp.md) |
+   | Localization | [`.github/agent_docs/localization.md`](.github/agent_docs/localization.md) |
+   | Nullable migration | [`.github/agent_docs/nullable-migrations.md`](.github/agent_docs/nullable-migrations.md) |
+   | Performance measurement | [`.github/agent_docs/benchmarking.md`](.github/agent_docs/benchmarking.md) |
+   | Dependency update | [`docs/updating-packages.md`](docs/updating-packages.md) |
+   | Branch or pull request | [`.github/agent_docs/git-workflow.md`](.github/agent_docs/git-workflow.md) |
+
+3. Use [`CONTRIBUTING.md`](CONTRIBUTING.md) as the index for broader
+   development documentation.
+
+## Implementation rules
+
+- Follow existing project conventions and reuse established test utilities.
+- Add or update tests when behavior changes.
+- Consider all affected NuGet surfaces: Visual Studio, `dotnet`, MSBuild,
+  `nuget.exe`, restore, and pack. Change only the surfaces relevant to the task.
+- Follow `SdkAnalysisLevel` and feature-configuration requirements for new
+  behavior.
+- Keep public API files accurate when changing public surface area.
+- Declare package versions in `Directory.Packages.props`; project
+  `PackageReference` items must be versionless.
+- Do not edit generated localization `.xlf` files manually. Edit the `.resx`
+  and build the owning project to regenerate dependent files.
+
+## Build and test
+
+- Configure once before the first build:
+  - Windows: `.\configure.ps1`
+  - Linux or macOS: `. ./configure.sh`
+- Build only the projects relevant to the change with `dotnet` or `msbuild`.
+- On Linux and macOS, do not build `NuGet.sln`; it contains Windows-only
+  projects. Use `./build.sh` when a broader cross-platform build is needed.
+- Run the smallest relevant tests with `dotnet test`, using `--filter` when
+  possible.
+- Before submitting a pull request, run:
+  `dotnet format whitespace --verify-no-changes NuGet.sln`
+
+## Completion
+
+- Ensure source, tests, public API files, generated artifacts, and directly
+  related documentation remain consistent.
+- Report the files changed and the exact validation performed.

src/NuGet.Clients/NuGet.CommandLine/AGENTS.md

@@ -0,0 +1,38 @@
+# NuGet.CommandLine Agent Scope
+
+## Architecture
+
+NuGet.CommandLine is a single Windows desktop executable (`NuGet.exe`) using MEF for command composition and ILRepack for binary merging. Commands are discovered via `[Import]`/`[ImportMany]` attributes (CommandManager.cs). Extensions load from `%LocalAppData%\NuGet\{Commands,CredentialProviders}` or paths set via environment variables `NUGET_EXTENSIONS_PATH` and `NUGET_CREDENTIALPROVIDERS_PATH`.
+
+**Supported Windows versions:** Windows 7, 8, 8.1, 10 (app.manifest).
+**Build target:** .NET Framework 4.6.2+.
+**Output:** ILRepack-merged executable with embedded localized satellites (13 languages).
+
+## High-Risk Invariants
+
+1. **ILRepack determinism**: Binary merge order is significant; NuGet.Core.dll must be last (ilmerge.props, csproj). Test: `dotnet build src\NuGet.Clients\NuGet.CommandLine\NuGet.CommandLine.csproj`
+2. **Localization satellites**: Embedded resource DLLs only in CI builds (csproj); local debug builds skip them.
+3. **Extension discovery order**: Environment variables checked before default paths; tests must disable extensions via `Program.IgnoreExtensions = true`.
+4. **Command lookup**: Case-insensitive prefix matching with ambiguity detection (CommandManager.GetCommand); exact matches preferred.
+
+## Test Execution
+
+**Unit tests:**
+```cmd
+dotnet test test\NuGet.Clients.Tests\NuGet.CommandLine.Test\NuGet.CommandLine.Test.csproj --filter "Category!=Integration"
+```
+
+**Functional tests:**
+```cmd
+dotnet test test\NuGet.Clients.FuncTests\NuGet.CommandLine.FuncTest\NuGet.CommandLine.FuncTest.csproj
+```
+
+**Extension loading tests:** Verify SampleCommandLineExtensions (TestExtensions directory) is copied to test output before running extension-related tests.
+
+## Build
+
+```cmd
+dotnet build src\NuGet.Clients\NuGet.CommandLine\NuGet.CommandLine.csproj
+```
+
+Produces `bin/Configuration/net462/NuGet.exe` (pre-merge); post-build target `ILMergeNuGetExe` produces `artifacts/NuGet.exe`.

src/NuGet.Clients/NuGet.Console/AGENTS.md

@@ -0,0 +1,34 @@
+# NuGet.Console Agent Scoping
+
+## Ownership
+`src\NuGet.Clients\NuGet.Console\` — VSIX-bundled PowerShell console UI for Package Manager (WPF, .NET Framework only).
+
+## Architecture Invariants
+- **MEF Composition**: Exports `IPowerConsoleWindow`, `IWpfConsoleService`, `IScriptExecutor` via `[Export]` attributes; multi-host via `[ImportMany] IHostProvider`.
+- **UI-Thread Gating**: All cross-process calls marshal via `NuGetUIThreadHelper.JoinableTaskFactory` and VS `ThreadHelper.ThrowIfNotOnUIThread()`. Violations cause deadlock/hang.
+- **PowerShell 3.x Host**: `ScriptExecutor` wraps init.ps1 execution; async events trigger console prompt refresh. `IPSNuGetProjectContext` bridges PS session state.
+- **Output Interop**: `OutputConsole` (non-blocking) and `BuildOutputConsole` write to VS Output pane via `IVsOutputWindow` — thread-safe by AsyncLazy marshaling.
+- **Dispatcher Concurrency**: `ConsoleDispatcher` uses `BlockingCollection<VsKeyInfo>` for input buffering; `ConcurrentDictionary` tracks init.ps1 per-package state.
+
+## High-Risk Edits
+- Change `AsyncLazy` initialization pattern → UI hangs.
+- Remove JoinableTaskFactory marshaling → cross-thread access violation.
+- Modify MEF metadata/export names → composition fails silently.
+- Add Thread.Sleep or blocking I/O in dispatcher → keyboard unresponsive.
+
+## Matching Tests
+- **Unit**: `test\NuGet.Clients.Tests\NuGetConsole.Host.PowerShell.Test\` — cmdlet + runspace tests.
+- **Contract**: `test\NuGet.Tests.Apex\NuGet.Console.TestContract\` — APEX integration tests (requires VS).
+- **Logger**: `test\NuGet.Clients.Tests\NuGet.VisualStudio.Common.Test\OutputConsoleLoggerTests*.cs` — output pane logging.
+
+## Validation Commands
+```
+dotnet build src\NuGet.Clients\NuGet.Console\NuGet.Console.csproj
+dotnet test test\NuGet.Clients.Tests\NuGetConsole.Host.PowerShell.Test\ --logger=console
+dotnet build /p:IncludeInVSIX=true src\NuGet.Clients\NuGet.Console\NuGet.Console.csproj
+```
+
+## Dependencies
+- `Microsoft.VisualStudio.Sdk`, `Microsoft.PowerShell.3.ReferenceAssemblies`
+- `NuGet.PackageManagement.UI`, `NuGet.VisualStudio` (transitive)
+- Win-only; requires VS 2015+; no Mono/CoreCLR support.

src/NuGet.Clients/NuGet.Indexing/AGENTS.md

@@ -0,0 +1,51 @@
+# NuGet.Indexing
+
+Package search indexing and ranking for Visual Studio client.
+
+## Architecture
+
+**Query Flow**: Query string → NuGetQuery.MakeQuery() → Lucene BooleanQuery
+- Field keywords: `id`, `version`, `title`, `description`, `tag/tags`, `author/authors`, `summary`, `owner/owners`
+- Quoted phrases supported; unquoted tokens become wildcard
+
+**Indexing**: PackageAnalyzer wraps field-specific analyzers
+- `Id`, `TokenizedId`, `ShingledId`: IdentifierKeywordAnalyzer, IdentifierAnalyzer
+- `Title`, `Description`, `Summary`, `Authors`: DescriptionAnalyzer
+- `Version`: VersionAnalyzer (semantic)
+- `Tags`: TagsAnalyzer; `Owner`: OwnerAnalyzer
+
+**Ranking Pipeline**
+1. RelevanceSearchResultsIndexer.Rank() creates in-memory Lucene index from IPackageSearchMetadata entries
+2. Executes query, scores results, maps by package ID to rank dict
+3. ProcessUnrankedEntries() fills gaps: unranked entries inherit prior ranked entry's rank, fallback to -1
+
+**Result Aggregation**: SearchResultsAggregator merges multiple search results
+- Requires ISearchResultsIndexer (ranking) + IPackageSearchMetadataSplicer (merge strategy)
+- Preserves input relative order per feed; re-ranks merged set
+
+## High-Risk Invariants
+
+**PackageSearchMetadataSplicer.MergeEntries(lhs, rhs)**
+- Throws InvalidOperationException if lhs.Identity.Id ≠ rhs.Identity.Id (case-insensitive)
+- Picks newer version as base; merges version lists via GetVersionsAsync()
+- Validates before merge; no partial state on exception
+
+**RelevanceSearchResultsIndexer.Rank()**
+- Lucene RAMDirectory is in-memory only; index lifecycle tied to indexer call
+- Ranking dict uses case-sensitive package IDs (retrieved from Lucene Field "Id")
+- Default rank for unranked entries: -1
+
+## Build & Test
+
+```powershell
+# Build
+dotnet build src\NuGet.Clients\NuGet.Indexing\NuGet.Indexing.csproj
+
+# Test all
+dotnet test test\NuGet.Clients.Tests\NuGet.Indexing.Test\NuGet.Indexing.Test.csproj -v normal
+
+# Test by name
+dotnet test test\NuGet.Clients.Tests\NuGet.Indexing.Test\NuGet.Indexing.Test.csproj --filter MergeEntries_WithDifferentPackageIds_Throws
+dotnet test test\NuGet.Clients.Tests\NuGet.Indexing.Test\NuGet.Indexing.Test.csproj --filter AggregateAsync_MergesVersions
+dotnet test test\NuGet.Clients.Tests\NuGet.Indexing.Test\NuGet.Indexing.Test.csproj --filter ProcessUnrankedEntries_FillsWithDefaultRank
+```

src/NuGet.Clients/NuGet.MSSigning.Extensions/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md: NuGet.MSSigning.Extensions
+
+**Scope:** `src\NuGet.Clients\NuGet.MSSigning.Extensions`
+
+## Architecture
+- **Commands:** `MSSignCommand` (author signing), `RepoSignCommand` (repo signing)
+- **Base:** `MSSignAbstract` — validates X.509 cert fingerprints (SHA-256/384/512), retrieves RSA private key via `CngProvider`
+- **Output:** ILMerge'd `NuGet.Mssign.exe` from 34 dependent assemblies (see `ilmerge.props`)
+- **Framework:** net472 | **Shipping:** true | **Sign:** Microsoft key + delay-sign
+
+## High-Risk Invariants
+- **CNG Provider constraint** (MSSignAbstract.cs): `CngKey.Open(keyContainer, provider, CngKeyOpenOptions.MachineKey)` requires Windows registry/HSM. Cross-platform tests must skip.
+- **Cert validation** (MSSignAbstract.cs): SHA-1 fingerprints rejected; deduction logic skips SHA-1 branch only for Thumbprint match.
+- **ILMerge post-build** (NuGet.MSSigning.Extensions.csproj): Runs only when `BuildingInsideVisualStudio != 'true'`. SignWithMicrosoftKey enforced via delay-sign keyfile.
+
+## Matching Tests
+| Type | Project Path | Entry Tests |
+|------|--------------|-------------|
+| Unit | `test\NuGet.Clients.Tests\NuGet.MSSigning.Extensions.Test` | `NuGetMSSignCommandTest.cs`, `NuGetReposignCommandTest.cs` |
+| Functional | `test\NuGet.Clients.FuncTests\NuGet.MSSigning.Extensions.FuncTest` | `MSSignCommandTests.cs`, `ReposignCommandTests.cs` |
+
+## Validation Commands
+```batch
+:: Build extension DLL and ILMerge executable
+dotnet build src\NuGet.Clients\NuGet.MSSigning.Extensions\NuGet.MSSigning.Extensions.csproj
+
+:: Unit tests (cross-platform compatible)
+dotnet test test\NuGet.Clients.Tests\NuGet.MSSigning.Extensions.Test --logger:console
+
+:: Functional tests (Windows + admin required; modifies LocalMachine\Root cert store)
+dotnet test test\NuGet.Clients.FuncTests\NuGet.MSSigning.Extensions.FuncTest --logger:console
+
+:: Verify ILMerge artifact
+powershell -NoProfile -Command "Test-Path artifacts\VSIX\NuGet.Mssign.exe"
+```

src/NuGet.Clients/NuGet.PackageManagement.PowerShellCmdlets/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md: NuGet.PackageManagement.PowerShellCmdlets
+
+**Owns:** Package Manager Console PowerShell host + 9 NuGet cmdlets (Find-Package, Get-Package, Install-Package, Update-Package, Uninstall-Package, Add-BindingRedirect, Get-Project, Sync-Package, Tab Expansion).
+
+**Target Framework:** net472 only (no cross-platform). PowerShell 2.0+ manifest. Visual Studio-bound via DTE automation.
+
+## High-Risk Invariants
+
+1. **Runspace Threading Lock (net472 only):**
+   - RunspaceDispatcher.WithLock() uses SemaphoreSlim(1,1) + [ThreadStatic] IHaveTheLock
+   - All pipeline invocations (sync/async) must serialize through this lock
+   - **Violation:** Direct Runspace.Invoke() outside WithLock = deadlock or race
+   - **Validation:** dotnet build src\NuGet.Clients\NuGet.PackageManagement.PowerShellCmdlets\NuGet.PackageManagement.PowerShellCmdlets.csproj -c Release
+
+2. **Satellite Assembly Generation:**
+   - 13 XLF files → satellite DLLs via GenerateSatelliteAssembliesForCore=true
+   - Missing XLF = missing language pack
+   - Build the project to regenerate and validate satellite assemblies.
+
+3. **Manifest Module Update:**
+   - Post-build target runs UpdateNuGetModuleManifest.ps1 to patch NuGet.psd1 with runtime FullName
+   - Script validates **exactly one** occurrence of 'NuGet.PackageManagement.PowerShellCmdlets.dll' and fails on mismatch
+   - **Validation:** Build output captures manifest patching success
+
+4. **UI Thread Barrier:**
+   - ThreadHelper.ThrowIfOnUIThread() enforces runspace operations off-UI-thread
+   - Cmdlet base class (NuGetPowerShellBaseCommand) must not call UI methods directly
+   - **Validation:** Code review + test fixture usage
+
+## Matching Tests
+
+**Project:** `test\NuGet.Clients.Tests\NuGetConsole.Host.PowerShell.Test\`
+**Test Commands:**
+- dotnet test test\NuGet.Clients.Tests\NuGetConsole.Host.PowerShell.Test\NuGetConsole.Host.PowerShell.Test.csproj -c Release --logger "console;verbosity=detailed"
+- Filter by fixture: --filter "GetPackageCommandTests"
+
+**Key Fixtures:**
+- CmdletRunspaceFixture (isolated runspace, minimal PSHost)
+- GetPackageCommandTests, FindPackageCommandTests (async cmdlet execution)
+
+## Build & Validation
+
+```powershell
+# Full build
+dotnet build src\NuGet.Clients\NuGet.PackageManagement.PowerShellCmdlets\NuGet.PackageManagement.PowerShellCmdlets.csproj -c Release
+
+# Test coverage
+dotnet test test\NuGet.Clients.Tests\NuGetConsole.Host.PowerShell.Test\NuGetConsole.Host.PowerShell.Test.csproj -c Release
+
+# Verify satellite assemblies
+Get-ChildItem src\NuGet.Clients\NuGet.PackageManagement.PowerShellCmdlets\bin\Release\net472\*/NuGet.PackageManagement.PowerShellCmdlets.resources.dll
+```
+
+## Constraints & Assumptions
+
+- **No async/await in cmdlet implementations:** BlockingCollection + Semaphore enforce sync dispatch
+- **Localization immutable post-build:** XLF files frozen; manifest auto-patches only assembly identity
+- **Test isolation:** CmdletRunspaceFixture creates fresh runspace per test (no state leakage)

src/NuGet.Clients/NuGet.PackageManagement.UI/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md: NuGet.PackageManagement.UI
+
+**Scope:** `src\NuGet.Clients\NuGet.PackageManagement.UI` — Visual Studio Package Manager UI, tool windows, dialogs, package metadata.
+
+## Architecture
+
+- **PackageManagerControl**: Main WPF UserControl (IVsWindowSearch, IPackageManagerControlViewModel)
+- **PackageManagerToolWindowPane**: VS ToolWindowPane host (IVsWindowFrameNotify3)
+- **Threading Model**: Mandatory `NuGetUIThreadHelper.JoinableTaskFactory` for all async operations
+  - RunAsync() for fire-and-forget background tasks
+  - SwitchToMainThreadAsync() for UI marshaling
+  - Run() for sync-over-async blocking
+- **XAML Layers**: 32 XAML files (controls, dialogs, indicators); theme/brush resources via DynamicResource
+- **Accessibility**: Custom AutomationPeers (ButtonHyperlinkAutomationPeer, ToggleableItemAutomationPeer implementing IToggleProvider)
+- **Localization**: 13 XLF satellite resources; Resources.resx with PublicResXFileCodeGenerator; T4 template for PackageIconMonikers
+- **Target**: .NET Framework (NETFXTargetFramework); requires PresentationFramework, System.Runtime.Caching
+- **Tests**: test\NuGet.Clients.Tests\NuGet.PackageManagement.UI.Test with WpfFactAttribute/WpfTheoryAttribute custom xunit discoverers
+
+## High-Risk Invariants
+
+1. **All background operations must use NuGetUIThreadHelper.JoinableTaskFactory**: Failure causes UI thread hangs or race conditions in VS event handlers.
+2. **No direct ThreadPool.QueueUserWorkItem or Task.Run without JoinableTaskFactory**: Blocks VS shutdown and breaks modal dialogs.
+3. **AutomationPeer implementations must preserve inheritance chain**: Custom peers override CreateItemAutomationPeer() to ensure accessibility tree consistency.
+4. **XAML resources must use ImageThemingUtilities for theme colors**: Missing themes break dark/light mode transitions.
+5. **Localization is generated from Resources.resx**: Edit the `.resx`, then build the project to regenerate the designer and `.xlf` files.
+
+## Build & Test Commands
+
+```powershell
+# Build
+dotnet build src\NuGet.Clients\NuGet.PackageManagement.UI\NuGet.PackageManagement.UI.csproj -c Release
+
+# Run all UI tests
+dotnet test test\NuGet.Clients.Tests\NuGet.PackageManagement.UI.Test\NuGet.PackageManagement.UI.Test.csproj --no-build
+
+# Run specific WPF test
+dotnet test test\NuGet.Clients.Tests\NuGet.PackageManagement.UI.Test\NuGet.PackageManagement.UI.Test.csproj --filter "FullyQualifiedName~PackageItemLoaderTests" --no-build
+```