Introduce doc publishing via MkDocs, add custom CSS & assets, and refactor GitHub workflows

- Added `.github/workflows/docs.yml` for deploying MkDocs-based docs to GitHub Pages.
- Introduced `docs/assets/styles.css` with minimal theme overrides.
- Added new assets: `agenix-logo.svg`, `agenix-favicon.svg` under `docs/assets/logos`.
- Updated `README.md` with improved formatting and consistent line breaks.
- Added extensive documentation structure, including new pages and navigation.
- Refactor license headers across multiple files for consistency.

Author: ereticul

.editorconfig

@@ -152,4 +152,7 @@ csharp_prefer_static_local_functions = true:suggestion
 csharp_style_prefer_switch_expression = true:suggestion
 
 # Enable file header template
-file_header_template = unset
+# To auto-apply to existing files, run: dotnet format --severity warn
+# IDEs (Rider/VS) will insert this header automatically for new C# files.
+dotnet_diagnostic.IDE0073.severity = warning
+file_header_template = #region License\n// Copyright (c) 2025 Agenix\n//\n// SPDX-License-Identifier: Apache-2.0\n//\n// Licensed under the Apache License, Version 2.0 (the "License");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an "AS IS" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n#endregion

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Docs
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install MkDocs and plugins
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload built site (PRs only)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site
+
+  deploy:
+    # Deploy only on direct pushes to main or develop
+    if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop') }}
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install MkDocs and plugins
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site

Agenix.PlaywrightGrid.Domain.Tests/Agenix.PlaywrightGrid.Domain.Tests.csproj

@@ -4,6 +4,6 @@
     <RootNamespace>Agenix.PlaywrightGrid.Domain.Tests</RootNamespace>
   </PropertyGroup>
   <ItemGroup>
-    <ProjectReference Include="../Agenix.PlaywrightGrid.Domain/Agenix.PlaywrightGrid.Domain.csproj" />
+    <ProjectReference Include="../Agenix.PlaywrightGrid.Domain/Agenix.PlaywrightGrid.Domain.csproj"/>
   </ItemGroup>
 </Project>

Agenix.PlaywrightGrid.Domain.Tests/LabelKeyTests.cs

@@ -1,5 +1,21 @@
-using Agenix.PlaywrightGrid.Domain;
 using NUnit.Framework;
+#region License
+// Copyright (c) 2025 Agenix
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#endregion
 
 namespace Agenix.PlaywrightGrid.Domain.Tests;
 

Agenix.PlaywrightGrid.Domain.Tests/LabelMatcherTests.cs

@@ -1,7 +1,22 @@
+#region License
+// Copyright (c) 2025 Agenix
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#endregion
+
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using Agenix.PlaywrightGrid.Domain;
 using NUnit.Framework;
 
 namespace Agenix.PlaywrightGrid.Domain.Tests;
@@ -11,7 +26,11 @@ public class LabelMatcherTests
     private static LabelKey L(string s)
     {
         var opts = new LabelKeyParsingOptions { EnforceBrowserSecond = false };
-        if (!LabelKey.TryParse(s, out var lk, opts)) throw new ArgumentException($"Invalid label: {s}");
+        if (!LabelKey.TryParse(s, out var lk, opts))
+        {
+            throw new ArgumentException($"Invalid label: {s}");
+        }
+
         return lk!;
     }
 
@@ -32,7 +51,9 @@ public void Trailing_Fallback_Drops_To_MinSegments_Default_2()
     {
         var requested = L("AppA:Chromium:UAT:EU");
         var available = new[] { L("AppA:Chromium"), L("AppA:Chromium:UAT") };
-        var matcher = new LabelMatcher(new LabelMatchingOptions { TrailingFallbackEnabled = true, PrefixExpansionEnabled = false });
+        var matcher =
+            new LabelMatcher(
+                new LabelMatchingOptions { TrailingFallbackEnabled = true, PrefixExpansionEnabled = false });
 
         var match = matcher.TryMatch(requested, available);
         // exact missing; fallback from 4->3 matches 3-segment entry
@@ -45,7 +66,12 @@ public void Trailing_Fallback_Respects_MinSegmentsForFallback()
     {
         var requested = L("AppA:Chromium:UAT");
         var available = new[] { L("AppA:Chromium") };
-        var matcher = new LabelMatcher(new LabelMatchingOptions { TrailingFallbackEnabled = true, MinSegmentsForFallback = 3, PrefixExpansionEnabled = false });
+        var matcher = new LabelMatcher(new LabelMatchingOptions
+        {
+            TrailingFallbackEnabled = true,
+            MinSegmentsForFallback = 3,
+            PrefixExpansionEnabled = false
+        });
 
         var match = matcher.TryMatch(requested, available);
         Assert.That(match, Is.Null, "Should not fallback below 3 segments");
@@ -56,7 +82,9 @@ public void Prefix_Expansion_Picks_Shortest_More_Specific_Then_Lexicographical()
     {
         var requested = L("AppB:Chromium");
         var available = new[] { L("AppB:Chromium:UAT:x"), L("AppB:Chromium:UAT:y"), L("AppB:Chromium:UAT:zz") };
-        var matcher = new LabelMatcher(new LabelMatchingOptions { PrefixExpansionEnabled = true, TrailingFallbackEnabled = false });
+        var matcher =
+            new LabelMatcher(
+                new LabelMatchingOptions { PrefixExpansionEnabled = true, TrailingFallbackEnabled = false });
 
         var match = matcher.TryMatch(requested, available);
         Assert.That(match, Is.Not.Null);
@@ -69,7 +97,12 @@ public void Wildcards_Disabled_Do_Not_Match_Asterisk_Segments()
     {
         var requested = L("AppA:*:UAT");
         var available = new[] { L("AppA:Firefox:UAT") };
-        var matcher = new LabelMatcher(new LabelMatchingOptions { WildcardsEnabled = false, PrefixExpansionEnabled = true, TrailingFallbackEnabled = true });
+        var matcher = new LabelMatcher(new LabelMatchingOptions
+        {
+            WildcardsEnabled = false,
+            PrefixExpansionEnabled = true,
+            TrailingFallbackEnabled = true
+        });
 
         var match = matcher.TryMatch(requested, available);
         Assert.That(match, Is.Null);
@@ -80,7 +113,12 @@ public void Wildcards_Enabled_Match_Any_Segment_In_Exact_And_Prefix()
     {
         var requested = L("AppA:*:UAT");
         var available = new[] { L("AppA:Firefox:UAT"), L("AppA:Chromium:UAT:EU") };
-        var matcher = new LabelMatcher(new LabelMatchingOptions { WildcardsEnabled = true, TrailingFallbackEnabled = false, PrefixExpansionEnabled = true });
+        var matcher = new LabelMatcher(new LabelMatchingOptions
+        {
+            WildcardsEnabled = true,
+            TrailingFallbackEnabled = false,
+            PrefixExpansionEnabled = true
+        });
 
         var match = matcher.TryMatch(requested, available);
         // Exact should win (3 segments) before prefix expansion to 4

Agenix.PlaywrightGrid.Domain/ILabelMatcher.cs

@@ -1,16 +1,32 @@
-using System.Collections.Generic;
+#region License
+// Copyright (c) 2025 Agenix
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#endregion
 
 namespace Agenix.PlaywrightGrid.Domain;
 
 /// <summary>
-/// Central label matching strategy service.
-/// Implements ordered resolution: exact → trailing fallback → prefix expansion → optional wildcards.
+///     Central label matching strategy service.
+///     Implements ordered resolution: exact → trailing fallback → prefix expansion → optional wildcards.
 /// </summary>
 public interface ILabelMatcher
 {
     /// <summary>
-    /// Attempts to find the best matching available label for the requested <see cref="LabelKey"/>.
-    /// Returns null when no match is found according to the configured <see cref="LabelMatchingOptions"/>.
+    ///     Attempts to find the best matching available label for the requested <see cref="LabelKey" />.
+    ///     Returns null when no match is found according to the configured <see cref="LabelMatchingOptions" />.
     /// </summary>
     LabelKey? TryMatch(LabelKey requested, IEnumerable<LabelKey> available);
 }