Apply Gemini review: fix page-load CTS race + harden docs cache IO

- Replace pageCts synchronously before any await so rapid page selections
  can't leak a stale load that overwrites newer content
- Cache write failures after a successful fetch no longer fail the operation
  (nested try-catch, logged as warnings)
- Unreadable/corrupt cached tree listing now falls back to network instead
  of throwing
- Match Engine as IMarkdownEngine2 (the getter's actual type; upgraded
  wrappers don't implement IMarkdownEngine)
- Avoid Split('/') allocations in hot-ish path helpers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mohnjiles

StabilityMatrix.Avalonia/Controls/DocumentationMarkdownViewer.cs

@@ -64,8 +64,10 @@ protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs chang
 
     private void ApplyLinkCommand()
     {
-        // The engine (IMarkdownEngine) owns the HyperlinkCommand used for all rendered links.
-        if (Engine is IMarkdownEngine engine)
+        // The engine owns the HyperlinkCommand used for all rendered links. The Engine getter
+        // always returns an IMarkdownEngine2 (custom IMarkdownEngine values are upgraded to a
+        // wrapper that only implements IMarkdownEngine2), so match on that interface.
+        if (Engine is IMarkdownEngine2 engine)
         {
             engine.HyperlinkCommand = LinkCommand;
         }

StabilityMatrix.Avalonia/ViewModels/DocumentationViewModel.cs

@@ -173,11 +173,18 @@ partial void OnSelectedPageChanged(DocumentationPageNavItem? oldValue, Documenta
 
     private async Task LoadPageAsync(string docsRelativePath)
     {
-        // Cancel any in-flight page load
-        await (pageCts?.CancelAsync() ?? Task.CompletedTask);
-        pageCts?.Dispose();
-        pageCts = new CancellationTokenSource();
-        var ct = pageCts.Token;
+        // Replace the CTS before any await so rapid selections can't race on the old one,
+        // then cancel the superseded load.
+        var oldCts = pageCts;
+        var newCts = new CancellationTokenSource();
+        pageCts = newCts;
+        var ct = newCts.Token;
+
+        if (oldCts is not null)
+        {
+            await oldCts.CancelAsync();
+            oldCts.Dispose();
+        }
 
         IsPageLoading = true;
         ErrorMessage = null;

StabilityMatrix.Core/Services/DocumentationService.cs

@@ -52,7 +52,14 @@ public async Task<IReadOnlyList<DocumentationSection>> GetSectionsAsync(
             try
             {
                 paths = await FetchDocsPathsAsync(cancellationToken).ConfigureAwait(false);
-                await WriteCachedPathsAsync(cacheFile, paths, cancellationToken).ConfigureAwait(false);
+                try
+                {
+                    await WriteCachedPathsAsync(cacheFile, paths, cancellationToken).ConfigureAwait(false);
+                }
+                catch (Exception cacheEx) when (cacheEx is not OperationCanceledException)
+                {
+                    logger.LogWarning(cacheEx, "Failed to write docs tree to cache");
+                }
             }
             catch (DocumentationNotAvailableException)
             {
@@ -99,8 +106,16 @@ public async Task<string> GetPageMarkdownAsync(
             client.Timeout = TimeSpan.FromSeconds(30);
             var markdown = await client.GetStringAsync(url, cancellationToken).ConfigureAwait(false);
 
-            CacheDir.Create();
-            await cacheFile.WriteAllTextAsync(markdown, cancellationToken).ConfigureAwait(false);
+            try
+            {
+                CacheDir.Create();
+                await cacheFile.WriteAllTextAsync(markdown, cancellationToken).ConfigureAwait(false);
+            }
+            catch (Exception cacheEx) when (cacheEx is not OperationCanceledException)
+            {
+                logger.LogWarning(cacheEx, "Failed to write markdown to cache for {Path}", docsRelativePath);
+            }
+
             return markdown;
         }
         catch (Exception e) when (e is not OperationCanceledException)
@@ -162,7 +177,8 @@ private static bool IsDocPage(string docsRelativePath)
         if (docsRelativePath.StartsWith("images/", StringComparison.OrdinalIgnoreCase))
             return false;
 
-        var fileName = docsRelativePath.Split('/').Last();
+        var lastSlash = docsRelativePath.LastIndexOf('/');
+        var fileName = lastSlash < 0 ? docsRelativePath : docsRelativePath[(lastSlash + 1)..];
         if (fileName.Equals(".gitkeep", StringComparison.OrdinalIgnoreCase))
             return false;
 
@@ -191,7 +207,7 @@ internal static IReadOnlyList<DocumentationSection> BuildSections(IReadOnlyList<
             }
 
             var folder = path[..separatorIndex];
-            var fileName = path.Split('/').Last();
+            var fileName = path[(path.LastIndexOf('/') + 1)..];
 
             if (!sections.TryGetValue(folder, out var list))
             {
@@ -247,14 +263,22 @@ private static bool IsFresh(FilePath cacheFile) =>
 
     private static async Task<List<string>?> ReadCachedPathsAsync(FilePath cacheFile, CancellationToken ct)
     {
-        if (!cacheFile.Exists)
-            return null;
+        try
+        {
+            if (!cacheFile.Exists)
+                return null;
 
-        var text = await cacheFile.ReadAllTextAsync(ct).ConfigureAwait(false);
-        return text.Split('\n', StringSplitOptions.RemoveEmptyEntries)
-            .Select(line => line.Trim())
-            .Where(line => line.Length > 0)
-            .ToList();
+            var text = await cacheFile.ReadAllTextAsync(ct).ConfigureAwait(false);
+            return text.Split('\n', StringSplitOptions.RemoveEmptyEntries)
+                .Select(line => line.Trim())
+                .Where(line => line.Length > 0)
+                .ToList();
+        }
+        catch (Exception e) when (e is not OperationCanceledException)
+        {
+            // Unreadable/corrupt cache — treat as a miss so callers fall back to the network.
+            return null;
+        }
     }
 
     private static async Task WriteCachedPathsAsync(