AGENTS.md

@@ -1,5 +1,7 @@
 # AGENTS.md
 
+Note: Keep AGENTS.md updated as project structure, key services, or workflows change.
+
 This repo is **OF DL** (also known as OF-DL), a C# console app that downloads media from a user's OnlyFans account(s).
 This document is for AI agents helping developers modify the project. It focuses on architecture, data flow, and the
 most important change points.
@@ -16,45 +18,46 @@ most important change points.
 
 **Project Layout**
 
-- `OF DL/Program.cs` orchestrates startup, config/auth loading, and the interactive flow.
-- `OF DL/Services/` contains application services (API, auth, download, config, DB, startup, logging, filenames).
-- `OF DL/Models/` holds configuration, auth, DTOs, entities, and mapping helpers.
-- `OF DL/Widevine/` implements Widevine CDM handling and key derivation.
-- `OF DL/CLI/` contains Spectre.Console UI helpers and progress reporting.
+- `OF DL/Program.cs` orchestrates startup, config/auth loading, and the interactive flow (CLI entrypoint).
+- `OF DL/CLI/` contains Spectre.Console UI helpers and progress reporting (CLI-only).
+- `OF DL.Core/Services/` contains application services (API, auth, download, config, DB, startup, logging, filenames).
+- `OF DL.Core/Models/` holds configuration, auth, DTOs, entities, and mapping helpers.
+- `OF DL.Core/Widevine/` implements Widevine CDM handling and key derivation.
+- `OF DL.Core/Helpers/`, `OF DL.Core/Utils/`, `OF DL.Core/Crypto/`, `OF DL.Core/Enumerations/` contain shared core logic.
 - `docs/` and `mkdocs.yml` define the documentation site.
 - `site/` is generated MkDocs output and should not be edited by hand.
 - `docker/` contains container entrypoint and supervisor configuration.
 
 **Key Services**
 
-- `ApiService` (`OF DL/Services/ApiService.cs`) builds signed headers, performs HTTP requests, and maps DTOs to
+- `ApiService` (`OF DL.Core/Services/ApiService.cs`) builds signed headers, performs HTTP requests, and maps DTOs to
   entities. It also handles DRM-related calls like MPD/PSSH extraction and license requests.
-- `AuthService` (`OF DL/Services/AuthService.cs`) loads `auth.json` or performs browser-based login with PuppeteerSharp,
+- `AuthService` (`OF DL.Core/Services/AuthService.cs`) loads `auth.json` or performs browser-based login with PuppeteerSharp,
   then persists auth. It also normalizes cookies.
-- `ConfigService` (`OF DL/Services/ConfigService.cs`) loads `config.conf` (HOCON), migrates legacy `config.json`, and
+- `ConfigService` (`OF DL.Core/Services/ConfigService.cs`) loads `config.conf` (HOCON), migrates legacy `config.json`, and
   updates global settings (logging, text sanitization).
-- `DownloadService` (`OF DL/Services/DownloadService.cs`) downloads all media (images, video, audio) and handles DRM
+- `DownloadService` (`OF DL.Core/Services/DownloadService.cs`) downloads all media (images, video, audio) and handles DRM
   video decryption and FFmpeg execution.
-- `DownloadOrchestrationService` (`OF DL/Services/DownloadOrchestrationService.cs`) coordinates user selection,
+- `DownloadOrchestrationService` (`OF DL.Core/Services/DownloadOrchestrationService.cs`) coordinates user selection,
   subscription lists, per-user folder prep, and per-media-type download execution.
-- `DBService` (`OF DL/Services/DBService.cs`) manages SQLite metadata DBs for downloaded media and a `users.db` index.
-- `StartupService` (`OF DL/Services/StartupService.cs`) validates FFmpeg, rules.json, Widevine device files, and
+- `DBService` (`OF DL.Core/Services/DBService.cs`) manages SQLite metadata DBs for downloaded media and a `users.db` index.
+- `StartupService` (`OF DL.Core/Services/StartupService.cs`) validates FFmpeg, rules.json, Widevine device files, and
   performs release version checks.
-- `LoggingService` (`OF DL/Services/LoggingService.cs`) writes logs to `logs/OFDL.txt` and updates log level based on
+- `LoggingService` (`OF DL.Core/Services/LoggingService.cs`) writes logs to `logs/OFDL.txt` and updates log level based on
   config.
-- `FileNameService` (`OF DL/Services/FileNameService.cs`) formats filenames using the custom format rules from config.
+- `FileNameService` (`OF DL.Core/Services/FileNameService.cs`) formats filenames using the custom format rules from config.
 
 **Models: DTOs vs Entities**
 
-- DTOs live under `OF DL/Models/Dtos/` and mirror API response JSON.
-- Entities live under `OF DL/Models/Entities/` and represent the internal domain used by download logic.
-- Mappers in `OF DL/Models/Mappers/` convert DTOs into entities to isolate API changes from downstream logic.
+- DTOs live under `OF DL.Core/Models/Dtos/` and mirror API response JSON.
+- Entities live under `OF DL.Core/Models/Entities/` and represent the internal domain used by download logic.
+- Mappers in `OF DL.Core/Models/Mappers/` convert DTOs into entities to isolate API changes from downstream logic.
 
 **Configuration**
 
 - Primary config file is `config.conf` (HOCON). `ConfigService` migrates legacy `config.json` if found and creates a
   default `config.conf` if missing.
-- `Config` lives in `OF DL/Models/Config.cs` and is populated by `ConfigService.LoadConfigFromFileAsync`.
+- `Config` lives in `OF DL.Core/Models/Config.cs` and is populated by `ConfigService.LoadConfigFromFileAsync`.
 - `ConfigService.UpdateConfig` is the central place where runtime config changes are applied (logging level and text
   sanitization).
 - CLI flag `--non-interactive` forces non-interactive mode; `ConfigService.IsCliNonInteractive` and
@@ -70,7 +73,7 @@ most important change points.
 
 **Authentication Flow**
 
-- Auth data is stored in `auth.json` using the `Auth` model in `OF DL/Models/Auth.cs`.
+- Auth data is stored in `auth.json` using the `Auth` model in `OF DL.Core/Models/Auth.cs`.
 - `AuthService.LoadFromBrowserAsync` launches Chrome via PuppeteerSharp, waits for login, then extracts `auth_id` and
   `sess` cookies, `bcTokenSha` from localStorage (used as `X_BC`), and `USER_AGENT` from the browser.
 - `AuthService.ValidateCookieString` rewrites the cookie string so it contains only `auth_id` and `sess` and ensures a
@@ -89,7 +92,7 @@ Environment variables used by auth:
   fallback to local `rules.json` in the current working directory. The repo ships `OF DL/rules.json` as the default
   rules file.
 - Cache durations: 15 minutes for remote rules, 5 minutes for local rules.
-- `DynamicRules` shape is defined in `OF DL/Models/DynamicRules.cs` and includes `app-token`, `static_param`, `prefix`,
+- `DynamicRules` shape is defined in `OF DL.Core/Models/DynamicRules.cs` and includes `app-token`, `static_param`, `prefix`,
   `suffix`, `checksum_constant`, and `checksum_indexes`.
 
 Signature algorithm in `GetDynamicHeaders`:
@@ -107,7 +110,7 @@ Headers included in signed requests:
 
 - Runtime Widevine device files are expected at `cdm/devices/chrome_1610/device_client_id_blob` and
   `cdm/devices/chrome_1610/device_private_key` (relative to the working directory). Paths are defined in
-  `OF DL/Widevine/Constants.cs` and validated in `StartupService`.
+  `OF DL.Core/Widevine/Constants.cs` and validated in `StartupService`.
 
 DRM flow is primarily in `DownloadService.GetDecryptionInfo` and `ApiService` DRM helpers:
 
@@ -175,12 +178,12 @@ cookies/user-agent. Output is written to `{filename}_source.mp4`, then moved and
 **Where to Look First**
 
 - `OF DL/Program.cs` for the execution path and menu flow.
-- `OF DL/Services/ApiService.cs` for OF API calls and header signing.
-- `OF DL/Services/DownloadService.cs` for downloads and DRM handling.
-- `OF DL/Services/DownloadOrchestrationService.cs` for creator selection and flow control.
-- `OF DL/Widevine/` for CDM key generation and license parsing.
-- `OF DL/Models/Config.cs` and `OF DL/Services/ConfigService.cs` for config shape and parsing.
-- `OF DL/Services/AuthService.cs` for user-facing authentication behavior and browser login flow.
+- `OF DL.Core/Services/ApiService.cs` for OF API calls and header signing.
+- `OF DL.Core/Services/DownloadService.cs` for downloads and DRM handling.
+- `OF DL.Core/Services/DownloadOrchestrationService.cs` for creator selection and flow control.
+- `OF DL.Core/Widevine/` for CDM key generation and license parsing.
+- `OF DL.Core/Models/Config.cs` and `OF DL.Core/Services/ConfigService.cs` for config shape and parsing.
+- `OF DL.Core/Services/AuthService.cs` for user-facing authentication behavior and browser login flow.
 - `docs/` for public documentation; update docs whenever user-facing behavior or configuration changes.
 
 Documentation updates for common changes: