tarkovtracker-org · DysektAI · Jul 28, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 28, 2026
diff --git a/.csharpierignore b/.csharpierignore
@@ -10,3 +10,4 @@
 **/*.xml
 **/obj/**
 **/bin/**
+src/ScanEngine/**
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -23,6 +23,7 @@ jobs:
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
         with:
           persist-credentials: false
+          submodules: recursive
       - name: Setup .NET
         uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
         with:

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -33,6 +33,7 @@ jobs:
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
         with:
           persist-credentials: false
+          submodules: recursive
       - name: Resolve release version and validated build
         id: release
         env:

diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,7 @@ RatScanner/[Dd]ata/*
 
 # publish folder
 publish/
+RatScanner.zip
 
 # Local smoke-test / agent watch captures (never commit)
 watch-verify-*.txt

diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "RatEye"]
+	path = src/ScanEngine
+	url = https://github.com/tarkovtracker-org/RatEye.git
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -11,6 +11,7 @@
     "**/bin/**",
     "**/obj/**",
     "**/publish/**",
-    "**/.vs/**"
+    "**/.vs/**",
+    "src/ScanEngine/**"
   ]
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,17 +1,17 @@
 # RatScanner — Agent Control Plane
 
-**Authority:** implementation and project files override this document when they disagree. Keep this file and `docs/agent-context/` synchronized when architecture, commands, packages, workflows, or behavior change.
+**Authority:** explicit maintainer decisions are authoritative for architecture and repository ownership, even when the current checkout or generated guidance still reflects an older or transitional layout. Implementation and project files are authoritative for current behavior. If those sources conflict, stop and surface the conflict instead of choosing one silently. Never close or supersede architecture PRs, delete source-bearing work, or reverse a repository boundary based only on inferred documentation precedence. Keep this file and `docs/agent-context/` synchronized when architecture, commands, packages, workflows, or behavior change.
 
 ## Product (one paragraph)
 
-Windows x64-only Escape from Tarkov external item scanner. WPF hosts MudBlazor UI via WebView2; screenshots feed an in-repo scan engine (vendored RatEye sources under `src/ScanEngine/`). Catalog data comes mainly from **json.tarkov.dev**; maps use a slim GraphQL query on **api.tarkov.dev** with JSON fallback. Maintained at `tarkovtracker-org/RatScanner`, semver **4.x** (`v4.x.x`).
+Windows x64-only Escape from Tarkov external item scanner. WPF hosts MudBlazor UI via WebView2; screenshots feed standalone RatEye source checked out as a Git submodule under `src/ScanEngine/`. Catalog data comes mainly from **json.tarkov.dev**; maps use a slim GraphQL query on **api.tarkov.dev** with JSON fallback. Maintained at `tarkovtracker-org/RatScanner`, semver **4.x** (`v4.x.x`).
 
 **Stack snapshot:** `net10.0-windows10.0.22621.0` · WPF + WinForms · Blazor WebView · MudBlazor · RatStash · OpenCvSharp · Tesseract · Newtonsoft.Json. Package versions live in `.csproj` files — do not copy versions into docs.
 
 ## Non-negotiable constraints
 
 1. **Windows x64 only** — the OpenCvSharp native runtime is x64-only. Do not design, build, test, or document x86, Linux/WSL, or macOS runs.
-2. **Scan engine is in-tree** — edit `src/ScanEngine/`. Never re-add a NuGet `PackageReference` for `RatEye`. App references it via `ProjectReference`. Namespaces remain `RatEye`; assembly remains RatEye.
+2. **Scan engine is standalone** — `src/ScanEngine/` is the `tarkovtracker-org/RatEye` submodule. Engine changes belong in RatEye and RatEye must never reference RatScanner. Never add a NuGet `PackageReference` for `RatEye`; App uses a source `ProjectReference`. A temporary vendored or in-tree checkout during migration is not authority to collapse the repositories or abandon the standalone boundary.
 3. **Bulk catalog via json.tarkov.dev** — use `TarkovDevAPI` (rate limit, dedup, offline cache, backoff). Do not bypass with ad-hoc HTTP for items/tasks/hideout/crafts/barters. Do not reintroduce a GraphQL schema generator for bulk catalog. Slim maps GraphQL is intentional; keep maps off cold-start critical path.
 4. **Product version only in** `src/App/RatScanner.csproj` `<Version>`. Independent 4.x line; do not mirror historical upstream 3.x tags.
 5. **No secrets in git** — tokens live in user `config.cfg` (DPAPI-protected fields where used).
@@ -39,6 +39,12 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\lint-markdown.ps1 -F
 publish.bat                      :: release package only (not day-to-day)
 ```
 
+Initialize source dependencies after cloning:
+
+```bat
+git submodule update --init --recursive
+```
+
 Day-to-day coding uses `dev.bat` / `scripts\dev.ps1` (debounced **restart-on-save** by default — 15s quiet period prevents endless rebuilds during rapid agent edits; `-NoDebounce` restores instant `dotnet watch`). Not full WPF hot reload. CI: `.github/workflows/build.yml` (Windows, .NET 10, documentation and formatting checks, Release build/test, dependency audit, validated single-file package) plus `.github/workflows/release.yml` (manual promotion of the exact successful `master` build artifact to either the opt-in `testing` pre-release channel or broad `latest` channel). Build CI runs on PRs and `master` pushes; releases are manual only.
 
 ## Fork / remotes / branches / PRs
@@ -119,9 +125,9 @@ Index and maintenance rules for the context set: [docs/agent-context/README.md](
 | Path | Scope |
 | --- | --- |
 | `src/App/AGENTS.md` | App UI, hosting, data clients owned by App |
-| `src/ScanEngine/AGENTS.md` | Vendored scan engine |
+| `src/ScanEngine/AGENTS.md` | Standalone RatEye submodule |
 | `tests/AGENTS.md` | Unit tests |
 
 ## Source-of-truth reminder
 
-**Code, `.csproj`, scripts, and CI win over docs.** If you discover drift, fix the docs in the same change set when you touch the related system.
+**Explicit maintainer architecture decisions win over stale or generated guidance. Code, `.csproj`, scripts, and CI define current behavior but may represent a transitional migration state.** If sources disagree, preserve active work, report the conflict, and obtain direction before changing repository ownership or PR state. Fix confirmed documentation drift in the same change set when you touch the related system.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -28,6 +28,7 @@ Supported workflow for this fork:
 Requirements: **64-bit Windows**, [.NET 10 SDK](https://dotnet.microsoft.com/download).
 
 ```bat
+git submodule update --init --recursive
 dev.bat                 :: watch rebuild + restart (preferred)
 dev.bat -Once           :: run once
 dotnet restore RatScanner.sln
@@ -51,7 +52,7 @@ Agent and architecture guidance: root `AGENTS.md` + `docs/agent-context/`.
 - Prefer clear structure over commentary that restates the code.
 - MudBlazor/CSS: prefer component parameters and specificity over `!important`.
 - Bulk catalog data goes through `TarkovDevAPI` (json.tarkov.dev); maps may use intentional slim GraphQL + JSON fallback. Do not reintroduce GraphQL schema generation for bulk catalog or a NuGet `RatEye` package.
-- Edit the in-repo scan engine under `src/ScanEngine/` (namespaces remain `RatEye`).
+- `src/ScanEngine/` is the `tarkovtracker-org/RatEye` submodule. Commit engine changes in RatEye first, then update RatScanner's gitlink; RatEye must not reference RatScanner.
 
 ## Documentation
 

diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -0,0 +1,7 @@
+<Project>
+  <PropertyGroup Condition="'$(MSBuildProjectName)' == 'RatEye'">
+    <!-- RatEye remains independently packable, but RatScanner integration builds
+         should not create a package as a side effect. -->
+    <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+  </PropertyGroup>
+</Project>
diff --git a/README.md b/README.md
@@ -79,9 +79,12 @@ Help: [FAQ][faq-page] · [Discord][discord] · [TarkovTracker Discord][tt-discor
 
 Requirements: **64-bit Windows**, [.NET 10 SDK](https://dotnet.microsoft.com/download).
 
-1. Clone **this** repo: `https://github.com/tarkovtracker-org/RatScanner`
+1. Clone **this** repo recursively: `git clone --recurse-submodules https://github.com/tarkovtracker-org/RatScanner`
 2. From the repo root, run **`dev.bat`** (downloads icons/OCR data and restores packages on first run)
 
+For an existing clone, initialize RatEye with
+`git submodule update --init --recursive`.
+
 ### Day-to-day coding
 
 | What you want | Command |
@@ -97,7 +100,7 @@ Requirements: **64-bit Windows**, [.NET 10 SDK](https://dotnet.microsoft.com/dow
 
 ```text
 src/App/           # Main WPF app
-src/ScanEngine/    # Scan engine (historical RatEye; in-tree)
+src/ScanEngine/    # Standalone RatEye Git submodule
 tests/             # Unit tests
 scripts/           # dev + data setup
 ```
@@ -139,7 +142,7 @@ See `CONTRIBUTING.md`. PRs and issues: **[tarkovtracker-org/RatScanner][fork-rep
 
 Default integration branch is **`master`**. Day-to-day work uses short-lived `feat/…` / `fix/…` branches and PRs against the fork.
 
-**Agent / contributor architecture docs:** root [`AGENTS.md`](AGENTS.md) (control plane) and [`docs/agent-context/`](docs/agent-context/README.md) (focused context). Nested `AGENTS.md` files under `src/App`, `src/ScanEngine`, and `tests` apply path-scoped rules. Implementation and project files override stale documentation.
+**Agent / contributor architecture docs:** root [`AGENTS.md`](AGENTS.md) (control plane) and [`docs/agent-context/`](docs/agent-context/README.md) (focused context). RatEye has its own scoped instructions in the `src/ScanEngine` submodule; `src/App/AGENTS.md` and `tests/AGENTS.md` apply to this repository. Implementation and project files override stale documentation.
 
 ## Community & support
 

diff --git a/RatScanner.sln b/RatScanner.sln
@@ -5,7 +5,7 @@ VisualStudioVersion = 17.1.31911.260
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "RatScanner", "src\App\RatScanner.csproj", "{6C9373BE-454F-4A4A-850E-17AC27C76992}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "RatEye", "src\ScanEngine\RatEye.csproj", "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "RatEye", "src\ScanEngine\RatEye\RatEye.csproj", "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RatScanner.Tests", "tests\RatScanner.Tests\RatScanner.Tests.csproj", "{C9A0B012-A8AD-4396-B7B8-4CA69308C4CA}"
 EndProject

diff --git a/docs/agent-context/README.md b/docs/agent-context/README.md
@@ -11,7 +11,7 @@ Root `AGENTS.md` is the **control plane**: short universal rules, default comman
 | **Mandatory instructions** | Root `AGENTS.md`, nested `**/AGENTS.md` | Always or path-scoped rules that must be followed |
 | **Explanatory context** | Files in this directory | How systems work, where code lives, what to verify |
 
-Context docs are not a second source of product truth. If prose disagrees with code, scripts, `.csproj`, or CI, **implementation wins** — then update the prose.
+Context docs are not a second source of product truth. Explicit maintainer decisions control architecture and repository ownership, while code, scripts, `.csproj`, and CI describe current behavior and may reflect a transitional state. If those sources conflict, stop and surface the conflict instead of choosing one silently; once resolved, update the stale source.
 
 ## Files and when to read them
 
@@ -23,7 +23,7 @@ Context docs are not a second source of product truth. If prose disagrees with c
 | [local-development.md](local-development.md) | Setup, `dev.bat`, data install, watch loop failures |
 | [build-and-validation.md](build-and-validation.md) | Restore/build/test/format, what to run per change type |
 | [app-ui.md](app-ui.md) | Razor, MudBlazor, CSS, themes, host pages, layouts |
-| [scan-engine.md](scan-engine.md) | OCR/icon pipeline, RatEye engine, vendoring rules |
+| [scan-engine.md](scan-engine.md) | OCR/icon pipeline and standalone RatEye boundary |
 | [data-integrations.md](data-integrations.md) | json.tarkov.dev, slim maps GraphQL, TarkovTracker, caches |
 | [configuration-and-cache.md](configuration-and-cache.md) | `config.cfg`, paths, TTL, offline cache |
 | [localization.md](localization.md) | UI `i18n` files and `LocalizationService` |
@@ -38,7 +38,7 @@ Root routing table: [`AGENTS.md`](../../AGENTS.md).
 1. When you change architecture, commands, packages, CI, paths, or user-visible behavior, update the **matching** context file(s) in the same change.
 2. Prefer links to authoritative files (`*.csproj`, scripts, workflows) over restating content that will drift.
 3. Do not copy package version numbers into these docs.
-4. Nested `src/App/AGENTS.md`, `src/ScanEngine/AGENTS.md`, and `tests/AGENTS.md` hold **scoped** rules; keep them short; point here for depth.
+4. Nested `src/App/AGENTS.md` and `tests/AGENTS.md` hold RatScanner-scoped rules. The `src/ScanEngine` submodule supplies RatEye's own `AGENTS.md`.
 5. Do not re-expand the root control plane into a subsystem dump.
 6. After structural doc changes, run `scripts/check-agent-docs.ps1` (also run in CI).
 7. After any `*.md` edit, run `scripts/lint-markdown.ps1 -Fix` (markdownlint-cli2; tables/fences/whitespace). CI enforces check mode; the optional hook checks without rewriting staged content.

diff --git a/docs/agent-context/app-ui.md b/docs/agent-context/app-ui.md
@@ -116,9 +116,9 @@ The always-visible PVP/PVE selector in `AppLayout` switches mode-specific tarkov
 | Package family | Project |
 | --- | --- |
 | WebView.Wpf, MudBlazor, Win Compatibility, SingleInstanceCore | App |
-| Scan/vision packages for processing | ScanEngine (plus App for Tesseract where referenced) |
+| Scan/vision packages for processing | Standalone RatEye submodule (plus App for Tesseract where referenced) |
 
-Do not move MudBlazor into ScanEngine.
+Do not move MudBlazor into RatEye.
 
 ## Practical UI change checklist
 

diff --git a/docs/agent-context/architecture.md b/docs/agent-context/architecture.md
@@ -120,4 +120,4 @@ flowchart TD
 ## Related nested rules
 
 - `src/App/AGENTS.md` — App-scoped constraints.
-- `src/ScanEngine/AGENTS.md` — vendoring / namespaces.
+- `src/ScanEngine/AGENTS.md` — standalone RatEye boundaries, tests, and packaging.
diff --git a/docs/agent-context/build-and-validation.md b/docs/agent-context/build-and-validation.md
@@ -30,7 +30,7 @@ dotnet test RatScanner.sln -c Release --no-restore
 
 CI builds and tests Release on `windows-latest` with .NET 10.x.
 
-Current test project: `tests/RatScanner.Tests` (xUnit v3). It covers selected pure logic and reliability contracts, configuration migration, localization fallback/key parity, and synthetic OpenCV/native-loading smoke. **Not** a full UI or live-scan accuracy suite. Scoped rules: `tests/AGENTS.md`.
+Current App test project: `tests/RatScanner.Tests` (xUnit v3). It covers App logic and reliability contracts, configuration migration, localization fallback/key parity, and the optional App-owned capture/crop harness. RatEye's submodule owns engine/OpenCV/cache tests and fixture replay. **Neither** is a substitute for full UI or live-scan verification. Scoped rules: `tests/AGENTS.md`.
 
 ### Formatting
 
@@ -75,7 +75,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check-agent-docs.ps1
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\test-agent-docs.ps1
 ```
 
-The integrity check validates required paths, context routing, local Markdown links, structurally parsed MSBuild references/package versions, ScanEngine packaging guards, and primary-branch consistency while excluding generated output. The adversarial test builds a disposable path-with-spaces fixture and proves representative failures are non-zero and actionable. Both run in CI.
+The integrity check validates required paths, context routing, local Markdown links, structurally parsed MSBuild references/package versions, RatEye submodule wiring, and primary-branch consistency while excluding generated output. The adversarial test builds a disposable path-with-spaces fixture and proves representative failures are non-zero and actionable. Both run in CI.
 
 ### Analyzers / warnings
 
@@ -149,7 +149,7 @@ CI uploads the validated `RatScanner.zip` as an immutable build artifact. The se
 | Pure logic / helpers | build + tests for covered code | csharpier |
 | API client / cache | build + unit tests | manual warm/cold start smoke |
 | UI Razor/CSS | build | WebView smoke |
-| ScanEngine processing | build + relevant tests | scan smoke if behaviorally risking accuracy |
+| RatEye processing | standalone RatEye build/tests + integrated App build | fixture replay + scan smoke if accuracy-sensitive |
 | Config paths / display | build + tests | manual multi-monitor if possible |
 | i18n | build | all locale files updated; UI language switch |
 | CI / scripts | build (or script dry-run) | publish path once if packaging changed |
@@ -164,7 +164,8 @@ CI uploads the validated `RatScanner.zip` as an immutable build artifact. The se
 | Unit tests | Pure functions, contracts, regressions that were encoded | Real OCR accuracy, WebView rendering, end-user scan UX |
 | Build | Compiles against current TFMs/packages | Runtime asset presence beyond compile |
 | Manual UI | WebView wiring, CSS, navigation | Automated coverage |
-| Manual scan | End-to-end recognition path | Continuous regression without a fixture harness |
+| RatEye fixture replay | Recorded accuracy/latency for versioned captures | Every display/game configuration |
+| Manual scan | End-to-end recognition path | Continuous regression by itself |
 | Doc integrity script | Structural doc + packaging constraints | Narrative accuracy of every sentence |
 
 Do not claim “fully tested” when only `dotnet build` succeeded.
diff --git a/docs/agent-context/configuration-and-cache.md b/docs/agent-context/configuration-and-cache.md
@@ -49,10 +49,13 @@ Defined under `RatConfig.Paths` (base = exe directory):
 | `I18nDir` | `i18n` under base (UI strings) |
 | `ConfigFile` | `config.cfg` |
 | `LogFile` | `Log.txt` |
+| `Debug` | Explicitly exported scan-diagnostic bundles under `Debug/ScanDiagnostics` |
 | Dynamic EFT icon cache | Battlestate Games temp `Icon Cache` |
 
 When code assumes paths, prefer these constants over string literals.
 
+The Advanced settings page exports only the most recent in-memory scan when the user explicitly requests it. Each bundle contains the exact captured PNG and a versioned `scan.ratdiag.json` sidecar with capture/display geometry, RatEye configuration, observed results, confidence, and stage timings. Users should review screenshots before sharing them.
+
 ## API offline cache
 
 Helpers:

diff --git a/docs/agent-context/contribution-workflow.md b/docs/agent-context/contribution-workflow.md
@@ -34,6 +34,8 @@ Build CI runs for PRs targeting `master` and pushes to `master`. Releases use a
 - PRs target **`tarkovtracker-org/RatScanner`**.
 - Bare `#NNN` issue refs resolve on the **fork**. Prefer full URLs for upstream history.
 - Do not push unless asked (agents); do not force-push shared branches without explicit instruction.
+- Explicit maintainer decisions control architecture and repository ownership. Current files or generated guidance may describe a transitional state; surface conflicts instead of silently choosing a direction.
+- Never close or supersede architecture PRs, remove their remote branches, or delete source-bearing worktrees solely because another branch currently implements a different layout. Preserve the work until the maintainer-directed path is reconciled.
 
 ### Commit quality and pre-merge validation
 
@@ -64,10 +66,11 @@ When a PR changes architecture, commands, packages, CI, config paths, or behavio
 2. Update the matching `docs/agent-context/*.md`.
 3. Update nested `AGENTS.md` if scoped rules changed.
 4. Update `README.md` / `CONTRIBUTING.md` when user-facing workflow changes.
-5. Never leave agent docs claiming GraphQL bulk catalog, NuGet RatEye, or Linux support.
+5. Never leave agent docs claiming GraphQL bulk catalog, NuGet RatEye consumption, vendored RatEye, or Linux support.
 
 ## License and attribution
 
 - Keep `LICENSE` in published output.
 - Preserve “software has been modified” notices (README, Credits).
-- Scan engine provenance note: `src/ScanEngine/VENDOR.md`.
+- Scan engine source: `src/ScanEngine` submodule from `tarkovtracker-org/RatEye`.
+- When both repositories change, push the RatEye commit before any RatScanner branch that references its gitlink.