chore: publish GridForge API docs and fix lean package dependency

Author: mrdav30

.github/workflows/coverage.yml

@@ -9,27 +9,37 @@ on:
     branches:
       - main
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
+permissions: {}
 
 concurrency:
   group: coverage-pages
   cancel-in-progress: true
 
 jobs:
   coverage:
+    permissions:
+      contents: read
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.head_sha == github.sha
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 1
+          persist-credentials: false
 
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: 8.0.x
+          dotnet-version: |
+            8.0.x
+            10.0.x
 
       - name: Cache NuGet packages
         uses: actions/cache@v5
@@ -42,8 +52,22 @@ jobs:
       - name: Restore dependencies
         run: dotnet restore GridForge.slnx --property:Configuration=Release
 
+      - name: Build solution
+        run: dotnet build GridForge.slnx --configuration Release --no-restore
+
       - name: Run tests with coverage
-        run: dotnet test tests/GridForge.Tests/GridForge.Tests.csproj --configuration Release --no-restore --collect:"XPlat Code Coverage" --settings tests/GridForge.Tests/coverlet.runsettings --results-directory artifacts/coverage
+        run: dotnet test tests/GridForge.Tests/GridForge.Tests.csproj --configuration Release --no-build --collect:"XPlat Code Coverage" --settings tests/GridForge.Tests/coverlet.runsettings --results-directory artifacts/coverage
+
+      - name: Restore local tools
+        run: dotnet tool restore
+
+      - name: Build API documentation
+        run: |
+          test -f src/GridForge/bin/Release/net8.0/GridForge.dll
+          test -f src/GridForge/bin/Release/net8.0/GridForge.xml
+          dotnet tool run docfx docs/api/docfx.json
+          test -f docs/api/obj/_site/index.html
+          test -f docs/api/obj/_site/api/GridForge.html
 
       - name: Install ReportGenerator
         run: dotnet tool install --global dotnet-reportgenerator-globaltool
@@ -62,15 +86,46 @@ jobs:
       - name: Add coverage summary to job
         run: cat artifacts/coverage-report/SummaryGithub.md >> "$GITHUB_STEP_SUMMARY"
 
+      - name: Enforce full coverage
+        shell: pwsh
+        run: |
+          $summary = Get-Content -Raw artifacts/coverage-report/Summary.json | ConvertFrom-Json
+          $coverage = $summary.summary
+          $uncoveredLines = $coverage.coverablelines - $coverage.coveredlines
+          $uncoveredBranches = $coverage.totalbranches - $coverage.coveredbranches
+          $uncoveredMethods = $coverage.totalmethods - $coverage.coveredmethods
+          if ($uncoveredLines -ne 0 -or $uncoveredBranches -ne 0 -or $uncoveredMethods -ne 0) {
+            throw "Coverage gate failed: $uncoveredLines uncovered line(s), $uncoveredBranches uncovered branch(es), $uncoveredMethods uncovered method(s)"
+          }
+
+      - name: Assemble Pages site
+        run: |
+          mkdir -p artifacts/pages/coverage
+          cp -a docs/api/obj/_site/. artifacts/pages/
+          cp -a artifacts/coverage-report/. artifacts/pages/coverage/
+          test -f artifacts/pages/index.html
+          test -f artifacts/pages/api/GridForge.html
+          test -f artifacts/pages/coverage/Summary.json
+          test -f artifacts/pages/coverage/badge_branchcoverage.svg
+
       - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
+        if: always()
+        uses: actions/upload-artifact@v7
         with:
           name: coverage-report
           path: artifacts/coverage-report
 
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: artifacts/pages
+
   deploy:
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
     needs: coverage
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     runs-on: ubuntu-latest
     environment:
       name: github-pages
@@ -80,17 +135,6 @@ jobs:
       - name: Configure Pages
         uses: actions/configure-pages@v6
 
-      - name: Download coverage artifact
-        uses: actions/download-artifact@v8
-        with:
-          name: coverage-report
-          path: artifacts/coverage-report
-
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v5
-        with:
-          path: artifacts/coverage-report
-
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5

.github/workflows/sync-wiki.yml

@@ -60,6 +60,12 @@ jobs:
 
           cd "$wiki_dir"
 
+          current_main_sha="$(git ls-remote "https://x-access-token:${WIKI_TOKEN}@github.com/${REPOSITORY}.git" refs/heads/main | cut -f1)"
+          if [[ "$SYNC_SHA" != "$current_main_sha" ]]; then
+            echo "Skipping stale wiki sync for ${SYNC_SHA}; main is ${current_main_sha}."
+            exit 0
+          fi
+
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 

AGENTS.md

@@ -15,7 +15,7 @@ The core design goal is to make grid-backed spatial systems scalable without
 forcing every consumer to reinvent ownership, snapping, neighbor resolution,
 coverage queries, or occupant indexing.
 
-Current priorities:
+Priorities:
 
 1. Preserve deterministic behavior across supported target frameworks.
 2. Keep runtime APIs anchored to explicit `GridWorld` ownership.
@@ -51,12 +51,12 @@ Read these in order before making non-trivial changes:
    pooling, tracing, scanning, registration, or other performance-sensitive
    behavior.
 
-When sibling repositories are available, also check their AGENTS/README files
-when a change touches shared stack assumptions:
+For coordinated stack changes, also check the guidance in the affected
+repositories:
 
-- `../FixedMathSharp`
-- `../SwiftCollections`
-- `../GridForge-Unity`
+- [FixedMathSharp](https://github.com/mrdav30/FixedMathSharp)
+- [SwiftCollections](https://github.com/mrdav30/SwiftCollections)
+- [GridForge-Unity](https://github.com/mrdav30/GridForge-Unity)
 
 ## Source Of Truth
 
@@ -70,6 +70,8 @@ workflow changes:
 - [`docs/wiki`](docs/wiki), especially pages covering world ownership, tracing,
   scan cells, blockers, occupants, partitions, determinism, testing, and build
   workflow.
+- [`docs/api`](docs/api) for the DocFX landing page, navigation, and API build
+  configuration.
 - [`AGENTS.md`](AGENTS.md)
 - [`src/GridForge/GridForge.csproj`](src/GridForge/GridForge.csproj)
 - [`tests/GridForge.Tests`](tests/GridForge.Tests)
@@ -98,8 +100,9 @@ rewrite.
 | [`src/GridForge/Utility`](src/GridForge/Utility)               | `GridTracer` and `GridForgeLogger`                                                | Tracing changes can affect many systems.                |
 | [`tests/GridForge.Tests`](tests/GridForge.Tests)               | xUnit v3 test project                                                             | Mirrors subsystem boundaries.                           |
 | [`tests/GridForge.Benchmarks`](tests/GridForge.Benchmarks)     | BenchmarkDotNet project                                                           | Covers allocation and throughput-sensitive scenarios.   |
-| [`docs/wiki`](docs/wiki)                                       | Developer-facing usage and architecture documentation                             | Keep current with public API and workflow changes.      |
-| [`.assets/scripts`](.assets/scripts)                           | Versioned build and release packaging helpers                                     | Used for release archive generation.                    |
+| [`docs/wiki`](docs/wiki)                                       | Developer-facing usage and architecture documentation                             | Keep aligned with public API and workflow changes.      |
+| [`docs/api`](docs/api)                                         | DocFX landing page, navigation, and API build configuration                       | Generated output stays under `docs/api/obj`.            |
+| [`.assets/scripts`](.assets/scripts)                           | PowerShell release packaging helpers                                              | Requires `GitVersion.Tool` for versioned archives.      |
 | [`.github/workflows`](.github/workflows)                       | CI, coverage, wiki sync, release, and publish automation                          | Keep workflow names in sync across triggers.            |
 
 Ignore generated output when reviewing or editing unless the task is explicitly
@@ -127,13 +130,16 @@ about build artifacts:
 - XML documentation: generated for the library project
 - Package generation: `GeneratePackageOnBuild` is enabled
 - Configurations: `Debug`, `Release`, `ReleaseLean`
+- Local prerequisites: the SDK selected by [`global.json`](global.json) and the
+  runtimes targeted by tests and benchmarks
 
 Package variants:
 
 - `Release` builds the standard `GridForge` package with `MemoryPack`,
   `FixedMathSharp`, and `SwiftCollections`.
 - `ReleaseLean` builds `GridForge.Lean` with `GRIDFORGE_DISABLE_MEMORYPACK`,
-  `FixedMathSharp.Lean`, and `SwiftCollections.Lean`.
+  `FixedMathSharp.Lean`, `SwiftCollections.Lean`, and the annotation-only
+  `Chronicler.MemoryPackShim` dependency.
 
 Versioning:
 
@@ -253,8 +259,8 @@ Rules:
 Match the surrounding file style instead of imposing a new one.
 
 - Add explicit `using` directives. `ImplicitUsings` is disabled.
-- The library project has nullable enabled; tests and benchmarks currently have
-  nullable disabled. Follow the local project context.
+- The library project enables nullable analysis; tests and benchmarks disable
+  it. Follow the project being edited.
 - `.editorconfig` disables implicit `new(...)`; prefer explicit construction.
 - Public API surface should have XML documentation.
 - Preserve existing `#region` organization in files that already use it.
@@ -276,8 +282,8 @@ dotnet test GridForge.slnx --configuration Debug --no-build
 CI validates both `Release` and `ReleaseLean` on Ubuntu and Windows:
 
 ```bash
-dotnet test GridForge.slnx --configuration Release --no-build
-dotnet test GridForge.slnx --configuration ReleaseLean --no-build
+dotnet test GridForge.slnx --configuration Release
+dotnet test GridForge.slnx --configuration ReleaseLean
 ```
 
 Run benchmarks when changing pooling, tracing, scan cells, occupant
@@ -362,9 +368,11 @@ GitHub wiki publishing.
 - `.github/workflows/publish-nuget.yml` validates release tag version, builds
   both package variants, checks for exactly four package artifacts, uploads the
   package artifact, and publishes `.nupkg` files to NuGet.
-- `.github/workflows/coverage.yml` and `.github/workflows/sync-wiki.yml` depend
-  on the `build-and-test` workflow name. If the build workflow name changes,
-  update those triggers and README badges together.
+- `.github/workflows/coverage.yml` builds the DocFX site and publishes coverage
+  beneath `/coverage` in the same GitHub Pages artifact.
+- `.github/workflows/sync-wiki.yml` publishes `docs/wiki` to the GitHub Wiki.
+  Both workflows depend on the `build-and-test` workflow name; update their
+  triggers and README badges if that name changes.
 
 ## Pitfalls To Avoid
 

README.md

@@ -3,7 +3,7 @@
 ![GridForge Icon](https://raw.githubusercontent.com/mrdav30/GridForge/main/icon.png)
 
 [![Build](https://github.com/mrdav30/GridForge/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/mrdav30/GridForge/actions/workflows/build-and-test.yml)
-[![Coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fmrdav30.github.io%2FGridForge%2FSummary.json&query=%24.summary.linecoverage&suffix=%25&label=coverage&color=brightgreen)](https://mrdav30.github.io/GridForge/)
+[![Branch Coverage](https://mrdav30.github.io/GridForge/coverage/badge_branchcoverage.svg)](https://mrdav30.github.io/GridForge/coverage/)
 [![NuGet](https://img.shields.io/nuget/v/GridForge.svg)](https://www.nuget.org/packages/GridForge)
 [![NuGet Downloads](https://img.shields.io/nuget/dt/GridForge.svg)](https://www.nuget.org/packages/GridForge)
 [![License](https://img.shields.io/github/license/mrdav30/GridForge.svg)](https://github.com/mrdav30/GridForge/blob/main/LICENSE)
@@ -212,11 +212,16 @@ identity remains host-owned through `IVoxelOccupant.GlobalId`.
 
 ## Documentation
 
-For breaking upgrades, start with the [Migration Guide](docs/MIGRATION.md).
-
-Start with the wiki:
+For breaking upgrades, start with the
+[Migration Guide](https://github.com/mrdav30/GridForge/blob/main/docs/MIGRATION.md).
 
+- [Documentation site](https://mrdav30.github.io/GridForge/)
+- [API reference](https://mrdav30.github.io/GridForge/api/GridForge.html)
 - [Wiki Home](https://github.com/mrdav30/GridForge/wiki/Home)
+- [Coverage report](https://mrdav30.github.io/GridForge/coverage/)
+
+The wiki includes:
+
 - [Getting Started](https://github.com/mrdav30/GridForge/wiki/Getting-Started)
 - [Core Concepts](https://github.com/mrdav30/GridForge/wiki/Core-Concepts)
 - [Sparse Grid Storage](https://github.com/mrdav30/GridForge/wiki/Sparse-Grid-Storage)
@@ -230,6 +235,9 @@ The source for those pages lives in [`docs/wiki`](docs/wiki).
 
 ## Local Validation
 
+Install the SDK selected by `global.json` and the runtimes targeted by the test
+and benchmark projects before running the repository commands.
+
 ```bash
 dotnet restore GridForge.slnx
 dotnet build GridForge.slnx --configuration Debug

docs/api/docfx.json

@@ -0,0 +1,24 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": ["src/GridForge/bin/Release/net8.0/GridForge.dll"],
+          "src": "../.."
+        }
+      ],
+      "dest": "obj/api"
+    }
+  ],
+  "build": {
+    "content": [
+      { "files": ["index.md", "toc.yml"] },
+      { "files": ["**/*.yml"], "src": "obj/api", "dest": "api" }
+    ],
+    "output": "obj/_site",
+    "template": ["default", "modern"],
+    "globalMetadata": {
+      "_appName": "GridForge API"
+    }
+  }
+}

docs/api/index.md

@@ -0,0 +1,9 @@
+# GridForge Documentation
+
+GridForge provides deterministic rectangular and hex-prism voxel grids for
+spatial partitioning, simulation, games, and tooling.
+
+- [Browse the API reference](xref:GridForge)
+- [Read the GridForge wiki](https://github.com/mrdav30/GridForge/wiki)
+- [Read the migration guide](https://github.com/mrdav30/GridForge/blob/main/docs/MIGRATION.md)
+- [View the coverage report](https://mrdav30.github.io/GridForge/coverage/)

docs/api/toc.yml

@@ -0,0 +1,12 @@
+items:
+  - name: Home
+    href: index.md
+  - name: API Reference
+    href: obj/api/
+    homepage: obj/api/GridForge.yml
+  - name: Wiki
+    href: https://github.com/mrdav30/GridForge/wiki
+  - name: Migration Guide
+    href: https://github.com/mrdav30/GridForge/blob/main/docs/MIGRATION.md
+  - name: Coverage
+    href: https://mrdav30.github.io/GridForge/coverage/