feat: Add Copilot instructions

.github/copilot-instructions.md

@@ -0,0 +1,20 @@
+# Whisper.net Copilot instructions
+
+When working in this repository, prefer the project skills under `.github/skills/` for repeatable workflows.
+
+## Skill routing
+
+- Use `Validate managed API changes` for ordinary C# API, processor, builder, test, example, and project-file changes.
+- Use `Run .NET tests with preview native libs` before managed test runs when native runtimes are needed locally and the task does not change `whisper.cpp`, native build scripts, runtime package targets, or native binary outputs.
+- Use `Change native runtimes` when changing `whisper.cpp`, native build scripts, native workflows, runtime artifact layout, or native runtime package contents.
+- Use `Validate runtime loading` when changing `RuntimeOptions`, `RuntimeLibrary`, `NativeLibraryLoader`, runtime selection, dependency checking, or examples that force runtime order.
+- Use `Validate No-AVX tests` for `CpuNoAvx`, `Whisper.net.Runtime.NoAvx`, or `USE_WHISPER_NOAVX_TESTS` changes.
+- Use `Validate MAUI mobile tests` for MAUI target frameworks, mobile runtime packaging, or iOS/Android test behavior.
+- Use `Validate runtime packages and releases` for NuGet packaging, `.nuspec`, `.targets`, versioning, or release workflow changes.
+- Use `Manage Whisper test models` when `WHISPER_TEST_MODEL_PATH` is involved or model downloads/cache behavior blocks tests.
+
+## Repository hygiene
+
+The preview native libs are published by `.github/workflows/upload-build-artifacts.yml` as prerelease tags named `preview-nativelibs-<whisper.cpp short sha>` with an asset named `native-runtimes.zip`.
+
+Do not commit downloaded native binaries, model files, or packed NuGet artifacts unless the task explicitly asks to update those artifacts.

.github/skills/change-native-runtimes/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: Change native runtimes
+description: Use when changing whisper.cpp, native build scripts, runtime artifact layout, or native runtime package contents.
+---
+
+# Change native runtimes
+
+Use this skill when a task changes `whisper.cpp`, native build workflows, `windows-scripts.ps1`, `Makefile`, native dependency packaging, or files under `runtimes/` that describe native runtime packages.
+
+## Do not use preview native libs
+
+Do not validate these changes with downloaded preview native libs. Preview native libs are only a shortcut for managed-only validation. Native runtime changes must build or consume artifacts produced from the changed native inputs.
+
+## Key places to inspect
+
+- `.github/workflows/*native-build.yml` for the CI build matrix.
+- `.github/workflows/build-all.yml` and `.github/workflows/upload-build-artifacts.yml` for artifact aggregation and preview release publishing.
+- `windows-scripts.ps1` and `Makefile` for local native build entry points.
+- `runtimes/*.nuspec` and `runtimes/*/*.targets` for package contents and MSBuild imports.
+- `tools/WhisperNetDependencyChecker/Program.cs` for runtime load validation.
+
+## Windows local build entry points
+
+From the repository root, dot-source the script and build only the relevant runtime when possible:
+
+```powershell
+. .\windows-scripts.ps1
+BuildWindows "Release"
+BuildWindowsIntel "Release"
+BuildWindowsArm "Release"
+BuildWindowsAll "Release"
+```
+
+Use the specific function that matches the task. Do not rebuild every native runtime unless the change affects shared native build logic.
+
+## Dependency checker validation
+
+After placing built artifacts under `runtimes/`, validate native loading for the changed runtime:
+
+```powershell
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- CpuNoAvx
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Cuda
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Cuda12
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Vulkan
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- CoreML
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- OpenVino
+```
+
+Only run checks for runtimes relevant to the change and available on the current machine.
+
+## Package validation
+
+When native package contents or targets change, also use the `Validate runtime packages and releases` skill before opening a PR.

.github/skills/manage-whisper-test-models/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: Manage Whisper test models
+description: Use when tests need deterministic model files, model downloads fail, or WHISPER_TEST_MODEL_PATH is involved.
+---
+
+# Manage Whisper test models
+
+Use this skill when tests fail because model files are missing, the environment cannot download models, or a task touches model download/test fixture behavior.
+
+## Model path contract
+
+`WHISPER_TEST_MODEL_PATH` must point to a directory that contains test model files, not to a single model file. The test helper expects file names like:
+
+```text
+ggml-tiny-noquantization.bin
+ggml-tiny-q5_0.bin
+```
+
+Do not set `WHISPER_TEST_MODEL_PATH` to `runtimes/` unless those `ggml-*.bin` files are present there.
+
+## Populate the model cache
+
+Use the repository tool to download the models expected by tests:
+
+```powershell
+$env:WHISPER_TEST_MODEL_PATH = "$PWD\.test-models"
+dotnet run --project .\tools\DownloadModelForTests\DownloadModelForTests.csproj
+dotnet test .\Whisper.net.slnx --logger "trx"
+Remove-Item Env:\WHISPER_TEST_MODEL_PATH
+```
+
+Keep `.test-models/` or any other downloaded model cache out of source control.
+
+## Hugging Face token
+
+Some model downloads may require authentication. If the environment provides `HF_TOKEN`, preserve and pass it through rather than hardcoding tokens or adding tokens to config files.
+
+## Troubleshooting
+
+- If tests fail before downloading, check that `WHISPER_TEST_MODEL_PATH` points to a writable directory.
+- If tests fail after downloading, verify both expected file names exist in the directory.
+- If native library loading fails, use runtime validation skills instead; model files and native runtimes are separate inputs.

.github/skills/run-dotnet-tests-with-preview-nativelibs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: Run .NET tests with preview native libs
+description: Use when validating managed .NET changes that do not modify whisper.cpp or native runtime build outputs.
+---
+
+# Run .NET tests with preview native libs
+
+Use this skill when you need to run Whisper.net managed tests and the change does not require rebuilding native runtimes or changing the `whisper.cpp` submodule.
+
+## When to use this
+
+- The task changes managed C# code, tests, docs, samples, or project files only.
+- You need native libraries available locally for `dotnet test`.
+- You do not need to validate a new `whisper.cpp` revision or native build-system change.
+
+Do not use this shortcut for changes under `whisper.cpp`, native build scripts, runtime package targets, or native binary outputs. In those cases, build the relevant native runtimes instead.
+
+## How the preview package is produced
+
+The `.github/workflows/upload-build-artifacts.yml` workflow:
+
+1. Reads the pinned `whisper.cpp` short commit SHA.
+2. Creates a prerelease tag named `preview-nativelibs-<sha>`.
+3. Uploads one release asset named `native-runtimes.zip`.
+4. Stores the merged native build outputs inside the archive under `runtime-artifacts/`.
+
+Example release:
+
+```text
+https://github.com/sandrohanea/whisper.net/releases/tag/preview-nativelibs-f24588a
+```
+
+## PowerShell workflow
+
+Run from the repository root:
+
+```powershell
+$commit = git rev-parse --short=7 HEAD:whisper.cpp
+$tag = "preview-nativelibs-$commit"
+gh release download $tag --repo sandrohanea/whisper.net --pattern native-runtimes.zip --clobber
+Expand-Archive .\native-runtimes.zip -DestinationPath . -Force
+Copy-Item .\runtime-artifacts\* .\runtimes\ -Recurse -Force
+Remove-Item .\runtime-artifacts -Recurse -Force
+Remove-Item .\native-runtimes.zip
+dotnet restore .\Whisper.net.slnx
+dotnet build .\Whisper.net.slnx --no-restore -warnaserror
+dotnet test .\Whisper.net.slnx --no-build --logger "trx"
+```
+
+## Bash workflow
+
+Run from the repository root:
+
+```bash
+commit="$(git rev-parse --short=7 HEAD:whisper.cpp)"
+tag="preview-nativelibs-$commit"
+gh release download "$tag" --repo sandrohanea/whisper.net --pattern native-runtimes.zip --clobber
+unzip -o native-runtimes.zip
+cp -R runtime-artifacts/* runtimes/
+rm -rf runtime-artifacts native-runtimes.zip
+dotnet restore ./Whisper.net.slnx
+dotnet build ./Whisper.net.slnx --no-restore -warnaserror
+dotnet test ./Whisper.net.slnx --no-build --logger "trx"
+```
+
+## Test model handling
+
+The preview native libs release contains native runtime artifacts, not necessarily test model files. Do not set `WHISPER_TEST_MODEL_PATH` to `runtimes/` unless the required `ggml-*.bin` model files are present there. Without that variable, the tests download models through the normal test fixture path.
+
+## Repository hygiene
+
+- Treat downloaded native runtimes as local test inputs, not source changes.
+- Do not commit copied binaries from `native-runtimes.zip` unless the task explicitly asks to update runtime artifacts.
+- Remove temporary `native-runtimes.zip` and `runtime-artifacts/` files after unpacking.

.github/skills/validate-managed-api-changes/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: Validate managed API changes
+description: Use when changing Whisper.net managed C# APIs, processors, builders, tests, or examples without changing native runtime outputs.
+---
+
+# Validate managed API changes
+
+Use this skill when a task changes managed code in `Whisper.net/`, managed tests, examples, or project metadata, and does not require rebuilding `whisper.cpp` or native runtime packages.
+
+## Start with the managed surface
+
+- Inspect the public API in `Whisper.net/` before changing tests or examples.
+- Keep nullable annotations, async disposal, and cancellation behavior consistent with existing code.
+- Update examples and README snippets when a public API shape, option, or default behavior changes.
+- Add or update tests in `tests/Whisper.net.Tests/` for behavior changes.
+
+## Validation workflow
+
+If native runtimes are already present locally, run:
+
+```powershell
+dotnet restore .\Whisper.net.slnx
+dotnet build .\Whisper.net.slnx --no-restore -warnaserror
+dotnet test .\Whisper.net.slnx --no-build --logger "trx"
+```
+
+If native runtimes are not present and the change does not touch `whisper.cpp`, native build scripts, runtime package targets, or native binaries, use the `Run .NET tests with preview native libs` skill first to populate `runtimes/`.
+
+## Test model handling
+
+Most tests can download required models automatically. If model downloads are not appropriate for the environment, use the `Manage Whisper test models` skill to pre-populate `WHISPER_TEST_MODEL_PATH`.
+
+## Avoid over-validating
+
+Do not run native runtime builds for a purely managed API change unless the managed change alters runtime loading, package target imports, or platform-specific behavior.

.github/skills/validate-maui-mobile-tests/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: Validate MAUI mobile tests
+description: Use when changing MAUI target frameworks, mobile runtime packaging, or mobile test behavior.
+---
+
+# Validate MAUI mobile tests
+
+Use this skill for changes involving MAUI target frameworks, mobile runtime packaging, iOS/Android test projects, or `.github/workflows/dotnet-maui.yml`.
+
+## Environment flags
+
+MAUI builds rely on these flags:
+
+```powershell
+$env:USE_WHISPER_MAUI = "true"
+$env:USE_WHISPER_MAUI_TESTS = "true"
+```
+
+Clear them after local validation:
+
+```powershell
+Remove-Item Env:\USE_WHISPER_MAUI
+Remove-Item Env:\USE_WHISPER_MAUI_TESTS
+```
+
+## Restore and build
+
+From the repository root:
+
+```powershell
+$env:USE_WHISPER_MAUI = "true"
+$env:USE_WHISPER_MAUI_TESTS = "true"
+dotnet workload restore .\Whisper.net.Maui.Tests.slnx
+dotnet restore .\Whisper.net.Maui.Tests.slnx
+dotnet build .\Whisper.net.Maui.Tests.slnx --no-restore -warnaserror
+```
+
+## Device and simulator tests
+
+The CI workflow uses XHarness for simulator/device execution. Prefer matching `.github/workflows/dotnet-maui.yml` over inventing local commands, because target frameworks and simulator images change over time.
+
+Run mobile tests locally only when the required workloads, SDKs, emulators, and simulator images are installed. Otherwise, validate restore/build locally and rely on CI for simulator execution.
+
+## Files to inspect
+
+- `.github/workflows/dotnet-maui.yml`
+- `Whisper.net.Maui.Tests.slnx`
+- `Whisper.net/Whisper.net.csproj`
+- `tests/Whisper.net.Tests.Maui/Whisper.net.Tests.Maui.csproj`
+- `tests/Whisper.net.Tests/Whisper.net.Tests.csproj`
+- Mobile runtime package `.nuspec` and `.targets` files under `runtimes/`

.github/skills/validate-noavx-tests/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: Validate No-AVX tests
+description: Use when changing CPU NoAvx runtime loading, package imports, or tests that must run without AVX.
+---
+
+# Validate No-AVX tests
+
+Use this skill for changes involving `CpuNoAvx`, `Whisper.net.Runtime.NoAvx`, `USE_WHISPER_NOAVX_TESTS`, or the no-AVX CI workflow.
+
+## Important behavior
+
+Setting `USE_WHISPER_NOAVX_TESTS=true` changes which runtime targets are imported by the demo, test project, and dependency checker. It should be used only for no-AVX validation.
+
+## Workflow
+
+From the repository root with no-AVX runtime artifacts available under `runtimes/`:
+
+```powershell
+$env:USE_WHISPER_NOAVX_TESTS = "true"
+dotnet restore .\Whisper.net.slnx
+dotnet build .\Whisper.net.slnx --no-restore -warnaserror
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- CpuNoAvx
+dotnet test .\Whisper.net.slnx --no-build --logger "trx"
+Remove-Item Env:\USE_WHISPER_NOAVX_TESTS
+```
+
+If no-AVX native artifacts are not present and the task changed native no-AVX outputs, use the `Change native runtimes` skill to build or obtain matching artifacts instead of using the preview native libs shortcut.
+
+## Files to inspect
+
+- `.github/workflows/dotnet-noavx.yml`
+- `.github/workflows/linux-noavx-native-build.yml`
+- `.github/workflows/windows-noavx-native-build.yml`
+- `runtimes/Whisper.net.Runtime.NoAvx.nuspec`
+- `runtimes/Whisper.net.Runtime.NoAvx/Whisper.net.Runtime.NoAvx.targets`
+- `Whisper.net/LibraryLoader/NativeLibraryLoader.cs`
+- `tools/WhisperNetDependencyChecker/Program.cs`

.github/skills/validate-runtime-loading/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: Validate runtime loading
+description: Use when changing runtime selection, RuntimeOptions, NativeLibraryLoader, runtime package imports, or examples that force runtime order.
+---
+
+# Validate runtime loading
+
+Use this skill when a task changes runtime discovery or selection, including `RuntimeOptions`, `RuntimeLibrary`, `NativeLibraryLoader`, runtime targets, dependency checker behavior, or examples that set `RuntimeOptions.RuntimeLibraryOrder`.
+
+## Runtime surfaces to keep in sync
+
+- `Whisper.net/LibraryLoader/RuntimeLibrary.cs`
+- `Whisper.net/LibraryLoader/RuntimeOptions.cs`
+- `Whisper.net/LibraryLoader/NativeLibraryLoader.cs`
+- `Whisper.net/LibraryLoader/CudaHelper.cs` for CUDA-specific probing
+- `tools/WhisperNetDependencyChecker/Program.cs`
+- `examples/MultiRuntime/Program.cs`
+- README runtime package and runtime-order documentation
+- `runtimes/*.nuspec` and `runtimes/*/*.targets` when package layout changes
+
+## Current runtime order
+
+The default order is:
+
+```text
+Cuda, Cuda12, Vulkan, CoreML, OpenVino, Cpu, CpuNoAvx
+```
+
+Preserve this order unless the task intentionally changes runtime preference behavior. If the order changes, update XML docs and README text together.
+
+## Validation
+
+With native artifacts present under `runtimes/`, run the dependency checker for each affected runtime:
+
+```powershell
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- CpuNoAvx
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Cuda
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Cuda12
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- Vulkan
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- CoreML
+dotnet run --project .\tools\WhisperNetDependencyChecker\WhisperNetDependencyChecker.csproj -- OpenVino
+```
+
+Then run the managed test suite:
+
+```powershell
+dotnet test .\Whisper.net.slnx --logger "trx"
+```
+
+Only use the preview native libs shortcut when the change is managed-only and does not alter runtime package layout or native outputs.