feat: Optional taxonomy directory, Umbraco compat, and critical bug fixes

.github/agents/examine-compat-validator.agent.md

@@ -0,0 +1,72 @@
+---
+description: "Use this agent when the user asks to validate Examine v4 code changes against v3 API compatibility or ensure backward compatibility with Examine v3.\n\nTrigger phrases include:\n- 'check v3 compatibility'\n- 'will this break v3 APIs?'\n- 'validate backward compatibility'\n- 'ensure v3 compatibility'\n- 'is this a breaking change?'\n- 'check API contract compatibility'\n\nExamples:\n- User says 'I modified the searcher API—will this break v3 compatibility?' → invoke this agent to analyze the change against v3 contracts\n- User asks 'before we release, check that this change is backward compatible with v3' → invoke this agent for full compatibility audit\n- During code review, user says 'validate this doesn't break existing v3 implementations' → invoke this agent to assess impact on v3 users\n- User requests 'check if our field mapping changes affect v3 API consumers' → invoke this agent to identify compatibility risks"
+name: examine-compat-validator
+---
+
+# examine-compat-validator instructions
+
+You are an expert Examine compatibility specialist with deep knowledge of both Examine v3 and v4 APIs, the Umbraco CMS ecosystem, and the migration patterns between versions.
+
+Your mission: Ensure that changes to the Examine v4 codebase maintain backward compatibility with v3 APIs, preventing breaking changes for users upgrading from v3 to v4. You validate API contracts, identify breaking changes, and provide clear compatibility assessments.
+
+Core responsibilities:
+- Analyze code changes for backward compatibility with v3 API contracts
+- Identify breaking changes (signature changes, removed methods, altered behavior)
+- Validate method parameters, return types, and exception contracts haven't changed
+- Check that public/protected surfaces remain stable
+- Assess impact on Umbraco integration scenarios
+- Distinguish between safe changes (internal refactors) and breaking changes (public API)
+
+Methodology:
+1. **Baseline establishment**: Understand the original v3 API surface (methods, signatures, return types, exceptions)
+2. **Change analysis**: Examine the v4 code changes line-by-line for modifications to public/protected APIs
+3. **Compatibility assessment**: Check for breaking changes:
+   - Method signature changes (parameters added, types changed, order altered)
+   - Return type changes
+   - Exception behavior changes
+   - Property/field accessibility changes
+   - Removed or deprecated public members without fallback
+   - Behavioral changes in search execution, indexing, or result handling
+4. **Umbraco integration check**: Validate common Umbraco usage patterns still work
+5. **Risk classification**: Mark changes as safe, deprecated (with fallback), or breaking
+
+Breaking changes to watch for in Examine context:
+- ISearcher/IExaminer interface changes
+- Query API modifications
+- Field value handling changes
+- Result mapping changes
+- Indexing pipeline changes
+- Analyzer or tokenizer behavior changes
+- Configuration key/structure changes
+
+Output format:
+- **Compatibility status**: COMPATIBLE / COMPATIBLE WITH DEPRECATION / BREAKING
+- **Summary**: One-sentence assessment
+- **Change analysis**: List each identified change with compatibility impact
+- **Breaking changes** (if any): Explicit list of what breaks, affected APIs, and migration path needed
+- **Recommendations**: How to proceed (safe to merge, needs mitigation, requires major version bump)
+- **Migration impact**: What v3 users upgrading to v4 would need to change
+
+Quality controls:
+- Verify you've examined ALL public/protected API changes, not just obvious ones
+- Check both method changes AND property/field changes
+- Consider implicit contracts (behavior changes that aren't signature changes)
+- Test against known v3 usage patterns if possible
+- Flag deprecated but working code—clarify deprecation status
+- Confirm you understand the Examine v3 baseline before assessing v4 changes
+
+Edge cases and pitfalls:
+- Internal implementation changes are safe (even if they look big)
+- Virtual method overrides may hide breaking changes in derived classes
+- Generic type parameter changes are breaking
+- Adding required parameters is breaking; adding optional parameters is safe
+- Narrowing exception types (throwing fewer exceptions) may break exception handlers
+- Performance changes aren't breaking unless they violate documented behavior
+- Umbraco CMS integration changes (configuration, event hooks) are potential breaking points
+
+When to ask for clarification:
+- If you need context on why a change was made (influences risk assessment)
+- If v3 API baseline is unclear for a component
+- If you need to know the target audience (v3 users upgrading vs new v4 users)
+- If architectural intent behind changes isn't clear
+- If you need guidance on what level of compatibility is acceptable (e.g., is minor breaking change acceptable in v4.0?)

.github/skills/examinex-compat/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: examinex-compat
+description: 'Validate Examine v4 backward compatibility with ExamineX by cloning the ExamineX.Source repo (support/9.x branch), swapping Examine NuGet package references to local project references, and verifying the build passes. Use when checking API compatibility, verifying breaking changes, or validating that Examine v4 works with ExamineX. Intended for the examine-compat-validator custom agent.'
+compatibility: 'Requires git and dotnet SDK 10.0+. Requires network access to clone https://github.com/SDKits/ExamineX.Source.git'
+metadata:
+  author: Examine
+  version: "1.0"
+---
+
+# ExamineX Compatibility Validator
+
+Validates that the current Examine v4 codebase is backward compatible with ExamineX by replacing ExamineX's NuGet package references for Examine with project references pointing to this workspace, then building the ExamineX solution.
+
+## When to Use This Skill
+
+- After making changes to Examine public APIs
+- Before releasing a new version of Examine
+- When verifying that Examine v4 does not introduce breaking changes for ExamineX
+- When the user asks to "check ExamineX compatibility", "validate ExamineX compat", or "test against ExamineX"
+
+## Prerequisites
+
+- `git` CLI available on PATH
+- `dotnet` SDK 10.0+ installed (ExamineX targets `net10.0`)
+- Network access to clone from GitHub (the SDKits/ExamineX.Source repo must be accessible with the current git credentials)
+
+## Important Rules
+
+- The `TEMP` folder at the workspace root is **disposable** and must **NEVER** be committed to the Examine repository.
+- Ensure `TEMP/` is listed in the root `.gitignore` before proceeding.
+- If `TEMP/ExamineX.Source` already exists, skip the clone step and use the existing clone (run `git pull` to update).
+- Always use the **`support/9.x`** branch.
+- Always build in **Debug** configuration — ExamineX runs obfuscation in Release which is unnecessary for compat testing.
+
+## Repository Structure
+
+The ExamineX.Source repository (`support/9.x` branch) has the following relevant layout:
+
+```
+ExamineX.Source/
+├── src/
+│   ├── ExamineX.sln                              ← Main solution file
+│   ├── Directory.Packages.props                   ← Central Package Management (has Examine entries)
+│   ├── Directory.Build.props                      ← Global properties (TFM: net10.0)
+│   ├── global.json                                ← Requires SDK 10.0.100+
+│   ├── ExamineX.Shared/                           ← Shared library (references Examine.Lucene)
+│   ├── ExamineX.AzureSearch/                      ← Azure Search provider (references Examine.Lucene)
+│   ├── ExamineX.ElasticSearch/                    ← Elastic Search provider (references Examine.Lucene)
+│   ├── ExamineX.Solr/                             ← Solr provider (references Examine.Lucene)
+│   ├── ExamineX.AzureSearch.Umbraco/              ← Azure + Umbraco integration
+│   ├── ExamineX.ElasticSearch.Umbraco/            ← Elastic + Umbraco integration
+│   ├── ExamineX.Shared.Umbraco/                   ← Shared Umbraco integration
+│   ├── ExamineX.Common.Tests/                     ← Shared test utilities (references Examine)
+│   ├── ExamineX.AzureSearch.Tests/                ← Azure Search tests (references Examine)
+│   ├── ExamineX.ElasticSearch.Tests/              ← Elastic Search tests (references Examine)
+│   ├── ExamineX.Solr.Tests/                       ← Solr tests
+│   ├── ExamineX.AzureSearch.Umbraco.BlobMedia/    ← Blob media integration
+│   ├── ExamineX.AzureSearch.Umbraco.ContentDelivery/ ← Content delivery integration
+│   ├── ExamineX.AzureSearch.Umbraco.Forms/        ← Azure + Umbraco Forms
+│   ├── ExamineX.AzureSearch.Umbraco.PDF/          ← Azure + Umbraco PDF
+│   ├── ExamineX.ElasticSearch.Umbraco.Forms/      ← Elastic + Umbraco Forms
+│   ├── ExamineX.AzureSearch.Umbraco.WebTest/      ← Web test app (legacy)
+│   ├── ExamineX.AzureSearch.Umbraco.WebTest2/     ← Web test app (v13+)
+│   └── ExamineX.Umbraco.WebTest/                  ← Combined web test app
+```
+
+## Package-to-Project Mapping
+
+ExamineX uses Central Package Management (`Directory.Packages.props`). The following NuGet packages must be swapped to project references:
+
+| NuGet Package | ExamineX Project(s) That Reference It | Examine Project Reference |
+|---|---|---|
+| `Examine.Lucene` (v3.7.1) | `ExamineX.Shared`, `ExamineX.AzureSearch`, `ExamineX.ElasticSearch`, `ExamineX.Solr` | `src/Examine.Lucene/Examine.Lucene.csproj` |
+| `Examine` (v3.7.1) | `ExamineX.Common.Tests`, `ExamineX.ElasticSearch.Tests`, `ExamineX.AzureSearch.Tests` | `src/Examine.Host/Examine.csproj` |
+
+> **Note:** The `Examine` meta-package transitively includes `Examine.Core` and `Examine.Lucene`. The test projects reference it for full Examine API access.
+
+## Step-by-Step Workflow
+
+### Step 1: Ensure TEMP Is Git-Ignored
+
+Check that the workspace root `.gitignore` contains a `TEMP/` entry. If not, add it:
+
+```
+TEMP/
+```
+
+### Step 2: Clone ExamineX.Source (If Needed)
+
+If `TEMP/ExamineX.Source` does not exist:
+
+```bash
+git clone --branch support/9.x https://github.com/SDKits/ExamineX.Source.git TEMP/ExamineX.Source
+```
+
+If it already exists, ensure it is on the correct branch and up to date:
+
+```bash
+cd TEMP/ExamineX.Source && git checkout support/9.x && git pull && cd ../..
+```
+
+### Step 3: Modify Directory.Packages.props
+
+In `TEMP/ExamineX.Source/src/Directory.Packages.props`, **remove or comment out** the Examine package version entries:
+
+```xml
+<!-- Remove or comment out these lines: -->
+<PackageVersion Include="Examine" Version="3.7.1" />
+<PackageVersion Include="Examine.Lucene" Version="3.7.1" />
+```
+
+### Step 4: Swap Package References to Project References
+
+All ExamineX projects live under `TEMP/ExamineX.Source/src/<ProjectName>/`, which is 4 directories deep from the Examine workspace root. The relative path prefix is `..\..\..\..\src\`.
+
+#### 4a. Projects referencing `Examine.Lucene` (4 projects)
+
+In each of these files, replace:
+```xml
+<PackageReference Include="Examine.Lucene" />
+```
+With:
+```xml
+<ProjectReference Include="..\..\..\..\src\Examine.Lucene\Examine.Lucene.csproj" />
+```
+
+Files to update:
+- `TEMP/ExamineX.Source/src/ExamineX.Shared/ExamineX.Shared.csproj`
+- `TEMP/ExamineX.Source/src/ExamineX.AzureSearch/ExamineX.AzureSearch.csproj`
+- `TEMP/ExamineX.Source/src/ExamineX.ElasticSearch/ExamineX.ElasticSearch.csproj`
+- `TEMP/ExamineX.Source/src/ExamineX.Solr/ExamineX.Solr.csproj`
+
+#### 4b. Projects referencing `Examine` (3 test projects)
+
+In each of these files, replace:
+```xml
+<PackageReference Include="Examine" />
+```
+With:
+```xml
+<ProjectReference Include="..\..\..\..\src\Examine.Host\Examine.csproj" />
+```
+
+Files to update:
+- `TEMP/ExamineX.Source/src/ExamineX.Common.Tests/ExamineX.Common.Tests.csproj`
+- `TEMP/ExamineX.Source/src/ExamineX.ElasticSearch.Tests/ExamineX.ElasticSearch.Tests.csproj`
+- `TEMP/ExamineX.Source/src/ExamineX.AzureSearch.Tests/ExamineX.AzureSearch.Tests.csproj`
+
+### Step 5: Restore and Build
+
+From the workspace root, build the ExamineX solution in Debug configuration:
+
+```bash
+cd TEMP/ExamineX.Source/src
+dotnet restore ExamineX.sln
+dotnet build ExamineX.sln --no-restore --configuration Debug
+```
+
+**Expected outcome:** Build succeeds with zero errors. Warnings are acceptable.
+
+If the build fails, analyze the error output:
+- **Missing type/member errors** indicate a breaking API change in Examine that must be addressed.
+- **Nullable annotation warnings promoted to errors** (CS8600, CS8601, CS8602, CS8604, CS8620, CS8765) may be caused by Examine v4 tightening NRT annotations. These can be suppressed in the affected `.csproj` files with `<NoWarn>` for compat testing purposes, while still detecting real API shape changes.
+- **Target framework mismatches** may require aligning TFMs between Examine and ExamineX (ExamineX targets `net10.0`).
+- **Transitive dependency conflicts** may require version alignment in `Directory.Packages.props`.
+
+### Step 6: Run Tests
+
+Run the Azure Search tests (these are designed to run locally):
+
+```bash
+cd TEMP/ExamineX.Source/src
+dotnet test ExamineX.AzureSearch.Tests --no-build --configuration Debug
+```
+
+**Expected outcome:** All tests pass. Any test failures related to Examine APIs indicate compatibility issues.
+
+> **Note:** The Elasticsearch and Solr test projects may require external service infrastructure. If they fail due to connection issues (not Examine API issues), those failures can be ignored — focus on the Azure Search tests and overall build success.
+
+### Step 7: Report Results
+
+Summarize the outcome:
+
+1. **Build status:** Pass / Fail (with error details)
+2. **Test status:** Pass / Fail / Skipped (with failure details if applicable)
+3. **Breaking changes found:** List any Examine API changes that caused build failures
+4. **Recommended fixes:** For each breaking change, suggest whether to fix in Examine (restore API) or note as an intentional breaking change
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Clone fails (403 Forbidden) | The SDKits org has OAuth restrictions — ensure your git credentials have access to SDKits/ExamineX.Source |
+| Clone fails (branch not found) | Verify the `support/9.x` branch exists: `git ls-remote --heads https://github.com/SDKits/ExamineX.Source.git` |
+| SDK version error | ExamineX requires .NET SDK 10.0.100+. Check `TEMP/ExamineX.Source/src/global.json` |
+| Build fails with TFM errors | ExamineX targets `net10.0`. Ensure Examine supports this TFM or add it |
+| NuGet restore fails after swap | Ensure the `Examine` and `Examine.Lucene` PackageVersion entries were fully removed from `Directory.Packages.props` |
+| Relative paths are wrong | Verify workspace structure: Examine repo root must contain both `TEMP/ExamineX.Source/` and `src/` |
+| Obfuscation errors | Ensure you are building with `--configuration Debug` (obfuscation only runs in Release) |
+| Nullable warnings treated as errors | Add `<NoWarn>$(NoWarn);CS8600;CS8601;CS8602;CS8604;CS8620;CS8765</NoWarn>` to affected project PropertyGroups |
+| Elasticsearch/Solr tests fail with connection errors | These test projects may need external services — focus on Azure Search tests and build success |
+
+## Cleanup
+
+The `TEMP` folder is disposable. To clean up:
+
+```bash
+Remove-Item -Recurse -Force TEMP/ExamineX.Source
+```