feat(magos-modificus): Phase 3 Track B mod-list, import, source model (#29)

Fills the shell content area (Track A's empty placeholder) with the
mod-list for the active profile, plus the mod source/version model that
backs it.

## Backend model
- `ModSource` (None / Nexus / GitHub) recorded on the shared entry;
versions are raw strings everywhere (GitHub release tags and Nexus file
versions are not SemVer).
- Allocation is plain string equality, which removes the `//
TODO(phase4)` version-equality wart.
- `IModImportService` (folder or `.zip` import into the shared store).
- `IModOrderResolver` + identity stub (the auto-sort seam; real
dependency algorithm deferred).

## Mod-list UI
- View / enable-disable / remove (confirmed) / reorder (up-down) /
per-mod policy (Latest or Pinned to a version string), with a read-only
source badge per row.
- Auto-sort toggle (identity stub, no-op).

## Import flow
- Split-button "Add Mod" (zip default, folder via the flyout) plus
drag-and-drop; both feed a sequential per-mod modal collecting Source +
Version + URL.
- Drag-and-drop is wired but messaged as Windows-only (Avalonia 12.0.x
lacks Linux XDND, wont-backport; PR AvaloniaUI/Avalonia#20926 lands it
in 12.1). Folder import is reachable via the picker on all platforms.

## Tests + docs
- 426 tests (backend model + services + VM logic against hand-rolled
fakes; view mechanics are live-verified).
- Reference, architecture, and AGENTS.md docs updated in place.

Author: ModifAmorphic

AGENTS.md

@@ -31,12 +31,15 @@ Requirements, architecture, and technology choices are made fresh.
   merged as the production seed; Magos Modificus has the backend libraries
   implemented (Phases 1–2) and the Phase 3 UI under construction: Track A (the app
   shell + profile management: dropdown switch, persisted active profile,
-  create/rename/delete dialog, switch-blocked-while-running) and Track D (global
+  create/rename/delete dialog, switch-blocked-while-running), Track D (global
   Preferences: theme + font scale + language, with the i18n infrastructure:
   `Strings.resx` + `LocalizationService` for dynamic culture switching, all Track
-  A UI strings backfilled to resource keys) are wired; mod-list UI (Track B) +
-  Launch behavior (Track C) are still pending, and the Launcher is a stub
-  (Phase 5).
+  A UI strings backfilled to resource keys), and Track B (the mod-list UI: view
+  mods with source/version badges, enable/disable, remove-with-confirm, reorder,
+  per-mod Latest/Pinned policy, auto-sort identity stub, and local folder/`.zip`
+  import via file picker + drag-and-drop, over the `ModSource` + raw-string version
+  model + `IModImportService`) are wired; Launch behavior (Track C) is still
+  pending, and the Launcher is a stub (Phase 5).
 - **`poc`** — historical proof-of-concept, reference only. Not built upon.
 - Development is branch + PR; no unreviewed merges to `main` (reviewed +
   covered + qa'd + CI green).
@@ -80,10 +83,15 @@ magos-modificus/        Magos Modificus — the mod manager app (.NET 10 + Avalo
   profiles/             Magos.Modificus.Profiles — profile data model, persistence,
                         shared-first staging (ProfileService.PrepareModRoot builds the
                         staged/ symlink projection + mods.lst) + SetModPolicy transitions
+                        + the auto-sort seam (IModOrderResolver/IdentityModOrderResolver,
+                        identity stub now; real dependency-driven resolver later)
   shared-mods/          Magos.Modificus.SharedMods — the global shared mod store
                         (ISharedModStore manifest) + the version-policy model
-                        (ModVersionPolicy: PinnedPolicy/LatestPolicy) + allocation
-                        resolution (AllocationResolver)
+                        (ModVersionPolicy: PinnedPolicy/LatestPolicy; version is a raw
+                        string tag) + the mod-source provenance model (ModSource:
+                        NoneSource/NexusSource/GitHubSource + ModSourceParser URL parsing)
+                        + allocation resolution (AllocationResolver, string-equality pins)
+                        + the local-import service (IModImportService: folder/.zip → store)
   integrations/         Magos.Modificus.Integrations — GitHub Releases client
                         (IGitHubClient: ListReleases/GetLatestRelease/DownloadAssetAsync
                         via IHttpClientFactory, typed exceptions, optional PAT)
@@ -175,8 +183,10 @@ dotnet run   --project magos-modificus/ui --configuration Release   # app shell
   + `IsGameRunning` — `WinProcessLookup` via process comm on Windows,
   `LinuxProcessLookup` via `/proc` argv[0] under Proton), **Integrations**
   (Phase 1: GitHub Releases client), **Enginseer-client** (Phase 1: the launch
-  façade), **SharedMods** (Phase 2: shared mod store + version-policy model +
-  allocation resolution). **General** carries cross-cutting infra: logging,
+  façade), **SharedMods** (Phase 2: shared mod store + version-policy model
+  + allocation resolution; Phase 3 Track B backend: version is a raw string tag,
+  the mod-source provenance model `ModSource` + `ModSourceParser`, and the local-
+  import service `IModImportService`; allocation uses string-equality pins). **General** carries cross-cutting infra: logging,
   `ConfigLoader` (load + `Save` write-back for Preferences), and `AppStateStore`
   (runtime app-state: the active-profile id, persisted to a separate
   `app-state.json`, not `MagosConfig`). **Phase 3 Track A UI** (the shell + profile
@@ -186,7 +196,11 @@ dotnet run   --project magos-modificus/ui --configuration Release   # app shell
   **Phase 3 Track D** (global Preferences: theme + font scale + language, plus
   the i18n infrastructure: `Strings.resx` + `LocalizationService` for dynamic
   culture switching, all Track A UI strings backfilled to resource keys) is
-  wired. Next: Track B (mod-list) and Track C (launch); the **Launcher** is a
+  wired. **Phase 3 Track B** (the mod-list UI: view mods with source/version
+  badges, enable/disable, remove-with-confirm, reorder, per-mod Latest/Pinned
+  policy, auto-sort identity stub, and local folder/`.zip` import via file picker
+  + drag-and-drop, over the `ModSource` + raw-string version model +
+  `IModImportService`) is wired. Next: Track C (launch); the **Launcher** is a
   stub (Phase 5). See `docs/architecture/MAGOS-MODIFICUS.md`.
 - **CI** (`magos-build.yml`) is scoped to `magos-modificus/**` + the workflow
   file, matrixed on Windows + Ubuntu; gates on build + tests.

docs/architecture/MAGOS-MODIFICUS.md

@@ -184,23 +184,46 @@ mod where possible while preserving per-profile version control where it's
 needed. Building this in from v1 (rather than retrofitting dedup later) keeps
 the storage model uniform.
 
-Each mod — in the shared store and in a profile — carries a version policy:
+Each mod, in the shared store and in a profile, carries a version policy:
 **pinned `<version>`** (frozen at a specific release) or **latest (auto-update)**
 (tracks the newest release). A profile's mod is resolved against the shared
 copy by policy pair:
 
 | Shared | Profile | Resolution |
 | --- | --- | --- |
-| pinned `v1.0.1` | pinned `v1.0.1` | **share** — same pin |
-| pinned `v1.0.1` | pinned `v2.0.1` | **diverge** — different pins → profile copy |
-| latest (auto-update) | latest (auto-update) | **share** — both track latest; shared is updated to latest |
-| latest (auto-update) | pinned `v2.0.1` | **diverge** — shared will move, profile won't → profile copy |
+| pinned `v1.0.1` | pinned `v1.0.1` | **share**, same pin |
+| pinned `v1.0.1` | pinned `v2.0.1` | **diverge**, different pins → profile copy |
+| latest (auto-update) | latest (auto-update) | **share**, both track latest; shared is updated to latest |
+| latest (auto-update) | pinned `v2.0.1` | **diverge**, shared will move, profile won't → profile copy |
 
 Rule: **share** iff both pinned to the same version OR both auto-update;
-otherwise **diverge**. The resolution is by *policy intent*, not current version
-— a shared auto-update mod and a profile pinned to today's same version still
+otherwise **diverge**. The resolution is by *policy intent*, not current version:
+a shared auto-update mod and a profile pinned to today's same version still
 diverge, because the shared one will move on the next release.
 
+The pin `<version>` is a **raw release tag string** (e.g. `v1.0.1`, `1.2`,
+`1.0.0-beta`), not a parsed `System.Version`. GitHub release tags + Nexus file
+versions are arbitrary strings, not SemVer, so the share check is exact string
+equality (`"1.0"` and `"1.0.0"` are genuinely different pins). There is no
+version ordering at this layer; "newer" is decided later (Phase 4) by fetching
+the latest release tag and checking string inequality.
+
+Each shared-store entry also carries a **source** (Local / Nexus / GitHub) so a
+pinned version is legible ("WeaponTweaks *(GitHub owner/repo)* pinned to
+`1.2`"). The UI collects URLs; the model stores the canonical identity (Nexus
+mod id; GitHub owner/repo) via a pure parser. Local / untracked mods default to
+the `none` source.
+
+**Import flow:** adding a mod to the active profile goes through
+`IModImportService` (the UI never touches the filesystem). The import service
+places the files (recursive copy for a folder, `ZipFile.ExtractToDirectory` for
+a `.zip`) into `<SharedModsFolder>/<modName>/`, upserts the shared-store entry
+with the declared source + version + path, then the caller adds the profile
+reference via `IProfileService.AddMod`. First import of a mod name establishes
+the shared copy (the shared-first staging); a re-import upserts (replaces files
++ metadata). Remote acquisition (Nexus / GitHub API clients, auto-fetch) stays
+in Phase 4.
+
 **Staging:** at launch (alongside regenerating `mods.lst`), Magos materializes
 the profile's mod root (the `--mod-path` dir) from the resolved set — shared
 mods linked/referenced from the shared store, diverged mods as profile-local

docs/reference/magos-modificus/profiles.md

@@ -99,8 +99,30 @@ Method behavior:
   without symlink permissions / Developer Mode). The staging layer never
   silently copies.
 
-`ModVersionPolicy` (PinnedPolicy/LatestPolicy) and `AllocationResolver` live in
-the [shared-mods](shared-mods.md) library; Profiles consumes them.
+`ModVersionPolicy` (PinnedPolicy/LatestPolicy), `ModSource`, and
+`AllocationResolver` live in the [shared-mods](shared-mods.md) library; Profiles
+consumes them.
+
+### `IModOrderResolver` + `IdentityModOrderResolver`
+
+The auto-sort seam. The mod-list UI's auto-sort toggle resolves an order via
+this interface, then applies it through `IProfileService.SetModOrder`.
+
+```csharp
+public interface IModOrderResolver
+{
+    IReadOnlyList<string> ResolveOrder(IReadOnlyList<ModListEntry> mods);
+}
+
+public sealed class IdentityModOrderResolver : IModOrderResolver;   // identity stub
+```
+
+The current implementation is the **identity stub** (`IdentityModOrderResolver`):
+it returns names in their current `ModListEntry.Order` (a no-op). The real
+dependency-driven auto-sort algorithm lands in a later phase; this interface is
+the DI-swappable seam so the UI wires against the abstraction now and the real
+resolver drops in later without a UI change. Pure + deterministic (stable on
+ties).
 
 ## DI registration
 
@@ -114,6 +136,9 @@ public static IServiceCollection AddProfiles(this IServiceCollection services);
   yields a resolvable `IProfileService`; the composition root also calls it.
 - `TryAddSingleton<SymlinkCreator>(_ => Directory.CreateSymbolicLink)` — the BCL
   default. `TryAdd` so a test may pre-register a throwing/fake delegate.
+- `TryAddSingleton<IModOrderResolver, IdentityModOrderResolver>()`: the auto-
+  sort identity stub. `TryAdd` so a test (or the real dependency-driven resolver,
+  when it lands) may pre-register an override.
 - `AddSingleton<IProfileService, ProfileService>()` — the filesystem-backed
   implementation (internal). Resolves `MagosConfig`, `ISharedModStore`,
   `SymlinkCreator`, and `ILogger<ProfileService>` from the container.