fix(docs-tests): stabilize landing-page and dist-rebuild assertions

.github/workflows/dotnet.yml

@@ -328,10 +328,17 @@ jobs:
   # ref.sh` → `docfx metadata`). The built dist tree is uploaded as a
   # workflow artifact so the sharded route-check job below can skip
   # the npm + docfx + build wall-clock (~5 min) entirely. The test
-  # fixture's [OneTimeSetUp] checks for docs/.vitepress/dist/index.html
-  # and skips the `npm ci && npm run build` bootstrap when the file is
-  # present, so a shard that downloads the artifact into the right
-  # path bypasses the bootstrap altogether.
+  # fixture's [OneTimeSetUp] contract has two modes:
+  #   - Consumer mode (ROUTE_SHARD_TOTAL > 1, i.e. the sharded matrix
+  #     leg below): checks for docs/.vitepress/dist/index.html and
+  #     skips the vitepress build bootstrap when the sentinel is
+  #     present. A shard that downloads this job's artifact into the
+  #     right path bypasses the bootstrap altogether.
+  #   - Producer mode (ROUTE_SHARD_TOTAL <= 1, i.e. local + unsharded
+  #     CI): always rebuilds by invoking `vitepress build` directly
+  #     (bypassing the `prebuild` docfx hook so the shard runners'
+  #     missing docfx is a non-issue) so a warm-cache developer run
+  #     still walks a dist tree generated from the CURRENT source.
   # ------------------------------------------------------------------
   docs-prepare:
     name: docs-prepare

build/MTConnect.NET-DocsGen/EnvVarInventory.cs

@@ -45,6 +45,15 @@ public static class EnvVarInventory
     private static readonly string[] ExcludedDirectoryNames =
     {
         "bin", "obj", "node_modules", ".git", ".vitepress",
+        // ".claude" holds sibling git-worktree checkouts (see repo
+        // convention: .claude/worktrees/<slug>/) used by agent sessions
+        // for isolated branch work. Left unexcluded, a repo-root-relative
+        // walk descends into every nested worktree and mixes in
+        // env-var reads from whatever branch each one happens to have
+        // checked out — producing a false "out of sync" verdict against
+        // docs/reference/environment-variables.md that has nothing to
+        // do with the actual source tree on the current branch.
+        ".claude",
     };
 
     // Match `MTCONNECT_FOO`, `DOTNET_BAR`, plus any other ALL-CAPS env-var

docs/.docfx/docfx.json

@@ -4,50 +4,50 @@
       "src": [
         {
           "files": [
-            "libraries/MTConnect.NET-Common/bin/Debug/net8.0/MTConnect.NET-Common.dll",
-            "libraries/MTConnect.NET-DeviceFinder/bin/Debug/net8.0/MTConnect.NET-DeviceFinder.dll",
-            "libraries/MTConnect.NET-HTTP/bin/Debug/net8.0/MTConnect.NET-HTTP.dll",
-            "libraries/MTConnect.NET-JSON/bin/Debug/net8.0/MTConnect.NET-JSON.dll",
-            "libraries/MTConnect.NET-JSON-cppagent/bin/Debug/net8.0/MTConnect.NET-JSON-cppagent.dll",
-            "libraries/MTConnect.NET-MQTT/bin/Debug/net8.0/MTConnect.NET-MQTT.dll",
-            "libraries/MTConnect.NET-Protobuf/bin/Debug/net8.0/MTConnect.NET-Protobuf.dll",
-            "libraries/MTConnect.NET-Services/bin/Debug/net8.0/MTConnect.NET-Services.dll",
-            "libraries/MTConnect.NET-SHDR/bin/Debug/net8.0/MTConnect.NET-SHDR.dll",
-            "libraries/MTConnect.NET-SysML/bin/Debug/net8.0/MTConnect.NET-SysML.dll",
-            "libraries/MTConnect.NET-TLS/bin/Debug/net8.0/MTConnect.NET-TLS.dll",
-            "libraries/MTConnect.NET-XML/bin/Debug/net8.0/MTConnect.NET-XML.dll",
-            "libraries/MTConnect.NET/bin/Debug/net8.0/MTConnect.NET.dll",
-            "agent/MTConnect.NET-Agent/bin/Debug/net8.0/MTConnect.NET-Agent.dll",
-            "agent/MTConnect.NET-Applications-Agents/bin/Debug/net8.0/MTConnect.NET-Applications-Agents.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-HttpServer/bin/Debug/net8.0/MTConnect.NET-AgentModule-HttpServer.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-HttpAdapter.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-MqttAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttAdapter.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-MqttBroker/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttBroker.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-MqttRelay/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay.dll",
-            "agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-ShdrAdapter.dll",
-            "agent/Processors/MTConnect.NET-AgentProcessor-Python/bin/Debug/net8.0/MTConnect.NET-AgentProcessor-Python.dll",
-            "adapter/MTConnect.NET-Adapter/bin/Debug/net8.0/MTConnect.NET-Adapter.dll",
-            "adapter/MTConnect.NET-Applications-Adapter/bin/Debug/net8.0/MTConnect.NET-Applications-Adapter.dll",
-            "adapter/Modules/MTConnect.NET-AdapterModule-MQTT/bin/Debug/net8.0/MTConnect.NET-AdapterModule-MQTT.dll",
-            "adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll",
-            "build/MTConnect.NET-SysML-Import/bin/Debug/net8.0/MTConnect.NET-SysML-Import.dll",
-            "build/MTConnect.NET.Builder/bin/Debug/net8.0/MTConnect.NET.Builder.dll",
-            "examples/MTConnect.NET-Agent-Embedded/bin/Debug/net8.0/MTConnect.NET-Agent-Embedded.dll",
-            "examples/MTConnect.NET-Client-HTTP/bin/Debug/net8.0/MTConnect.NET-Client-HTTP.dll",
-            "examples/MTConnect.NET-Client-MQTT/bin/Debug/net8.0/MTConnect.NET-Client-MQTT.dll",
-            "examples/MTConnect.NET-Client-SHDR/bin/Debug/net8.0/MTConnect.NET-Client-SHDR.dll",
-            "templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent/bin/Debug/net8.0/agent.dll",
-            "tests/Compliance/MTConnect-Compliance-Tests/bin/Debug/net8.0/MTConnect-Compliance-Tests.dll",
-            "tests/MTConnect.NET-AgentModule-MqttRelay-Tests/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay-Tests.dll",
-            "tests/MTConnect.NET-Common-Tests/bin/Debug/net8.0/MTConnect.NET-Common-Tests.dll",
-            "tests/MTConnect.NET-Docs-Tests/bin/Debug/net8.0/MTConnect.NET-Docs-Tests.dll",
-            "tests/MTConnect.NET-HTTP-Tests/bin/Debug/net8.0/MTConnect.NET-HTTP-Tests.dll",
-            "tests/MTConnect.NET-Integration-Tests/bin/Debug/net8.0/MTConnect.NET-Integration-Tests.dll",
-            "tests/MTConnect.NET-JSON-cppagent-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-cppagent-Tests.dll",
-            "tests/MTConnect.NET-JSON-Tests/bin/Debug/net8.0/MTConnect.NET-JSON-Tests.dll",
-            "tests/MTConnect.NET-SHDR-Tests/bin/Debug/net8.0/MTConnect.NET-SHDR-Tests.dll",
-            "tests/MTConnect.NET-Tests-Agents/bin/Debug/net8.0/MTConnect.NET-Tests-Agents.dll",
-            "tests/MTConnect.NET-XML-Tests/bin/Debug/net8.0/MTConnect.NET-XML-Tests.dll"
+            "libraries/MTConnect.NET-Common/MTConnect.NET-Common.csproj",
+            "libraries/MTConnect.NET-DeviceFinder/MTConnect.NET-DeviceFinder.csproj",
+            "libraries/MTConnect.NET-HTTP/MTConnect.NET-HTTP.csproj",
+            "libraries/MTConnect.NET-JSON/MTConnect.NET-JSON.csproj",
+            "libraries/MTConnect.NET-JSON-cppagent/MTConnect.NET-JSON-cppagent.csproj",
+            "libraries/MTConnect.NET-MQTT/MTConnect.NET-MQTT.csproj",
+            "libraries/MTConnect.NET-Protobuf/MTConnect.NET-Protobuf.csproj",
+            "libraries/MTConnect.NET-Services/MTConnect.NET-Services.csproj",
+            "libraries/MTConnect.NET-SHDR/MTConnect.NET-SHDR.csproj",
+            "libraries/MTConnect.NET-SysML/MTConnect.NET-SysML.csproj",
+            "libraries/MTConnect.NET-TLS/MTConnect.NET-TLS.csproj",
+            "libraries/MTConnect.NET-XML/MTConnect.NET-XML.csproj",
+            "libraries/MTConnect.NET/MTConnect.NET.csproj",
+            "agent/MTConnect.NET-Agent/MTConnect.NET-Agent.csproj",
+            "agent/MTConnect.NET-Applications-Agents/MTConnect.NET-Applications-Agents.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-HttpServer/MTConnect.NET-AgentModule-HttpServer.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/MTConnect.NET-AgentModule-HttpAdapter.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttAdapter/MTConnect.NET-AgentModule-MqttAdapter.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttBroker/MTConnect.NET-AgentModule-MqttBroker.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttRelay/MTConnect.NET-AgentModule-MqttRelay.csproj",
+            "agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/MTConnect.NET-AgentModule-ShdrAdapter.csproj",
+            "agent/Processors/MTConnect.NET-AgentProcessor-Python/MTConnect.NET-AgentProcessor-Python.csproj",
+            "adapter/MTConnect.NET-Adapter/MTConnect.NET-Adapter.csproj",
+            "adapter/MTConnect.NET-Applications-Adapter/MTConnect.NET-Applications-Adapter.csproj",
+            "adapter/Modules/MTConnect.NET-AdapterModule-MQTT/MTConnect.NET-AdapterModule-MQTT.csproj",
+            "adapter/Modules/MTConnect.NET-AdapterModule-SHDR/MTConnect.NET-AdapterModule-SHDR.csproj",
+            "build/MTConnect.NET-SysML-Import/MTConnect.NET-SysML-Import.csproj",
+            "build/MTConnect.NET.Builder/MTConnect.NET.Builder.csproj",
+            "examples/MTConnect.NET-Agent-Embedded/MTConnect.NET-Agent-Embedded.csproj",
+            "examples/MTConnect.NET-Client-HTTP/MTConnect.NET-Client-HTTP.csproj",
+            "examples/MTConnect.NET-Client-MQTT/MTConnect.NET-Client-MQTT.csproj",
+            "examples/MTConnect.NET-Client-SHDR/MTConnect.NET-Client-SHDR.csproj",
+            "templates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent/Agent.csproj",
+            "tests/Compliance/MTConnect-Compliance-Tests/MTConnect-Compliance-Tests.csproj",
+            "tests/MTConnect.NET-AgentModule-MqttRelay-Tests/MTConnect.NET-AgentModule-MqttRelay-Tests.csproj",
+            "tests/MTConnect.NET-Common-Tests/MTConnect.NET-Common-Tests.csproj",
+            "tests/MTConnect.NET-Docs-Tests/MTConnect.NET-Docs-Tests.csproj",
+            "tests/MTConnect.NET-HTTP-Tests/MTConnect.NET-HTTP-Tests.csproj",
+            "tests/MTConnect.NET-Integration-Tests/MTConnect.NET-Integration-Tests.csproj",
+            "tests/MTConnect.NET-JSON-cppagent-Tests/MTConnect.NET-JSON-cppagent-Tests.csproj",
+            "tests/MTConnect.NET-JSON-Tests/MTConnect.NET-JSON-Tests.csproj",
+            "tests/MTConnect.NET-SHDR-Tests/MTConnect.NET-SHDR-Tests.csproj",
+            "tests/MTConnect.NET-Tests-Agents/MTConnect.NET-Tests-Agents.csproj",
+            "tests/MTConnect.NET-XML-Tests/MTConnect.NET-XML-Tests.csproj"
           ],
           "src": "../.."
         }
@@ -57,7 +57,11 @@
       "namespaceLayout": "flattened",
       "memberLayout": "samePage",
       "includePrivateMembers": true,
-      "filter": "filter.yml"
+      "filter": "filter.yml",
+      "properties": {
+        "TargetFramework": "net8.0",
+        "Configuration": "Debug"
+      }
     }
   ]
 }

docs/development/docs-site.md

@@ -61,15 +61,15 @@ The classic symptom of a base mismatch is a deployed page that renders as raw HT
 
 ## End-to-end route check
 
-`tests/MTConnect.NET-Docs-Tests/RouteCheckTests.cs` is a Playwright e2e fixture that builds the docs site, spawns `vitepress preview` against the built `dist/` tree, walks every route the markdown source tree implies in a headless Chromium browser, and asserts no client-side 404s. CI runs it on the `ubuntu-latest` matrix leg of `.github/workflows/dotnet.yml` (the `windows-latest` leg filters `Category=E2E` out — hosted Windows runners do not carry Linux-image Docker, and the test fixture's `npm ci && npm run build` bootstrap is the easier target to keep Linux-only).
+`tests/MTConnect.NET-Docs-Tests/RouteCheckTests.cs` is a Playwright e2e fixture that builds the docs site, spawns `vitepress preview` against the built `dist/` tree, walks every route the markdown source tree implies in a headless Chromium browser, and asserts no client-side 404s. CI runs it on the `ubuntu-latest` matrix leg of `.github/workflows/dotnet.yml` (the `windows-latest` leg filters `Category=E2E` out — hosted Windows runners do not carry Linux-image Docker, and the test fixture's `npm ci` + direct `vitepress build` bootstrap is the easier target to keep Linux-only).
 
 Run locally from the repo root:
 
 ```
 dotnet test tests/MTConnect.NET-Docs-Tests --filter Category=E2E
 ```
 
-On the first run the fixture installs the chromium binary the Playwright .NET binding drives (~150 MB; cached on subsequent runs) and — if `docs/.vitepress/dist/` is missing — invokes `npm ci && npm run build` from `docs/` to produce a preview-able site. Subsequent runs reuse both, so a warm working tree completes in a couple of minutes; a cold checkout takes longer because the build artefact is rebuilt from scratch.
+On the first run the fixture installs the chromium binary the Playwright .NET binding drives (~150 MB; cached on subsequent runs) and, in producer mode (local + unsharded CI, i.e. `ROUTE_SHARD_TOTAL <= 1`), invokes `npm ci` when `docs/node_modules/` is missing and then always invokes `vitepress build` directly from `docs/` — bypassing the `package.json` `prebuild` hook (`docs/scripts/generate-api-ref.sh` → `docfx metadata`) that would otherwise clobber every touched project's `obj/project.assets.json` back to a Debug-only `net8.0` view and race any in-flight multi-TFM Release build. In consumer mode (sharded CI matrix with `ROUTE_SHARD_TOTAL > 1`), the shard downloads a `dist/` tree from the `docs-prepare` workflow artifact and honors the `docs/.vitepress/dist/index.html` sentinel, skipping the rebuild. Subsequent local runs reuse the cached `node_modules/` and Playwright chromium, so a warm producer-mode run completes in a couple of minutes; a cold checkout takes longer because the build artefact is rebuilt from scratch.
 
 Failure output names every route that surfaced as a 404 along with which of the two signals fired—the `.NotFound` element rendered by the VitePress default theme's NotFound component, or `document.title` starting with `404` (the static `404.html` emits `<title>404 | MTConnect.NET</title>`, so a prefix match catches it regardless of the trailing site-title suffix). Typical fixes:
 

tests/MTConnect.NET-Docs-Tests/DocsReferenceGenerationTests.cs

@@ -64,7 +64,10 @@ public void HttpApi_Page_Is_In_Sync_With_Source()
         }
     }
 
-    /// <summary>Pins the behaviour expressed by the test name: environment variables page is in sync with source.</summary>
+    /// <summary>Pins the behavior expressed by the test name: environment variables page is in sync with source.
+    /// Historically flaky as collateral damage from a prebuild-hook <c>obj/</c> race triggered elsewhere in the
+    /// same <c>dotnet test</c> invocation — see <see cref="RouteCheckTests.RunVitepressBuild"/>'s remarks on why
+    /// producer-mode OneTimeSetUp no longer shells out through `npm run build`'s `prebuild` hook.</summary>
     [Test]
     public void EnvironmentVariables_Page_Is_In_Sync_With_Source()
     {