Refactor analysis logic into focused modules with macOS separation

docs/AGENTS.md

@@ -224,6 +224,27 @@ Minor helper changes that do not alter behavior may proceed, but must still be r
 - Keep one clear orchestrator per workflow and move helper policies/utilities/IO/details to focused companion files.
 - Treat structural refactors as behavior-preserving by default (no runtime/UI changes unless explicitly requested).
 
+## File naming rules
+
+- File names must use letters only (`A-Z`, `a-z`) by default.
+- Use `PascalCase` and compose names from:
+  - feature/domain prefix,
+  - concrete responsibility,
+  - role suffix.
+- Match existing repository patterns, for example:
+  - `AnalysisLogicMacOSCompatibility.swift`
+  - `MacOSDiscoveryCatalogParser.swift`
+  - `MacOSDownloadOrchestrator.swift`
+  - `MacOSDownloaderListView.swift`
+- The underscore (`_`) is allowed only when an external or required structure mandates it (for example GitHub workflow conventions).
+- Do not use spaces, hyphens, digits, or other special characters in file names unless required by external format constraints.
+
+## Large file split rule
+
+- If a file becomes materially larger after a change (many additional lines), the agent must explicitly evaluate whether splitting it into smaller focused files makes sense.
+- When a split is reasonable, the agent should propose the split before implementation or include the split in the same change when safe.
+- Splits should preserve behavior and separate concerns (orchestrator vs helpers/policies/parsers/ui parts).
+
 ## Branch naming convention
 
 When branch creation is requested:

docs/reference/core/FILE_STRUCTURE.md

@@ -13,6 +13,22 @@
 - `macUSB/Features/Finish/*` — result and cleanup UX.
 - `macUSB/Features/Downloader/*` — downloader coordinator + UI + logic split.
 
+### Analysis layout
+
+- `macUSB/Features/Analysis/SystemAnalysisView.swift` — analysis UI screen.
+- `macUSB/Features/Analysis/AnalysisLogic.swift` — analysis state + facade API for UI bindings.
+- `macUSB/Features/Analysis/AnalysisSelectionHandoff.swift` — handoff bridge for pending installer URL from downloader flow.
+- `macUSB/Features/Analysis/AnalysisNotifications.swift` — shared `Notification.Name` constants used by analysis/flow wiring.
+- `macUSB/Features/Analysis/Logic/AnalysisLogicFileSelection.swift` — file selection/drop/open-panel logic.
+- `macUSB/Features/Analysis/Logic/AnalysisLogicAnalysisFlow.swift` — orchestration of analysis execution for `.app` and image sources.
+- `macUSB/Features/Analysis/Logic/macOS/AnalysisLogicMacOSCompatibility.swift` — macOS-only compatibility/version-family detection rules and flag mapping.
+- `macUSB/Features/Analysis/Logic/macOS/AnalysisLogicMacOSImageMounting.swift` — image mounting + mounted-source guard + legacy image read logic.
+- `macUSB/Features/Analysis/Logic/macOS/AnalysisLogicMacOSInstallerMetadata.swift` — installer metadata/version parsing and USB capacity mapping helpers.
+- `macUSB/Features/Analysis/Logic/macOS/AnalysisLogicMacOSInstallerIcon.swift` — installer icon discovery.
+- `macUSB/Features/Analysis/Logic/AnalysisLogicUsbDrives.swift` — USB drive enumeration/refresh/capacity checks.
+- `macUSB/Features/Analysis/Logic/macOS/AnalysisLogicMacOSLifecycle.swift` — reset/cleanup/manual Tiger flow helpers.
+- Reserved naming for future non-macOS support: `AnalysisLogicLinuxCompatibility.swift` (not implemented yet).
+
 ### Downloader layout
 
 - `macUSB/Features/Downloader/MacOSDownloaderCoordinator.swift`

docs/reference/features/analysis/ANALYSIS_COMPATIBILITY.md

@@ -1,5 +1,7 @@
 # Analysis and Compatibility Contract
 
+Current implementation scope of this contract is the macOS analysis path (see `AnalysisLogicMacOSCompatibility.swift`).
+
 ## Detection Source of Truth
 
 Analysis flags are the source of truth for workflow branch selection.

macUSB.xcodeproj/project.pbxproj

@@ -107,6 +107,16 @@
 				App/ContentView.swift,
 				App/macUSBApp.swift,
 				Features/Analysis/AnalysisLogic.swift,
+				Features/Analysis/AnalysisNotifications.swift,
+				Features/Analysis/AnalysisSelectionHandoff.swift,
+				Features/Analysis/Logic/AnalysisLogicAnalysisFlow.swift,
+				Features/Analysis/Logic/AnalysisLogicFileSelection.swift,
+				Features/Analysis/Logic/AnalysisLogicUsbDrives.swift,
+				Features/Analysis/Logic/macOS/AnalysisLogicMacOSCompatibility.swift,
+				Features/Analysis/Logic/macOS/AnalysisLogicMacOSImageMounting.swift,
+				Features/Analysis/Logic/macOS/AnalysisLogicMacOSInstallerIcon.swift,
+				Features/Analysis/Logic/macOS/AnalysisLogicMacOSInstallerMetadata.swift,
+				Features/Analysis/Logic/macOS/AnalysisLogicMacOSLifecycle.swift,
 				Features/Analysis/SystemAnalysisView.swift,
 				Features/Downloader/Logic/Assembly/MacOSAssemblyFileUtils.swift,
 				Features/Downloader/Logic/Assembly/MacOSAssemblyLegacyFlow.swift,