chore(deps): upgrade target frameworks to .NET 8/10 and update dependencies

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "refs/Gymnasium"]
+	path = refs/Gymnasium
+	url = https://github.com/Farama-Foundation/Gymnasium.git

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 1. Project Overview
+
+Gym.NET is a native C# (.NET) port of OpenAI Gym / Farama Gymnasium, providing a standardized reinforcement learning environment toolkit and benchmark suite. It is part of the SciSharp STACK ecosystem and uses `NumSharp` for multidimensional tensor/array operations and `SixLabors.ImageSharp` for rendering.
+
+- **Canonical SOT Submodule:** `refs/Gymnasium` (Farama Foundation Gymnasium Git submodule for behavioral, mathematical, and algorithmic parity).
+
+---
+
+## 2. Solution & Project Architecture
+
+The repository is structured around the `Gym.NET.sln` solution:
+
+```
+refs/Gym.NET/
+├── src/
+│   ├── Gym/                       # Core abstractions, spaces, vector environments, threading
+│   │   ├── Envs/                  # IEnv, Env, GoalEnv, VecEnv, DummyVecEnv, VecEnvWrapper
+│   │   ├── Spaces/                # Space (base), Box (bounded/continuous), Discrete
+│   │   ├── Observations/          # Step (Observation, Reward, Done, Information)
+│   │   ├── Internal/              # Dict, CircularQueue, DistributedScheduler, Threading
+│   │   └── Exceptions/            # InvalidActionError, AlreadySteppingError, NotSteppingError
+│   │
+│   ├── Gym.Environments/          # Concrete environment implementations
+│   │   ├── Envs/Classic/          # CartPoleEnv (CartPole-v1)
+│   │   ├── Envs/Aether/           # LunarLanderEnv (Aether.Physics2D 2D physics simulation)
+│   │   └── Rendering/             # IEnvViewer, IEnvironmentViewerFactoryDelegate, NullEnvViewer
+│   │
+│   ├── Gym.Rendering.Avalonia/    # Cross-platform GUI rendering (AvaloniaEnvViewer, StaticAvaloniaApp)
+│   └── Gym.Rendering.WinForm/     # Windows Forms GUI rendering (WinFormEnvViewer)
+│
+├── tests/
+│   └── Gym.Tests/                 # MSTest test suite for environments, spaces, and multi-instance concurrency
+│
+├── examples/                      # Standalone reinforcement learning sample runners
+│   └── ReinforcementLearning/     # CartPole neural network training via parameters vs image observations
+│
+└── refs/
+    └── Gymnasium/                 # Submodule: Farama-Foundation/Gymnasium (Python Master SOT)
+```
+
+### Core Design Patterns & Mechanisms
+
+- **Environment Contract (`IEnv` / `Env`):** Standard RL lifecycle methods:
+  - `NDArray Reset()`: Resets the state and returns the initial observation.
+  - `Step Step(object action)`: Steps environment dynamics; returns `(Observation, Reward, Done, Information)`.
+  - `Image Render(string mode = "human")`: Generates/renders frame via `SixLabors.ImageSharp`.
+  - `void Seed(int seed)`: Seeds pseudorandom number generators via `NumPyRandom`.
+  - `void CloseEnvironment()` / `Dispose()`: Releases rendering and physics resources.
+- **Pluggable Viewer Architecture:** Environments accept an `IEnvironmentViewerFactoryDelegate` allowing execution in headless mode (`NullEnvViewer.Factory`) or interactive GUI mode (`AvaloniaEnvViewer.Factory`, `WinFormEnvViewer.Factory`).
+- **Vectorized Environments (`IVecEnv` / `VecEnv` / `DummyVecEnv`):** Synchronous/asynchronous batch stepping across multiple parallel environment instances.
+- **Observation & Action Spaces:** Strongly-typed bounds checking and random sampling via `Box` (multi-dimensional continuous floats/bounds) and `Discrete` (categorical integer actions).
+
+---
+
+## 3. Build & Test Commands
+
+### 3.1 Building the Solution & Projects
+
+```powershell
+# Build entire solution (Debug / Release)
+dotnet build Gym.NET.sln -c Debug
+dotnet build Gym.NET.sln -c Release
+
+# Build specific subprojects
+dotnet build src/Gym/Gym.csproj -c Release
+dotnet build src/Gym.Environments/Gym.Environments.csproj -c Release
+dotnet build src/Gym.Rendering.Avalonia/Gym.Rendering.Avalonia.csproj -c Release
+dotnet build src/Gym.Rendering.WinForm/Gym.Rendering.WinForm.csproj -c Release
+```
+
+### 3.2 Running Automated Tests
+
+Tests are located in `tests/Gym.Tests/` using MSTest.
+
+```powershell
+# Run full test suite
+dotnet test tests/Gym.Tests/Gym.Tests.csproj
+
+# Run tests targeting a specific framework
+dotnet test tests/Gym.Tests/Gym.Tests.csproj -f net6.0-windows
+
+# Run a specific test class
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~CartpoleEnvironment"
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~BoxTest"
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~LunarLanderEnvironment"
+
+# Run a single individual test method
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~CartpoleEnvironment.Run_NullEnv"
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~BoxTest.TestBoxBoundedTest"
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~LunarLanderEnvironment.Run_Discrete_NullEnv"
+dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~LunarLanderEnvironment.Run_TwoInstances_Continuous_AvaloniaEnv"
+```
+
+### 3.3 Submodule Management
+
+```powershell
+# Initialize and synchronize Gymnasium SOT submodule
+git submodule update --init --recursive
+```

GEMINI.md

@@ -0,0 +1 @@
+CLAUDE.md

PRD.md

@@ -0,0 +1,100 @@
+# Gym.NET: Product Requirements Document (PRD)
+
+## 1. Executive Summary & Vision
+
+**Gym.NET** is a high-performance, native C# (.NET 8/10) port of OpenAI Gym / Farama Gymnasium designed for reinforcement learning algorithmic development, benchmarking, and quantitative financial microstructure simulations. Operating as part of the SciSharp STACK ecosystem, it provides a standardized, strongly-typed environment suite with `NumSharp` as the underlying multidimensional array/tensor engine.
+
+The goal of this project is to achieve complete architectural, behavioral, and mathematical parity with **Farama Gymnasium** (`refs/Gymnasium`), replacing legacy OpenAI Gym patterns with modern lifecycle contracts, comprehensive observation/action spaces, extensible wrapper hierarchies, and vectorized execution engines.
+
+---
+
+## 2. Core Functional Requirements (FR)
+
+### FR-01: Modernized `Reset` Contract
+- **Contract**: `(NDArray Observation, Dict Information) Reset(int? seed = null, Dict options = null)`.
+- **Behavior**:
+  - Reseeds environment PRNG (`np.random.RandomState(seed)`) when `seed` is provided.
+  - Accepts domain-specific options (`Dict options`) for custom initial states.
+  - Returns initial observation tensor accompanied by diagnostic information metadata.
+
+### FR-02: Modernized 5-Tuple `Step` Contract
+- **Contract**: `StepResult Step(object action)` supporting 5-tuple deconstruction:
+  ```csharp
+  var (observation, reward, terminated, truncated, info) = env.Step(action);
+  ```
+- **Behavior**:
+  - `terminated` (`bool`): Signals MDP terminal condition (e.g. agent succeeded or failed).
+  - `truncated` (`bool`): Signals out-of-bounds termination or time limit expiration (e.g. `TimeLimit` wrapper reached max steps).
+  - Deprecates legacy `Done` flag to ensure proper Generalized Advantage Estimation ($\text{GAE}$) bootstrapping in downstream RL engines like `PPO.Core`.
+
+### FR-03: Complete Observation & Action Spaces Suite
+- **`Box`**: Continuous multi-dimensional bounded intervals with vectorized Gaussian, exponential, and uniform sampling.
+- **`Discrete`**: Categorical integer space `{start, ..., start + n - 1}` with action masking support.
+- **`MultiDiscrete`**: Vector of discrete categorical dimensions, each with independent bounds.
+- **`MultiBinary`**: Multi-dimensional binary arrays with values in $\{0, 1\}$.
+- **`TupleSpace`**: Cartesian product of heterogeneous subspaces.
+- **`DictSpace`**: Key-value mapped composite subspaces.
+- **`TextSpace`**: Bounded/variable-length character string space.
+- **`SequenceSpace`**: Variable-length sequences of subspace elements.
+- **`GraphSpace`**: Structured graph spaces containing node, edge, and link features.
+- **`OneOfSpace`**: Exclusive union of alternative subspaces.
+
+### FR-04: Standard Wrapper Architecture
+- **Base Contracts**: `Wrapper`, `ObservationWrapper`, `ActionWrapper`, `RewardWrapper`.
+- **Standard Suite**:
+  - `TimeLimit`: Enforces maximum episode step bounds and marks `truncated = true`.
+  - `TransformObservation`: Functional transformation applied to observation tensors.
+  - `TransformReward`: Functional scaling/clipping applied to rewards.
+  - `ClipAction`: Clips continuous actions to action space bounds.
+  - `RescaleAction`: Maps continuous actions affine-transformed to custom ranges (e.g. $[-1, 1]$).
+  - `RecordEpisodeStatistics`: Collects episode return, length, and execution time in `info["episode"]`.
+  - `Autoreset`: Automatically invokes `Reset()` when `terminated or truncated` is encountered in `Step()`.
+  - `OrderEnforcing`: Enforces that `Reset()` is invoked prior to `Step()`.
+
+### FR-05: Vectorized Environments
+- **`VectorEnv`**: Base vectorized environment abstraction.
+- **`SyncVectorEnv`**: Sequential batch execution across $N$ environment instances.
+- **`AsyncVectorEnv`**: Parallel batch execution across worker threads/tasks.
+- **Autoreset Semantics**: Automatically captures `final_observation` in `info` when sub-environments terminate while continuing seamless rollout batching.
+
+### FR-06: Classical Control & Physics Environments
+- **`CartPole-v1`**: Discrete classic control balancing cart and pole via Euler kinematics.
+- **`Pendulum-v1`**: Continuous torque control pendulum swing-up.
+- **`MountainCar-v0`** & **`MountainCarContinuous-v0`**: Underpowered car mountain ascent.
+- **`Acrobot-v1`**: Two-link double pendulum.
+- **`LunarLander-v3`**: Discrete and Continuous 2D lunar lander physics simulation (via `Aether.Physics2D`).
+- **`BipedalWalker-v3`**: 4-joint bipedal locomotion robot.
+
+### FR-07: Headless & Decoupled Rendering Pipeline
+- Environment constructor parameter: `string render_mode = null` (`"human"`, `"rgb_array"`, `null`).
+- Rendering decoupled from core physics/math via `IEnvViewer` and `IEnvironmentViewerFactoryDelegate`.
+- Implementations:
+  - `NullEnvViewer`: High-speed headless simulation.
+  - `AvaloniaEnvViewer`: Cross-platform hardware-accelerated GUI (`Gym.Rendering.Avalonia`).
+  - `WinFormEnvViewer`: Windows Forms GUI (`Gym.Rendering.WinForm`).
+
+---
+
+## 3. Non-Functional Requirements & Engineering Standards
+
+### 3.1 SOLID Principles
+- **Single Responsibility (SRP)**: Segregate observation calculation, physics integration, reward calculation, and viewer rendering into focused classes.
+- **Open/Closed (OCP)**: Extend environment capabilities via `Wrapper` composition rather than modifying concrete environment classes.
+- **Liskov Substitution (LSP)**: All concrete environments and wrappers must satisfy `IEnv` and generic `IEnv<TObs, TAct>` contracts without surprising side effects.
+- **Interface Segregation (ISP)**: Focused interfaces (`IEnv`, `ISpace`, `IWrapper`, `IVectorEnv`, `IEnvViewer`).
+- **Dependency Inversion (DIP)**: Environments depend upon abstract viewers via `IEnvironmentViewerFactoryDelegate`, enabling headless testing.
+
+### 3.2 Object Calisthenics Rules
+1. **One level of indentation per method**: Extract nested loops/conditionals into private descriptive methods.
+2. **Never use the `else` keyword**: Guard clauses, early returns, and polymorphic strategy dispatch.
+3. **Wrap domain primitives**: Wrap scalars and raw arrays in strongly typed Value Objects (`Observation`, `Action`, `Reward`, `EpisodeStats`).
+4. **First-class collections**: Classes containing collections must encapsulate collection behavior without extraneous properties.
+5. **One dot per line**: Demeter compliance across all submodules.
+6. **No abbreviations**: Use explicit identifiers (`observation`, `terminated`, `truncated`, `actionSpace`).
+7. **Keep entities small**: Target classes $\le 100$ lines, methods $\le 15$ lines.
+8. **No bare getters/setters**: Expose domain behavior instead of mutable data structures (*Tell, Don't Ask*).
+
+### 3.3 Test-Driven Development (TDD)
+- Comprehensive test coverage with MSTest / FluentAssertions.
+- Golden comparison tests validating against deterministic Python Gymnasium trajectories and bounds.
+- Tests serve as immutable behavioral contracts.

ROADMAP.md

@@ -0,0 +1,65 @@
+# Gym.NET: Live Milestone Roadmap & Deliverables Matrix
+
+This document tracks the live milestone progress, implementation status, and deliverables matrix for **Gym.NET**, migrating from legacy OpenAI Gym to 100% **Farama Gymnasium** (`refs/Gymnasium`) parity.
+
+---
+
+## 1. High-Level Milestone Overview
+
+| Milestone | Focus Area | Status | Target Frameworks | Verification Gate |
+| :--- | :--- | :---: | :--- | :--- |
+| **M0** | .NET 8/10 Modernization & Security | **COMPLETED** | .NET 8.0, .NET 10.0 | 15/15 Automated Tests Passing |
+| **M1** | Core Lifecycle & Spaces Suite | **PLANNED** | .NET 8.0, .NET 10.0 | Golden Space Sampling & Bounds Tests |
+| **M2** | Wrapper Pipeline & Vector Environments | **PLANNED** | .NET 8.0, .NET 10.0 | Wrapper Truncation & Autoreset Tests |
+| **M3** | Classical Control & Physics Environments | **PLANNED** | .NET 8.0, .NET 10.0 | SOT Golden Seed Trajectory Comparisons |
+| **M4** | Live Documentation Hub & Agent Ontology | **IN PROGRESS** | Markdown / JSON | PRD, Architecture Specs, Ontology Graph |
+
+---
+
+## 2. Deliverables Matrix
+
+### Milestone 0: .NET 8/10 Modernization & Security (Completed)
+- [x] Multi-target projects to `net8.0` and `net10.0` (with `net8.0-windows;net10.0-windows` for UI).
+- [x] Upgrade `SixLabors.ImageSharp` to `2.1.13` resolving high/moderate CVE security advisories.
+- [x] Upgrade `SixLabors.ImageSharp.Drawing` to stable `1.0.0` and `SixLabors.Fonts` to `1.0.1`.
+- [x] Upgrade `Avalonia` & `Avalonia.Desktop` to `0.10.22`.
+- [x] Upgrade test framework to `MSTest 3.8.2` and `Microsoft.NET.Test.Sdk 17.14.1`.
+- [x] Fix 0D scalar shape bounds and sampling logic in `Box.cs`.
+- [x] Fix Avalonia application lifetime multi-instance reuse in `StaticAvaloniaApp.cs`.
+- [x] Guard `WinFormEnvViewer.cs` against headless modal dialog crashes.
+
+### Milestone 1: Core Lifecycle & Spaces Suite
+- [ ] Implement modern `(NDArray Obs, Dict Info) Reset(int? seed = null, Dict options = null)`.
+- [ ] Implement modern 5-tuple `StepResult Step(object action)` with `(Obs, Reward, Terminated, Truncated, Info)` and tuple deconstruction.
+- [ ] Implement `MultiDiscrete` space with independent dimension bounds.
+- [ ] Implement `MultiBinary` space with multi-dimensional binary arrays.
+- [ ] Implement `TupleSpace` for Cartesian products of heterogeneous subspaces.
+- [ ] Implement `DictSpace` for named composite key-value subspaces.
+- [ ] Implement `TextSpace`, `SequenceSpace`, `GraphSpace`, `OneOfSpace`.
+- [ ] Complete TDD test suite for all spaces verifying sampling, masking, bounds, and containment.
+
+### Milestone 2: Wrapper Pipeline & Vector Environments
+- [ ] Implement `Wrapper`, `ObservationWrapper`, `ActionWrapper`, `RewardWrapper` base abstractions.
+- [ ] Implement `TimeLimit` wrapper managing truncation limits.
+- [ ] Implement `TransformObservation` and `TransformReward` functional transformation wrappers.
+- [ ] Implement `ClipAction` and `RescaleAction` action space adapters.
+- [ ] Implement `RecordEpisodeStatistics` monitoring return and episode length.
+- [ ] Implement `Autoreset` and `OrderEnforcing` wrappers.
+- [ ] Modernize `VectorEnv`, `SyncVectorEnv`, `AsyncVectorEnv` with batched stepping and `final_observation` tracking.
+
+### Milestone 3: Classical Control & Physics Environments
+- [ ] Implement `CartPole-v1` with Gymnasium Euler kinematics and termination boundaries.
+- [ ] Implement `Pendulum-v1` with continuous torque physics and trigonometry observation vectors.
+- [ ] Implement `MountainCar-v0` (discrete) and `MountainCarContinuous-v0` (continuous).
+- [ ] Implement `Acrobot-v1` two-link double pendulum.
+- [ ] Modernize `LunarLander-v3` with discrete and continuous physics simulation via `Aether.Physics2D`.
+- [ ] Implement `BipedalWalker-v3` 4-joint locomotion.
+- [ ] Author automated Golden SOT test suites comparing seeded rollout trajectories against Python Gymnasium.
+
+### Milestone 4: Live Documentation Hub & Agent Ontology
+- [x] Author `PRD.md` capturing functional, architectural, and quality requirements.
+- [x] Author `ROADMAP.md` tracking milestone deliverables.
+- [ ] Author `docs/architecture/` specs (Core Lifecycle, Spaces, Wrappers, Vector Environments, Decoupled Rendering).
+- [ ] Author `docs/architecture/ontology.json` and Mermaid dependency graph for autonomous guide agents.
+- [ ] Author `docs/sot/` mapping and golden trajectory baselines.
+- [ ] Author `docs/guides/` for development, testing, and custom environment authoring.