Optimize Copilot instructions for clarity and maintainability

.github/copilot-instructions.md

@@ -1,75 +1,67 @@
 # Copilot Instructions for Dev Proxy
 
 ## Overview
-Dev Proxy is a cross-platform .NET API simulator and proxy for testing how applications handle API failures, rate limits, latency, and more. It is highly extensible via a plugin architecture and is configured using JSON files. The project is organized as a multi-project .NET solution.
-
-**Key technologies:**
-- Uses a fork of Titanium.Web.Proxy: [svrooij/unobtanium-web-proxy](https://github.com/svrooij/unobtanium-web-proxy)
-- CLI built with System.CommandLine
-- .NET Dependency Injection is used throughout
-
-## Architecture
-- **Main entry point:** `DevProxy/Program.cs` sets up the web host, loads configuration, logging, and plugins, and starts the proxy engine.
-- **Proxy Engine:** `DevProxy/Proxy/ProxyEngine.cs` manages network interception, request/response handling, plugin invocation, and system proxy integration.
-- **Plugins:** Implement the `IPlugin` interface (`DevProxy.Abstractions/Plugins/IPlugin.cs`). For most plugins, inherit from `BasePlugin` or `BaseReportingPlugin` in `DevProxy.Abstractions/Plugins/`. Plugins are loaded dynamically based on configuration in `devproxyrc.json` or similar config files. Plugins can:
-  - Intercept and modify requests/responses
-  - Add custom commands/options to the CLI (via System.CommandLine)
-  - React to events (recording, logging, etc.)
-- **Configuration:**
-  - Main config: `DevProxy/config/devproxyrc.json` (or other JSON files in `config/`)
-  - Plugins and URLs to watch are defined here. See `m365.json` for examples.
-- **Commands:**
-  - CLI commands are defined in `DevProxy/Commands/` and registered via `DevProxyCommand.cs` (using System.CommandLine).
-  - Certificate management: `cert ensure` and `cert remove` (see `CertCommand.cs`).
-- **Cross-platform support:**
-  - macOS-specific scripts: `trust-cert.sh`, `remove-cert.sh`, `toggle-proxy.sh` in `DevProxy/`.
-
-## Dev Proxy MCP Server
-- The Dev Proxy MCP server exposes access to Dev Proxy documentation and JSON schemas, making it invaluable for both contributors and users.
-- Use the MCP server to programmatically retrieve up-to-date docs and schema definitions for config and plugins.
-- See: [@devproxy/mcp on npm](https://www.npmjs.com/package/@devproxy/mcp)
-
-## Developer Workflows
-- **Build:** Use the VS Code task `build` or run `dotnet build DevProxy.sln`.
-- **Run:** Use the VS Code task `watch` or run `dotnet watch run --project DevProxy.sln`.
-- **Publish:** Use the VS Code task `publish` or run `dotnet publish DevProxy.sln`.
-- **Debug:** Attach to the running process or use `dotnet watch run` for hot reload.
-- **Test:** (No test project detected; add tests in `tests/` if needed.)
-
-## Project Conventions
-- **Plugin loading:** Plugins must be registered in the config file and implement `IPlugin` (preferably via `BasePlugin` or `BaseReportingPlugin`). Use the `PluginServiceExtensions` for registration logic.
-- **URL matching:** URLs to watch are defined as wildcards in config and converted to regexes at runtime.
-- **Logging:** Uses Microsoft.Extensions.Logging. Log levels and output are configurable.
-- **Configuration tokens:** Paths in config can use `~appFolder` for resolution.
-- **Hotkeys:** When running interactively, hotkeys are available (see console output for details).
-- **Schema validation:** Config files reference a `$schema` for validation and versioning.
-- **CLI:** All CLI commands and options are built using System.CommandLine.
-- **Dependency Injection:** All services, plugins, and commands are registered and resolved via .NET DI.
-
-## Key Files & Directories
-- `DevProxy/Program.cs` — Main entry
-- `DevProxy/Proxy/ProxyEngine.cs` — Core proxy logic
-- `DevProxy/Commands/` — CLI commands (System.CommandLine)
-- `DevProxy/Plugins/` — Plugin loader and helpers
-- `DevProxy.Abstractions/Plugins/IPlugin.cs` — Plugin interface
-- `DevProxy.Abstractions/Plugins/BasePlugin.cs`, `BaseReportingPlugin.cs` — Plugin base classes
-- `DevProxy/config/` — Example and default configs
-- `media/` — Branding assets
-- `scripts/` — Local build/setup scripts
-
-## External Dependencies
-- [svrooij/unobtanium-web-proxy](https://github.com/svrooij/unobtanium-web-proxy) — Core proxy engine (fork of Titanium.Web.Proxy)
-- Microsoft.Extensions.* — Logging, configuration, DI
-- System.CommandLine — CLI framework
-
-## Examples
-- To add a new plugin, inherit from `BasePlugin` or `BaseReportingPlugin`, implement `IPlugin`, and register it in the config file under `plugins`.
-- To add a new CLI command, implement a `Command` in `DevProxy/Commands/` and register it in `DevProxyCommand.cs`.
+
+Dev Proxy is a cross-platform .NET API simulator and proxy for testing how applications handle API failures, rate limits, latency, and more.
+
+## Critical (Non-Obvious)
+
+- **Proxy engine:** Uses [svrooij/unobtanium-web-proxy](https://github.com/svrooij/unobtanium-web-proxy) (fork of Titanium.Web.Proxy)
+- **Config tokens:** Paths in config files can use `~appFolder` for resolution
+- **MCP Server:** Use [@devproxy/mcp](https://www.npmjs.com/package/@devproxy/mcp) to programmatically retrieve up-to-date docs and JSON schemas
+
+## Best Practices
+
+See the comprehensive best practices guide: https://raw.githubusercontent.com/dev-proxy-tools/mcp/refs/heads/main/assets/best-practices.md
+
+Key points:
+- Store Dev Proxy files in `.devproxy` folder in the workspace
+- Schema version in `$schema` must match installed Dev Proxy version
+- In config files: `plugins` first, then `urlsToWatch`, then plugin configs
+- Plugin order matters: latency plugins first, response simulators before reporters, reporters last
+- URL matching is order-dependent: most specific URLs first, use `!` prefix to exclude
+- File paths are relative to the config file where they're defined
+- Hot reload (v2.1.0+): config changes are detected and the proxy restarts automatically to apply them
+
+## Plugin Development
+
+To create a new plugin:
+1. Implement the `IPlugin` interface (`DevProxy.Abstractions/Plugins/IPlugin.cs`) either directly or by inheriting from `BasePlugin` / `BaseReportingPlugin`. Optionally implement `IStdioPlugin` for stdio-based communication.
+2. Implement it as a **public class** in a class library project.
+3. Implement the required interface members and override any relevant base class methods/events for your use case.
+
+## Commits & Releases
+
+- **Commit messages:** Clear, succinct, and reference the issue they close when applicable
+- **Versioning:** We follow semver. Use the `upgrade-devproxy-version` skill for version bumps
+- **Release:** After release builds, homebrew and winget are updated manually
+
+## Testing Code Changes
+
+When testing code, features, or changes, **always launch the proxy in detached mode** with these settings to avoid conflicts:
+
+```bash
+dotnet run --project DevProxy -- --detach --as-system-proxy false --port 0 --api-port 0
+```
+
+- `--as-system-proxy false` — prevents modifying system-wide network settings
+- `--port 0` — lets the OS assign a random available port for the proxy
+- `--api-port 0` — lets the OS assign a random available port for the API
+
+**Auth for M365/Azure:** No automated auth. You can try `m365 util accesstoken get` or `az account get-access-token` (use `-h` for options) but the user may not be signed in.
+
+**Cleanup:** After testing, stop the proxy using `devproxy stop` (preferred, cross-platform). If you started it with `dotnet run`, you can also stop it with `Ctrl+C` in that terminal; as a last resort, terminate the process using OS-specific tools (for example, `kill <PID>` on Unix-like systems or Task Manager on Windows). Clean up any generated log files (`devproxy-*.log`).
+
+## Reference (Architecture)
+
+- **Main entry point:** `DevProxy/Program.cs` — sets up web host, configuration, logging, plugins, and starts proxy engine
+- **Proxy Engine:** `DevProxy/Proxy/ProxyEngine.cs` — network interception, request/response handling, plugin invocation
+- **Plugins:** Implement `IPlugin` interface (`DevProxy.Abstractions/Plugins/IPlugin.cs`). Base classes: `BasePlugin`, `BaseReportingPlugin` in `DevProxy.Abstractions/Plugins/`
+- **CLI Commands:** `DevProxy/Commands/` — built with System.CommandLine, registered via `DevProxyCommand.cs`
+- **Configuration:** `DevProxy/config/devproxyrc.json` and other JSON files in `config/`
+- **macOS scripts:** `trust-cert.sh`, `remove-cert.sh`, `toggle-proxy.sh` in `DevProxy/`
 
 ## Resources
+
 - [Official documentation](https://aka.ms/devproxy)
 - [YouTube channel](https://youtube.com/@devproxy)
-
----
-
-*Update this file as project conventions evolve. For questions, see the README or open an issue.*