Detect retail installations by archive presence, not executable name

[bobtista]

Detection-side complement to #315 — both turn on sentinel .big existence and should share constants.

Deliberately excluded: the *.exe glob in GameClientDetector.cs:566,742 that hides extensionless
binaries from client detection. That belongs with #325 and should consume its magic-byte
classification rather than add a second heuristic.

Problem

GameInstallation.HasValidExecutable (GameInstallation.cs:286) accepts only game.dat and
generals.exe, and it gates all detection on every platform: InstallationExtensions.ToDomain
(:86) calls SetPaths, discarding each platform detector's own HasGenerals/HasZeroHour.

So the canonical native macOS layout is undetectable. The engine's macOS deploy produces a flat
directory — engine binary, bundled dylibs, source-controlled Data//Window//Art/, and the user's
own .big archives merged into one tree, by default ~/TheSuperHackers/GeneralsZH/. That is not a
search root, not a name-matched child, and its binary is extensionless.

Alpha 5 launches the native client against the user's retail data, but the archive roots come from
GameInstallation.ZeroHourPath, so there is nothing to supply them.

generals.exe was only ever a proxy for "the archives are here." The archives are the direct signal
and the thing $CNC_ZH_INSTALLPATH actually needs.

Approach

All three parts are needed together:

1. Identify retail data by archive presence instead of executable name.
   Zero Hour is any *zh.big; Generals is any of the canonical set — audio.big,
   audioenglish.big, english.big, gensec.big, ini.big, maps.big, music.big,
   shaders.big, speech.big, speechenglish.big, terrain.big, textures.big, w3d.big,
   window.big. Share constants with Validate retail archive roots before launch #315.
   These are retail filenames — verified present in a retail Zero Hour installation, which is
   what GenHub is identifying. Deliberately not derived from any engine build's loading code,
   so the rule stays valid for a user running a stock retail install with no community client.
   Check the directory root only, not recursively: Data/INI/INIZH.big is a duplicate shipped in
   the English, Chinese and Korean SKUs and must not be counted twice.
2. MacOSInstallationDetector must test the candidate directory itself, not only name-matched
   immediate children.
3. Keep GameInstallation.Fetch() in step — it is a second implementation of the same question.

Main hazard: a combined directory has both INI.big and INIZH.big, so both flags become true —
an unexercised state. ManifestProvider.cs:182,236 does HasZeroHour ? ZeroHour : Generals, so
Generals silently never gets a manifest. Also affects GameClientDetector.cs:58,87 (same directory
scanned twice), WindowsInstallationDetector.cs:209-269 (dedup does not collapse this case), and
InstallationPathResolver.cs:99-108.

Acceptance

• A flat directory with INI.big and INIZH.big yields one installation with both paths set, and
  both manifests generated.
• No duplicate GameClient entries when both paths are equal.
• Steam, EA App, Wine, Lutris and CD/ISO detection unchanged on Windows and Linux.
• ~/TheSuperHackers/GeneralsZH detected with no environment overrides, producing correct
  CNC_ZH_INSTALLPATH/CNC_GENERALS_INSTALLPATH including the mandatory trailing separator.

Own PR off development — not folded into the mac stack, since the ManifestProvider change is
user-visible on Windows retail and needs deliberate review.

[coderabbitai]

🔗 Related PRs

#305 - fix(manifest): use JSON file pattern during discovery [merged]
#328 - feat(platform): make paths, manifests, and Unix workspaces platform-aware [merged]
#329 - feat(macos): add native host, installation detection, and CI [merged]
#331 - fix(macos): register the platform services the merged state requires [merged]
#332 - feat(launching): launch the native BGFX client against retail archives [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Centralize .big sentinel filenames as shared constants and make archive presence (not executable name) the single detection signal in GameInstallation, keeping HasValidExecutable, SetPaths, and Fetch() in lockstep.
• Fix the combined-directory state end to end: generate manifests for both game types, dedup identical-path client detection, and collapse combined directories in Windows dedup.
• Add a greenfield GenHub.MacOS project and MacOSInstallationDetector that inspects the candidate directory itself for the sentinels and produces launch-ready, trailing-separator paths, wired via a MacServicesModule the orchestrator discovers automatically.
• Preserve all existing Windows/Linux detection behavior and defer the *.exe glob change to #325.

Design Choices

Design Choice 1: Which GameInstallationType should represent the native macOS flat-directory install?

Options Considered:

1. Reuse the existing Retail value (no enum/switch changes).
2. Add a new MacOS (or MacOSRetail) value and update the five exhaustive switches in InstallationExtensions.cs.

Chosen Option: 2

Rationale: A dedicated value makes the detection source explicit and traceable in logs/UI, at the cost of updating the existing switch expressions; this matches the precedent of distinct per-source enum values. The enum has no macOS value; the macOS layout is a retail-style flat directory with no packaging metadata.

Design Choice 2: How should ManifestProvider.GetManifestAsync(GameInstallation, ...) produce two manifests for a combined installation?

Options Considered:

1. Add an explicit GameType parameter and have callers request each game type they need.
2. Keep the existing entry point but internally generate/return manifests for every present game type.

Chosen Option: 1

Rationale: An explicit GameType parameter keeps each manifest's deterministic ID, source path, and pool entry cleanly separated, avoids ambiguous return shapes, and lets callers iterate the flags they already own. Today it short-circuits to a single GameType, so Generals never gets a manifest when both flags are true.

Design Choice 3: Where do the CNC_ZH_INSTALLPATH/CNC_GENERALS_INSTALLPATH env vars and the mandatory trailing separator live?

Options Considered:

1. Build the full launch-time env-var pipeline in this PR.
2. Provide a reusable trailing-separator path helper and ensure the macOS detector stores launch-ready GeneralsPath/ZeroHourPath, leaving env-var wiring to the mac stack that already reads those paths.

Chosen Option: 2

Rationale: This ticket is the detection-side complement; the mac stack already reads GameInstallation.ZeroHourPath, so the correct scope here is producing correctly-formatted (trailing-separator) paths plus a shared helper, not the launch pipeline itself. No launch-time env-var construction or trailing-separator utility exists; the native client launch ("Alpha 5") lives in the separate mac stack.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Archive-based detection and shared sentinel constants

Establish .big archive presence as the single source of truth for whether Generals/Zero Hour data exists in a directory, replacing the degenerate generals.exe/game.dat executable check. This phase centralizes the sentinel filenames as shared constants (the contract shared with #315) and aligns both detection code paths in the core model so they cannot diverge.

Task 1: Add shared .big archive sentinel constants

Introduce the canonical sentinel filenames used by both detection and #315.

• Add a new // ===== Game Archive Sentinel Files ===== section to GenHub.Core/Constants/GameClientConstants.cs following the existing const + aggregate-array style.
• Define individual constants for the Zero Hour sentinel (INIZH.big) and the Generals sentinels (INI.big, Generals.big), each with XML-doc summaries.
• Expose per-game aggregate IReadOnlyList<string> collections (e.g., Generals sentinels vs Zero Hour sentinel) so detection code can check "any present" without duplicating literals.

Task 2: Convert GameInstallation detection to archive presence

Replace executable-name gating with game-type-aware archive detection while keeping the two detection routines consistent.

• In GenHub.Core/Models/GameInstallations/GameInstallation.cs, replace the HasValidExecutable helper with game-type-aware archive checks (e.g., "directory contains a Generals sentinel" and "directory contains the Zero Hour sentinel"), using FileExistsCaseInsensitive and the new constants.
• Update SetPaths so the Generals path is validated against the Generals sentinels and the Zero Hour path against the Zero Hour sentinel, allowing both flags to be true when a single (combined) directory contains both.
• Update Fetch() to use the same archive-based checks so it remains a faithful second implementation of the same question rather than diverging on executable names.
• Confirm IsValid continues to rely on directory existence and does not reintroduce an executable check.

Task 3: Preserve platform detector flags through ToDomain

Ensure the domain re-validation cannot silently discard a platform detector's correct result.

• Review GenHub.Core/Extensions/GameInstallations/InstallationExtensions.cs ToDomain/ValidateInstallation so that the archive-based SetPaths re-validation is consistent with (and does not undo) the platform detectors' findings.
• Ensure the Windows/Linux detectors (Steam, EA App, CD/ISO, Wine, Lutris) still yield unchanged results after this re-validation, satisfying the "detection unchanged on Windows and Linux" acceptance criterion.

🤖 Prompt for AI agents

Implement archive-presence detection as the single source of truth for
Generals/Zero Hour data, replacing the executable-name check, and centralize the
sentinel filenames as shared constants.

- Add a new `// ===== Game Archive Sentinel Files =====` section to
`GenHub.Core/Constants/GameClientConstants.cs`, following the existing const +
aggregate-array style. Define constants for the Zero Hour sentinel (`INIZH.big`)
and the Generals sentinels (`INI.big`, `Generals.big`), each with XML-doc
summaries. Expose per-game aggregate `IReadOnlyList<string>` collections so
detection code can check "any present" without duplicating literals.
- In `GenHub.Core/Models/GameInstallations/GameInstallation.cs`, replace the
private `HasValidExecutable` helper with game-type-aware archive checks
(Generals sentinels vs Zero Hour sentinel), using `FileExistsCaseInsensitive`
and the new constants.
- Update `SetPaths` so the Generals path is validated against the Generals
sentinels and the Zero Hour path against the Zero Hour sentinel, allowing both
`HasGenerals` and `HasZeroHour` to be true when a single (combined) directory
contains both sets of archives.
- Update `Fetch()` to use the same archive-based checks so both detection
routines stay in lockstep rather than diverging on executable names.
- Confirm `IsValid` continues to rely on directory existence only, without
reintroducing an executable check.
- Review `GenHub.Core/Extensions/GameInstallations/InstallationExtensions.cs`
`ToDomain`/`ValidateInstallation` so the archive-based `SetPaths` re-validation
stays consistent with, and does not undo, the platform detectors' findings.
Verify Windows/Linux detectors (Steam, EA App, CD/ISO, Wine, Lutris) still yield
unchanged results after this re-validation.

Phase 2: Combined-directory correctness across the pipeline

Handle the previously-unexercised state where one directory holds both games' archives so that both flags being true no longer causes a missing manifest, duplicate clients, or broken dedup. This is the user-visible portion on Windows retail and warrants deliberate review.

Task 1: Generate manifests for both game types when both are present

Stop biasing manifest generation toward Zero Hour when both flags are true.

• Refactor ManifestProvider.GetManifestAsync(GameInstallation, ...) (the HasZeroHour ? ZeroHour : Generals logic and its fallback-generation branch) to operate on an explicit GameType rather than deriving a single type from the installation.
• Ensure each game type resolves its own source path (GeneralsPath vs ZeroHourPath, which may be equal in a combined install), its own deterministic ID, and its own manifest version constant.
• Update callers (notably GameInstallationService.PopulateGameClientsAndManifestsAsync and any other consumers) to request a manifest for each present game type, so a combined directory yields both manifests.

Task 2: Deduplicate client detection for combined directories

Prevent duplicate GameClient entries when GeneralsPath == ZeroHourPath.

• In GenHub/Features/GameClients/GameClientDetector.cs, detect the combined-directory case (equal Generals/Zero Hour paths) and avoid scanning/hashing the shared directory twice, while still producing the correct GameClient record(s).
• Add dedup keyed on installation + executable path (and game type where appropriate) so identical executables are not emitted twice; explicitly leave the *.exe glob behavior at the referenced lines untouched (that belongs to #325).

Task 3: Collapse combined directories in Windows dedup

Make Windows dedup aware that one directory can legitimately supply both games.

• Review WindowsInstallationDetector.DeduplicateInstallations so a single installation whose Generals and Zero Hour paths point at the same directory is retained as one installation with both flags set, rather than being partially stripped or dropped.
• Preserve the existing priority-based path-claiming behavior for genuinely distinct sources so Windows/Linux detection remains unchanged.

🤖 Prompt for AI agents

Fix end-to-end handling of the combined-directory state (one directory holding
both games' archives, both `HasGenerals` and `HasZeroHour` true) across manifest
generation, client detection, and Windows dedup.

- Refactor `ManifestProvider.GetManifestAsync(GameInstallation, ...)`, replacing
the `HasZeroHour ? ZeroHour : Generals` ternary and its fallback-generation
branch, to accept/operate on an explicit `GameType` rather than deriving a
single type from the installation. Each game type must resolve its own source
path (`GeneralsPath` vs `ZeroHourPath`, which may be equal in a combined
install), its own deterministic ID, and its own manifest version constant.
- Update callers of `GetManifestAsync`, notably
`GameInstallationService.PopulateGameClientsAndManifestsAsync` and any other
consumers, to request a manifest for each present game type so a combined
directory yields both manifests.
- In `GenHub/Features/GameClients/GameClientDetector.cs`, detect the
combined-directory case where `GeneralsPath == ZeroHourPath` and avoid
scanning/hashing the shared directory twice, while still producing the correct
`GameClient` record(s). Add dedup keyed on installation + executable path (and
game type where appropriate) so identical executables are not emitted twice. Do
not modify the `*.exe` glob behavior at the referenced lines — that is reserved
for a separate ticket (`#325`).
- Review `WindowsInstallationDetector.DeduplicateInstallations` so a single
installation whose Generals and Zero Hour paths point at the same directory is
retained as one installation with both flags set, rather than being partially
stripped or dropped. Preserve the existing priority-based path-claiming behavior
for genuinely distinct sources so Windows/Linux detection remains unchanged.

Phase 3: macOS detector and launch-ready paths

Add the greenfield macOS detector that recognizes the flat ~/TheSuperHackers/GeneralsZH/ layout by testing the candidate directory itself (not only name-matched children), wire it into DI following the existing platform pattern, and ensure detected paths are launch-ready for the native client.

Task 1: Add a trailing-separator path helper

Provide the reusable formatting utility the native launch requires.

• Add an EnsureTrailingSeparator (or equivalently named) static method to GenHub.Core/Helpers/PathHelper.cs that guarantees a single trailing directory separator.
• Keep this opt-in so Windows/Linux path comparisons and dedup are not affected globally.

Task 2: Introduce the macOS installation type and mapping

Represent the macOS flat-directory install as a first-class source.

• Add a macOS value to GenHub.Core/Models/Enums/GameInstallationType.cs.
• Update the exhaustive switch expressions in InstallationExtensions.cs (GetDisplayName, ToIdentifierString, SupportsAutomaticUpdates, ToInstallationSourceString, ToPublisherTypeString) to map the new value.

Task 3: Create the GenHub.MacOS project and detector

Mirror the existing Windows/Linux platform-project pattern.

• Add a new GenHub.MacOS class library (registered in GenHub.sln) mirroring the GenHub.Linux layout.
• Implement MacOSInstallationDetector : IGameInstallationDetector, self-gated via RuntimeInformation.IsOSPlatform(OSPlatform.OSX), that checks the default ~/TheSuperHackers/GeneralsZH/ root (with no environment overrides) by inspecting the candidate directory itself for the .big sentinels, then builds a GameInstallation via ToDomain.
• Use the trailing-separator helper so the detector stores launch-ready GeneralsPath/ZeroHourPath, and correctly yields a single combined installation with both paths set when both sentinels are present.

Task 4: Wire macOS DI registration

Register the detector so the orchestrator picks it up automatically.

• Add a MacServicesModule with an AddMacServices extension (guarded by [SupportedOSPlatform("macos")]) registering MacOSInstallationDetector as IGameInstallationDetector, following WindowsServicesModule/LinuxServicesModule.
• Add the corresponding Program.cs entry point invoking ConfigureApplicationServices(s => s.AddMacServices()), mirroring the Linux entry point.

Task 5: Update documentation

Reflect the new detector and detection strategy.

• Add a macOS detector node to docs/FlowCharts/Detection-Flow.md (sibling to the Windows/Linux nodes) and add macOS to the platform matrix/summary in docs/features/game-installations/index.md.
• Note the shift from executable-name to archive-presence detection where relevant.

🤖 Prompt for AI agents

Add the greenfield macOS installation detector for the flat
`~/TheSuperHackers/GeneralsZH/` layout, wire it into DI, and ensure detected
paths are launch-ready.

- Add an `EnsureTrailingSeparator` (or equivalently named) static method to
`GenHub.Core/Helpers/PathHelper.cs` that guarantees a single trailing directory
separator. Keep this opt-in so it does not globally affect Windows/Linux path
comparisons and dedup.
- Add a macOS value to `GenHub.Core/Models/Enums/GameInstallationType.cs`.
Update the exhaustive switch expressions in `InstallationExtensions.cs`
(`GetDisplayName`, `ToIdentifierString`, `SupportsAutomaticUpdates`,
`ToInstallationSourceString`, `ToPublisherTypeString`) to map the new value.
- Add a new `GenHub.MacOS` class library project (registered in `GenHub.sln`),
mirroring the layout of the existing `GenHub.Linux` project.
- Implement `MacOSInstallationDetector : IGameInstallationDetector`, self-gated
via `RuntimeInformation.IsOSPlatform(OSPlatform.OSX)`. It should check the
default `~/TheSuperHackers/GeneralsZH/` root with no environment overrides,
inspecting the candidate directory itself (not only name-matched children) for
the `.big` sentinels, then build a `GameInstallation` via `ToDomain`. Use the
trailing-separator helper so the detector stores launch-ready
`GeneralsPath`/`ZeroHourPath`, correctly yielding a single combined installation
with both paths set when both sentinels are present.
- Add a `MacServicesModule` with an `AddMacServices` extension guarded by
`[SupportedOSPlatform("macos")]`, registering `MacOSInstallationDetector` as
`IGameInstallationDetector`, following the pattern of
`WindowsServicesModule`/`LinuxServicesModule`. Add a corresponding `Program.cs`
entry point invoking `ConfigureApplicationServices(s => s.AddMacServices())`,
mirroring the Linux entry point.
- Update `docs/FlowCharts/Detection-Flow.md` with a macOS detector node (sibling
to the Windows/Linux nodes) and update the platform matrix/summary in
`docs/features/game-installations/index.md` to include macOS, noting the shift
from executable-name to archive-presence detection where relevant.

Research

Codebase Summary

Installation detection is orchestrated by the platform-agnostic GameInstallationDetectionOrchestrator, which aggregates results from every registered IGameInstallationDetector (currently only WindowsInstallationDetector and LinuxInstallationDetector, self-gated via CanDetectOnCurrentPlatform). Platform detectors populate a neutral GameInstallation model (HasGenerals/HasZeroHour/GeneralsPath/ZeroHourPath) through SetPaths, whose truthiness is gated by the private HasValidExecutable helper (which today only recognizes generals.exe). InstallationExtensions.ToDomain re-runs SetPaths when converting a platform installation to the domain model, and GameInstallation.Fetch() is a second, independent detection routine covering the same question. Downstream, ManifestProvider.GetManifestAsync maps an installation to exactly one GameType via a HasZeroHour ? ZeroHour : Generals ternary, and GameClientDetector scans GeneralsPath and ZeroHourPath in two independent, non-deduplicated passes. Shared naming lives in GenHub.Core/Constants/GameClientConstants.cs; there is no macOS project, no .big constants, no InstallationPathResolver.cs, and no CNC_* environment-variable or trailing-separator handling in the codebase today.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement archive-presence detection as the single source of truth for
Generals/Zero Hour data, replacing the executable-name check, and centralize the
sentinel filenames as shared constants.

- Add a new `// ===== Game Archive Sentinel Files =====` section to
`GenHub.Core/Constants/GameClientConstants.cs`, following the existing const +
aggregate-array style. Define constants for the Zero Hour sentinel (`INIZH.big`)
and the Generals sentinels (`INI.big`, `Generals.big`), each with XML-doc
summaries. Expose per-game aggregate `IReadOnlyList<string>` collections so
detection code can check "any present" without duplicating literals.
- In `GenHub.Core/Models/GameInstallations/GameInstallation.cs`, replace the
private `HasValidExecutable` helper with game-type-aware archive checks
(Generals sentinels vs Zero Hour sentinel), using `FileExistsCaseInsensitive`
and the new constants.
- Update `SetPaths` so the Generals path is validated against the Generals
sentinels and the Zero Hour path against the Zero Hour sentinel, allowing both
`HasGenerals` and `HasZeroHour` to be true when a single (combined) directory
contains both sets of archives.
- Update `Fetch()` to use the same archive-based checks so both detection
routines stay in lockstep rather than diverging on executable names.
- Confirm `IsValid` continues to rely on directory existence only, without
reintroducing an executable check.
- Review `GenHub.Core/Extensions/GameInstallations/InstallationExtensions.cs`
`ToDomain`/`ValidateInstallation` so the archive-based `SetPaths` re-validation
stays consistent with, and does not undo, the platform detectors' findings.
Verify Windows/Linux detectors (Steam, EA App, CD/ISO, Wine, Lutris) still yield
unchanged results after this re-validation.
===============================================================================

Task: 2

Fix end-to-end handling of the combined-directory state (one directory holding
both games' archives, both `HasGenerals` and `HasZeroHour` true) across manifest
generation, client detection, and Windows dedup.

- Refactor `ManifestProvider.GetManifestAsync(GameInstallation, ...)`, replacing
the `HasZeroHour ? ZeroHour : Generals` ternary and its fallback-generation
branch, to accept/operate on an explicit `GameType` rather than deriving a
single type from the installation. Each game type must resolve its own source
path (`GeneralsPath` vs `ZeroHourPath`, which may be equal in a combined
install), its own deterministic ID, and its own manifest version constant.
- Update callers of `GetManifestAsync`, notably
`GameInstallationService.PopulateGameClientsAndManifestsAsync` and any other
consumers, to request a manifest for each present game type so a combined
directory yields both manifests.
- In `GenHub/Features/GameClients/GameClientDetector.cs`, detect the
combined-directory case where `GeneralsPath == ZeroHourPath` and avoid
scanning/hashing the shared directory twice, while still producing the correct
`GameClient` record(s). Add dedup keyed on installation + executable path (and
game type where appropriate) so identical executables are not emitted twice. Do
not modify the `*.exe` glob behavior at the referenced lines — that is reserved
for a separate ticket (`#325`).
- Review `WindowsInstallationDetector.DeduplicateInstallations` so a single
installation whose Generals and Zero Hour paths point at the same directory is
retained as one installation with both flags set, rather than being partially
stripped or dropped. Preserve the existing priority-based path-claiming behavior
for genuinely distinct sources so Windows/Linux detection remains unchanged.
===============================================================================

Task: 3

Add the greenfield macOS installation detector for the flat
`~/TheSuperHackers/GeneralsZH/` layout, wire it into DI, and ensure detected
paths are launch-ready.

- Add an `EnsureTrailingSeparator` (or equivalently named) static method to
`GenHub.Core/Helpers/PathHelper.cs` that guarantees a single trailing directory
separator. Keep this opt-in so it does not globally affect Windows/Linux path
comparisons and dedup.
- Add a macOS value to `GenHub.Core/Models/Enums/GameInstallationType.cs`.
Update the exhaustive switch expressions in `InstallationExtensions.cs`
(`GetDisplayName`, `ToIdentifierString`, `SupportsAutomaticUpdates`,
`ToInstallationSourceString`, `ToPublisherTypeString`) to map the new value.
- Add a new `GenHub.MacOS` class library project (registered in `GenHub.sln`),
mirroring the layout of the existing `GenHub.Linux` project.
- Implement `MacOSInstallationDetector : IGameInstallationDetector`, self-gated
via `RuntimeInformation.IsOSPlatform(OSPlatform.OSX)`. It should check the
default `~/TheSuperHackers/GeneralsZH/` root with no environment overrides,
inspecting the candidate directory itself (not only name-matched children) for
the `.big` sentinels, then build a `GameInstallation` via `ToDomain`. Use the
trailing-separator helper so the detector stores launch-ready
`GeneralsPath`/`ZeroHourPath`, correctly yielding a single combined installation
with both paths set when both sentinels are present.
- Add a `MacServicesModule` with an `AddMacServices` extension guarded by
`[SupportedOSPlatform("macos")]`, registering `MacOSInstallationDetector` as
`IGameInstallationDetector`, following the pattern of
`WindowsServicesModule`/`LinuxServicesModule`. Add a corresponding `Program.cs`
entry point invoking `ConfigureApplicationServices(s => s.AddMacServices())`,
mirroring the Linux entry point.
- Update `docs/FlowCharts/Detection-Flow.md` with a macOS detector node (sibling
to the Windows/Linux nodes) and update the platform matrix/summary in
`docs/features/game-installations/index.md` to include macOS, noting the shift
from executable-name to archive-presence detection where relevant.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[bobtista]

Note on the relationship with #315, now that its implementation is in place
(GameLauncher.ValidateRetailArchiveRoots).

The two predicates stay separate. #315 uses a game-agnostic sentinel — at least one .big in the
root — because it validates a root that has already been chosen, and a specific filename varies by
localisation and version. This issue classifies an unknown directory by game. Making #315 adopt the
game-specific rule would make it stricter and could reject a valid root, so its behaviour stays as-is.

What is shared is the vocabulary, not the verb:

1. RetailArchiveConstants — the .big extension, the zh.big suffix, the canonical Generals set.
2. A root-only, case-insensitive enumeration helper.
3. Two predicates on top: HasAnyArchive(root) for Validate retail archive roots before launch #315, ClassifyArchives(dir) here.

This PR owns the extraction, since it is where the second consumer appears. That keeps the mac
stack untouched and avoids a speculative refactor ahead of a real need.

One deliberate behaviour change rides along. EnumerateFiles(root, "*.big", …) does not match
INIZH.BIG on a case-sensitive volume, and retail data copied from a disc or a Windows machine is
frequently upper-cased. #315 therefore has a latent failure on such volumes — a valid root is
rejected with "contains no .big archives" and the launch is blocked. Fixing it once in the shared
helper serves both call sites; it should be called out in the PR description rather than folded in
silently.

[bobtista]

Correction to my previous comment: the case-sensitivity fix no longer rides along with this issue.
It has landed in #315 instead, so that the mac stack does not ship a window where a valid
upper-cased retail root is rejected and the launch blocked.

What remains here is unchanged — the extraction of the shared vocabulary:

1. RetailArchiveConstants — the .big extension, the zh.big suffix, the canonical Generals set.
2. A root-only, case-insensitive enumeration helper.
3. Two predicates on top: HasAnyArchive(root) for Validate retail archive roots before launch #315, ClassifyArchives(dir) here.

ValidateRetailArchiveRoots now carries its own EnumerationOptions with
MatchCasing = CaseInsensitive and IgnoreInaccessible = false. When the shared helper is extracted,
it must preserve both settings — the second is easy to lose, since it defaults to true and silently
converts a permission error into "no archives found".

[bobtista]

Scope update — part of the extraction described above already exists on feat/native-launch (#332),
so this issue is smaller than originally written.

Already landed there: GenHub.Core/Constants/RetailArchiveConstants.cs, holding the install-path
variable names, ArchiveSearchPattern (*.big), and now an ArchiveSearch EnumerationOptions with
MatchCasing = CaseInsensitive and IgnoreInaccessible = false. The case-sensitivity fix landed there
too rather than waiting for this issue.

What remains here:

1. Add the game classification vocabulary to the same constants class — the zh.big suffix and the
   canonical Generals set of retail archive filenames listed in the issue body. (An earlier revision
   of this comment cited GetBIGLoadPriority as the source of that set; that function is fork-only
   and citing it violated the body's own grounding rule. The set is a retail fact, verifiable
   against a real installation, which is the only grounding it needs.)
2. ClassifyArchives(dir) returning which games' archives are present, built on the existing
   ArchiveSearch options so both call sites match files identically.
3. Everything in the issue body above: the detector root handling, keeping Fetch() in step, and the
   four both-flags hazards.

ValidateRetailArchiveRoots keeps its game-agnostic HasAnyArchive semantics unchanged.

One caveat worth carrying forward. Validate_WithUpperCasedArchive_Accepts only exercises the
case-sensitivity regression on a case-sensitive volume — in practice Linux CI. The SearchOption
overload matched with MatchCasing.PlatformDefault, which is already case-insensitive on macOS and
Windows, so the test passes on those platforms whether or not the fix is present. Any test written
here for ClassifyArchives has the same limitation and should say so rather than imply local coverage.