Fix documentation paths, error codes, and script robustness

.github/workflows/scripts/build-docfx.sh

@@ -7,18 +7,27 @@ WORKTREE_ROOT="$ROOT/.docfx-worktrees"
 WORKTREES_TO_REMOVE=()
 
 cleanup() {
-  for worktree in "${WORKTREES_TO_REMOVE[@]:-}"; do
-    if [ -d "$worktree" ]; then
-      git worktree remove --force "$worktree" >/dev/null 2>&1 || true
-    fi
-  done
+  if [ ${#WORKTREES_TO_REMOVE[@]} -gt 0 ]; then
+    for worktree in "${WORKTREES_TO_REMOVE[@]}"; do
+      if [ -d "$worktree" ]; then
+        git worktree remove --force "$worktree" >/dev/null 2>&1 || true
+      fi
+    done
+  fi
   rm -rf "$ARTIFACT_DIR" "$WORKTREE_ROOT"
 }
 trap cleanup EXIT
 
 rm -rf "$ARTIFACT_DIR" "$WORKTREE_ROOT"
 mkdir -p "$ARTIFACT_DIR" "$WORKTREE_ROOT"
 
+# Verify docfx tool exists
+if [ ! -f "$ROOT/docfx" ]; then
+  echo "Error: docfx tool not found at $ROOT/docfx"
+  echo "Please run: dotnet tool install --tool-path . docfx"
+  exit 1
+fi
+
 ./docfx metadata docs/docfx.json
 ./docfx build docs/docfx.json
 mv docs/_site "$ARTIFACT_DIR/main"

docs/index.md

@@ -49,7 +49,7 @@ Humanizer turns numbers, dates, enums, quantities, and strings into human-friend
 
 ## Versioned Docs
 
-The published site always serves the latest stable release at the root path. Development snapshots live under `/main/`, and prior releases remain under `/v{major.minor}/`. See [`/versions.json`](/versions.json) to enumerate the available builds programmatically.
+The published site always serves the latest stable release at the root path. Development snapshots live under `/main/`, and prior releases remain under `/{version}/`. See [`/versions.json`](/versions.json) to enumerate the available builds programmatically.
 
 ## API Reference
 

docs/performance.md

@@ -14,6 +14,9 @@ Humanizer focuses on readability, but many applications call it in performance-s
 
 Humanizer already applies internal caching for culture-specific resources. Adding your own memoization rarely delivers additional wins and can easily serve the wrong culture if you ignore `CultureInfo`. If you discover a real hotspot that still needs memoization, key the cache with both the value **and** the culture (for example, `(value, CultureInfo.CurrentUICulture.Name)`) so French output is not reused for English callers.
 
+> [!NOTE]
+> If you implement custom caching for humanized output in multi-threaded scenarios, use a thread-safe collection such as `ConcurrentDictionary` to avoid race conditions and data corruption.
+
 ### Minimize culture switches
 
 Group similar operations to avoid thrashing `CultureInfo`:
@@ -31,6 +34,7 @@ try
     foreach (var item in items)
     {
         item.DisplayAge = item.Created.Humanize();
+        // ToQuantity expects a singular word and handles pluralization automatically
         item.DisplayCount = item.Count.ToQuantity("élément");
     }
 }

docs/testing.md

@@ -6,7 +6,7 @@ A reliable Humanizer integration includes automated tests that lock down localiz
 
 ### Pin cultures with `UseCulture`
 
-Create a reusable attribute that switches `CultureInfo.CurrentCulture` and `CultureInfo.CurrentUICulture` for the duration of a test. Humanizer ships a sample implementation inside the test project ([see `UseCultureAttribute.cs`](../src/Humanizer.Tests/UseCultureAttribute.cs)); you can copy the approach:
+Create a reusable attribute that switches `CultureInfo.CurrentCulture` and `CultureInfo.CurrentUICulture` for the duration of a test. Humanizer ships a sample implementation inside the test project (see [`UseCultureAttribute.cs` on GitHub](https://github.com/Humanizr/Humanizer/blob/main/src/Humanizer.Tests/UseCultureAttribute.cs)); you can copy the approach:
 
 ```csharp
 public sealed class UseCultureAttribute : BeforeAfterTestAttribute

docs/troubleshooting.md

@@ -16,7 +16,7 @@ Use this guide to diagnose common issues that arise when installing, configuring
 ## Restore failures with old SDKs
 
 **Symptoms**
-- `NU1004` or `NU3004` errors mentioning unrecognized locales during `dotnet restore`
+- `NU1004` errors mentioning unrecognized locales during `dotnet restore`
 
 **Resolution**
 - Upgrade to .NET SDK 9.0.200 or newer, or use Visual Studio/MSBuild builds that contain the locale parsing fix.
@@ -39,7 +39,7 @@ Use this guide to diagnose common issues that arise when installing, configuring
 
 **Resolution**
 - Some languages intentionally ship with partial feature support. Check whether ordinal or cardinal conversions exist for the target culture.
-- Consider contributing the missing implementation (see [Contributing](contributing.md)).
+- Consider contributing the missing implementation (see [Contributing](../.github/CONTRIBUTING.md)).
 - Provide a fallback by wrapping calls in `try/catch` and defaulting to English or a neutral culture.
 
 ## Configuration side effects