feat: fall back to a bundled docs snapshot when the live copy is unreachable

The listing needs the GitHub API, whose anonymous 60/hr budget the app already
spends on package version checks — an install with many packages can exhaust it
before the viewer is ever opened, so the docs page showed an error rather than
documentation. Page content was already safe, coming from raw.githubusercontent,
which is a CDN and not part of that budget.

Embeds the docs tree at build time and consults it last, after the network and
any cached copy, so the live version stays authoritative and pages added after a
release still appear. The snapshot backs the listing as well as page content,
otherwise a rate-limited cold start would still show an empty viewer.

Adds 17 files / ~191 KB to the assembly. The glob excludes the VitePress site
build and node_modules, whose bundled READMEs are several times the size of the
documentation itself.

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

Author: mohnjiles

StabilityMatrix.Core/Models/Documentation/BundledDocumentation.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+
+namespace StabilityMatrix.Core.Models.Documentation;
+
+/// <summary>
+/// The copy of the docs tree embedded in the app at build time. Read only when the live copy
+/// is unreachable — the network copy stays authoritative so pages added after a release still
+/// appear — but it guarantees the viewer is never empty, including on a first run that is
+/// offline or has exhausted the anonymous GitHub API budget.
+/// </summary>
+public static class BundledDocumentation
+{
+    private const string ResourcePrefix = "BundledDocs/";
+
+    private static readonly Lazy<IReadOnlyDictionary<string, string>> ResourcesByPath = new(BuildIndex);
+
+    /// <summary>
+    /// Docs-relative paths present in the bundle, e.g. <c>getting-started/overview.md</c>.
+    /// Empty if the build produced no snapshot.
+    /// </summary>
+    public static IReadOnlyList<string> Paths => ResourcesByPath.Value.Keys.ToList();
+
+    /// <summary>
+    /// Reads a bundled page, or null when the path is not part of the snapshot.
+    /// </summary>
+    public static string? TryReadPage(string docsRelativePath)
+    {
+        if (!ResourcesByPath.Value.TryGetValue(docsRelativePath, out var resourceName))
+            return null;
+
+        using var stream = typeof(BundledDocumentation).Assembly.GetManifestResourceStream(resourceName);
+        if (stream is null)
+            return null;
+
+        using var reader = new StreamReader(stream);
+        return reader.ReadToEnd();
+    }
+
+    private static IReadOnlyDictionary<string, string> BuildIndex()
+    {
+        var assembly = typeof(BundledDocumentation).Assembly;
+
+        return assembly
+            .GetManifestResourceNames()
+            .Where(name => name.StartsWith(ResourcePrefix, StringComparison.Ordinal))
+            .ToDictionary(
+                name => name[ResourcePrefix.Length..],
+                name => name,
+                StringComparer.OrdinalIgnoreCase
+            );
+    }
+}

StabilityMatrix.Core/Services/DocumentationService.cs

@@ -67,6 +67,17 @@ public async Task<IReadOnlyList<DocumentationSection>> GetSectionsAsync(
             {
                 logger.LogWarning(e, "Failed to fetch docs tree, attempting to use cached copy");
                 paths = await ReadCachedPathsAsync(cacheFile, cancellationToken).ConfigureAwait(false);
+
+                if (paths is null && BundledDocumentation.Paths is { Count: > 0 } bundledPaths)
+                {
+                    // The listing needs the GitHub API, whose anonymous budget the app also
+                    // spends on package version checks — so an install with many packages can
+                    // exhaust it before the viewer is ever opened. Falling back to the snapshot
+                    // keeps the nav usable; page content still comes from the network below.
+                    logger.LogInformation("Falling back to the bundled documentation listing");
+                    paths = bundledPaths.ToList();
+                }
+
                 if (paths is null)
                     throw;
             }
@@ -127,6 +138,12 @@ public async Task<string> GetPageMarkdownAsync(
             if (cacheFile.Exists)
                 return await cacheFile.ReadAllTextAsync(cancellationToken).ConfigureAwait(false);
 
+            if (BundledDocumentation.TryReadPage(docsRelativePath) is { } bundled)
+            {
+                logger.LogInformation("Serving {Path} from the bundled documentation", docsRelativePath);
+                return bundled;
+            }
+
             throw;
         }
     }

StabilityMatrix.Core/StabilityMatrix.Core.csproj

@@ -86,4 +86,15 @@
     <ItemGroup>
       <Folder Include="Api\PromptGen\Generated\" />
     </ItemGroup>
+
+    <!--
+      Snapshot of the docs tree, used by DocumentationService when the live copy is
+      unreachable. Excludes the VitePress site build and its dependencies, whose bundled
+      READMEs are several times the size of the documentation itself.
+    -->
+    <ItemGroup>
+      <EmbeddedResource Include="..\docs\**\*.md" Exclude="..\docs\node_modules\**;..\docs\.vitepress\**">
+        <LogicalName>BundledDocs/$([System.String]::Copy('%(RecursiveDir)').Replace('\','/'))%(Filename)%(Extension)</LogicalName>
+      </EmbeddedResource>
+    </ItemGroup>
 </Project>

StabilityMatrix.Tests/Core/BundledDocumentationTests.cs

@@ -0,0 +1,53 @@
+using StabilityMatrix.Core.Models.Documentation;
+
+namespace StabilityMatrix.Tests.Core;
+
+[TestClass]
+public class BundledDocumentationTests
+{
+    /// <summary>
+    /// A broken embed glob or LogicalName still compiles and just yields an empty bundle,
+    /// which would silently remove the offline fallback.
+    /// </summary>
+    [TestMethod]
+    public void Paths_ContainsDocsTree()
+    {
+        var paths = BundledDocumentation.Paths;
+
+        Assert.IsTrue(paths.Count > 0, "No docs were embedded — check the EmbeddedResource glob.");
+        CollectionAssert.Contains(paths.ToList(), "README.md");
+        Assert.IsTrue(
+            paths.Any(p => p.StartsWith("getting-started/", StringComparison.Ordinal)),
+            "Nested docs should keep forward-slash relative paths, got: " + string.Join(", ", paths.Take(5))
+        );
+    }
+
+    /// <summary>
+    /// The VitePress site build pulls in dependency READMEs several times the size of the
+    /// docs themselves; they must not ride along into the shipped assembly.
+    /// </summary>
+    [TestMethod]
+    public void Paths_ExcludesNodeModulesAndSiteBuild()
+    {
+        foreach (var path in BundledDocumentation.Paths)
+        {
+            Assert.IsFalse(path.Contains("node_modules", StringComparison.OrdinalIgnoreCase), path);
+            Assert.IsFalse(path.Contains(".vitepress", StringComparison.OrdinalIgnoreCase), path);
+        }
+    }
+
+    [TestMethod]
+    public void TryReadPage_ReturnsContentForBundledPage()
+    {
+        var markdown = BundledDocumentation.TryReadPage("README.md");
+
+        Assert.IsNotNull(markdown);
+        Assert.IsTrue(markdown.Length > 0);
+    }
+
+    [TestMethod]
+    public void TryReadPage_ReturnsNullForUnknownPage()
+    {
+        Assert.IsNull(BundledDocumentation.TryReadPage("nope/not-a-real-page.md"));
+    }
+}

StabilityMatrix.Tests/Core/DocumentationServiceFallbackTests.cs

@@ -0,0 +1,71 @@
+using System.Net;
+using Microsoft.Extensions.Logging.Abstractions;
+using NSubstitute;
+using NSubstitute.ExceptionExtensions;
+using Octokit;
+using StabilityMatrix.Core.Services;
+
+namespace StabilityMatrix.Tests.Core;
+
+/// <summary>
+/// Covers the offline chain: with the network failing and no cache, both the listing and page
+/// content must still come back from the bundled snapshot rather than surfacing an error.
+/// </summary>
+[TestClass]
+public class DocumentationServiceFallbackTests
+{
+    private sealed class FailingHandler : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken
+        ) => throw new HttpRequestException("offline");
+    }
+
+    private static DocumentationService CreateRateLimitedService()
+    {
+        var gitHub = Substitute.For<IGitHubClient>();
+        gitHub
+            .Git.Tree.GetRecursive(Arg.Any<string>(), Arg.Any<string>(), Arg.Any<string>())
+            .Throws(new ApiException("API rate limit exceeded", HttpStatusCode.Forbidden));
+
+        var factory = Substitute.For<IHttpClientFactory>();
+        factory.CreateClient(Arg.Any<string>()).Returns(_ => new HttpClient(new FailingHandler()));
+
+        return new DocumentationService(NullLogger<DocumentationService>.Instance, gitHub, factory);
+    }
+
+    [TestMethod]
+    public async Task GetSectionsAsync_FallsBackToBundle_WhenApiRateLimited()
+    {
+        var service = CreateRateLimitedService();
+
+        var sections = await service.GetSectionsAsync(forceRefresh: true);
+
+        Assert.IsTrue(sections.Count > 0, "Expected the bundled listing to populate the nav tree.");
+        Assert.IsTrue(
+            sections.SelectMany(s => s.Pages).Any(p => p.Path == "README.md"),
+            "Bundled listing should include the docs landing page."
+        );
+    }
+
+    [TestMethod]
+    public async Task GetPageMarkdownAsync_FallsBackToBundle_WhenOffline()
+    {
+        var service = CreateRateLimitedService();
+
+        var markdown = await service.GetPageMarkdownAsync("README.md", forceRefresh: true);
+
+        Assert.IsFalse(string.IsNullOrWhiteSpace(markdown));
+    }
+
+    [TestMethod]
+    public async Task GetPageMarkdownAsync_StillThrows_ForPageNotInBundle()
+    {
+        var service = CreateRateLimitedService();
+
+        await Assert.ThrowsExceptionAsync<HttpRequestException>(() =>
+            service.GetPageMarkdownAsync("nope/not-a-real-page.md", forceRefresh: true)
+        );
+    }
+}