diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33615dc..41ce398 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,14 +4,33 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 ## [Unreleased]
 
+## [0.1.5-alpha] — 2026-08-22
+
+The `shelldocs build` output is now a real static site. Previously it copied `publish/wwwroot/` 1:1 — fine on paper, useless in practice for a Blazor Server scaffold, which produces no `index.html`, no client-side runtime, nothing a static host can serve at the root URL. Deploying the output to GH Pages / Cloudflare Pages / Netlify silently returned a blank shell. Now every URL the site knows about is prerendered at build time and the framework's static assets are merged on top.
+
+### Fixed
+
+- **`shelldocs build` produces a fully static site deployable to GH Pages / Cloudflare Pages / Netlify without a .NET host.** Previously the CLI ran `dotnet publish` and copied `wwwroot/` verbatim — which, for a Blazor Server scaffold (what `shelldocs init` produces by default), contains only static assets and no HTML entrypoint. Visiting the deployed root returned an empty page; deep links 404'd. New flow: publish → launch the published app on a loopback ephemeral port → walk `NavigationGraph.AllUrls` to enumerate every route (visible + hidden) plus `/` → `HttpClient.GetAsync` each URL → save the rendered HTML to `<output>/<url>/index.html`. Then merge `publish/wwwroot/` (`_content/`, `_framework/blazor.web.js`, `app.css`, `favicon.png`, tokens CSS) on top. Result is a directory any dumb file host can serve; every URL is a real HTML file with content in the response body. Server scaffold unchanged — the prerender happens entirely inside `shelldocs build`.
+- **`--base-href` now rewrites `<base href>` in every prerendered HTML file, not just the root `index.html`.** The pre-fix pass only touched one file, so subpath deploys (GH user-repo pages at `/repo/`) worked for the home page but broke every deep-linked doc route (assets 404'd because the deep-linked pages still had `<base href="/">`). New pass walks `<output>/**/*.html` and rewrites every occurrence.
+
+### Added
+
+- **`NavigationGraph.AllUrls`** — public enumeration of every indexed URL (visible + hidden). Needed by the new prerender walk so hidden pages still land in the static output (they route at runtime and would 404 on the static site otherwise). Trivial addition, no API break.
+- **`PrerenderRunner`** internal helper in `ShellDocs.CLI` — encapsulates the subprocess launch + readiness poll + URL walk + file save. Kept out of `BuildCommand` so the orchestration reads linearly. Guarantees subprocess cleanup on every exit path (finally + `ProcessExit` + `CancelKeyPress`).
+
+### Known limitations
+
+- **URL discovery is content-folder-based, not runtime-based.** `PrerenderRunner` walks URLs via `NavigationGraphBuilder.Build(contentRoot)` — same logic the running app uses — so file-based routes are complete. Custom routes registered outside `content/` (bespoke `@page` directives) won't be prerendered and will need to be added manually. Not a regression from `0.1.4-alpha` behavior (which prerendered nothing).
+- **Interactive server components at request time.** The prerendered HTML is a snapshot of the initial render; hydration on the client picks up from there via `<script src="_framework/blazor.web.js">`. Deep-linking to a page hits the static HTML; the theme toggle, search, tabs, code copy work via the shipped `shelldocs.js` on top. Full Blazor Server interactivity (SignalR-backed component state) doesn't survive the static build — but a docs site doesn't need it.
+
 ## [0.1.4-alpha] — 2026-08-22
 
-Second dogfood batch. `0.1.3-alpha` pinned the sidebar footer to a fixed slot but only under the desktop Sidebar variant — footer still floated mid-sidebar on TopNav / mobile drawer / short-tree cases. 
+`0.1.3-alpha` pinned the sidebar footer to a fixed slot but only under the desktop Sidebar variant — footer still floated mid-sidebar on TopNav, mobile drawer, and short-tree cases. This release covers that plus three primitive-DX improvements.
 
 ### Fixed
 
 - **Sidebar footer now pins to the bottom in every layout context.** The `0.1.3-alpha` fix only worked in the desktop Sidebar variant — the `flex: 1; min-height: 0` sizing that lets the nav fill its slot was scoped to `.docs-shell-sidebar .docs-sidebar-slot > nav` inside a `@media (min-width: 1024px)` block. On the TopNav variant, the mobile drawer, or any Sidebar site whose tree is shorter than the slot, the nav still collapsed to intrinsic content size and the footer (GitHub link + theme toggle) sat wherever the tree ended, mid-sidebar. Moved `flex: 1; min-height: 0` onto `.docs-sidebar` itself and made `.docs-sidebar-slot` `display: flex; flex-direction: column` in every context. Footer pins hard to the bottom regardless of variant / viewport / item count.
-- **`razor:preview` fences with an unknown outer tag now render a visible error in the frame instead of falling back to a plain code block silently.** Previously `SlotExtractor.TryBuildPreviewSlot` returned `null` when the fence's first tag didn't resolve to a registered component; the fence rendered as regular fenced code with only a build-log warning. Authors chasing "why isn't my icon rendering" would hunt for a nonexistent component bug. Now the same case emits a `PreviewSlot` with `ComponentType = null` and an `Error` message; `PreviewFrame` renders a red-tinted error panel in the render region naming the unknown tag and pointing at `o.RegisterComponent<T>()` / `o.RegisterComponentsFromAssembly<TMarker>()`. Build-log warning still emitted. `PreviewSlot.ComponentType` is now nullable — technically a source-breaking change for callers pattern-matching on it, though external consumers of that type are ~none in the alpha window. [SHELLDOCS_FIXES.md #4]
+- **`razor:preview` fences with an unknown outer tag now render a visible error in the frame instead of falling back to a plain code block silently.** Previously `SlotExtractor.TryBuildPreviewSlot` returned `null` when the fence's first tag didn't resolve to a registered component; the fence rendered as regular fenced code with only a build-log warning. Authors chasing "why isn't my icon rendering" would hunt for a nonexistent component bug. Now the same case emits a `PreviewSlot` with `ComponentType = null` and an `Error` message; `PreviewFrame` renders a red-tinted error panel in the render region naming the unknown tag and pointing at `o.RegisterComponent<T>()` / `o.RegisterComponentsFromAssembly<TMarker>()`. Build-log warning still emitted. `PreviewSlot.ComponentType` is now nullable — technically a source-breaking change for callers pattern-matching on it, though external consumers of that type are ~none in the alpha window.
 
 ### Added
 
@@ -20,18 +39,18 @@ Second dogfood batch. `0.1.3-alpha` pinned the sidebar footer to a fixed slot bu
   o.RegisterComponentsFromAssembly<Marker>("ShellIcons.Icons");
   ```
   instead of the lambda form. The `Func` overload stays for anything more complex.
-- **`shelldocs init` scaffolded `Program.cs` now surfaces the `LayoutVariant` knob.** Commented-out `// o.LayoutVariant = DocsLayoutVariant.Sidebar;` line right in the `AddShellDocs(...)` block, plus the `RegisterComponentsFromAssembly` hint. First-time consumers no longer have to grep `ShellDocs.Components/Layouts/DocsLayout.razor` to discover the sidebar-variant option exists. [SHELLDOCS_FIXES.md #3]
+- **`shelldocs init` scaffolded `Program.cs` now surfaces the `LayoutVariant` knob.** Commented-out `// o.LayoutVariant = DocsLayoutVariant.Sidebar;` line right in the `AddShellDocs(...)` block, plus the `RegisterComponentsFromAssembly` hint. First-time consumers no longer have to grep `ShellDocs.Components/Layouts/DocsLayout.razor` to discover the sidebar-variant option exists.
 
-### Not fixed this batch
+### Known limitations
 
-Three items from SHELLDOCS_FIXES.md deferred; they need spec-level work rather than a patch:
+Two items deferred to future releases; both need spec-level design rather than a patch:
 
-- **#1 / #2 — `shelldocs build` produces no `index.html`, and `init`/`build` render-mode mismatch.** The scaffolded project is Server-interactive but `build` prints "publish kind: static (Blazor WASM)" and copies the resulting `wwwroot/` — which for a Server-interactive project has no `index.html`, no `_framework/dotnet.js`, no runtime blob. Output is unusable as a static site (blocks GH Pages / Cloudflare / Netlify deploys). Two viable paths (server-side prerender walk of the nav graph, or scaffold WASM Standalone by default) — either is a substantial change to `BuildCommand` and/or `InitCommand`. Design work needs to happen before this lands. Consumers workaround: `dotnet run` locally, skip `shelldocs build`.
-- **#5 — Markdig mangles inline HTML wrappers between component slots in `razor:preview`.** Plain `<span style="color:…">` around a registered component tag inside a preview loses its parent-child relationship after Markdig's inline pass, because SlotExtractor lifts component tags before Markdig sees them. Documented workaround: use registered wrapper components with their own attribute props instead of raw inline HTML. Framework fix would need SlotExtractor to lift-and-preserve trivial wrappers (`<span>`, `<a>`, `<button>`) around component tags.
+- **`shelldocs build` produces no `index.html`, and `init`/`build` render-mode mismatch.** The scaffolded project is Server-interactive but `build` prints "publish kind: static (Blazor WASM)" and copies the resulting `wwwroot/` — which for a Server-interactive project has no `index.html`, no `_framework/dotnet.js`, no runtime blob. Output is unusable as a static site (blocks GH Pages / Cloudflare / Netlify deploys). Two viable paths (server-side prerender walk of the nav graph, or scaffold WASM Standalone by default) — either is a substantial change to `BuildCommand` and/or `InitCommand`. Consumers workaround: `dotnet run` locally, skip `shelldocs build`.
+- **Markdig mangles inline HTML wrappers between component slots in `razor:preview`.** Plain `<span style="color:…">` around a registered component tag inside a preview loses its parent-child relationship after Markdig's inline pass, because SlotExtractor lifts component tags before Markdig sees them. Workaround: use registered wrapper components with their own attribute props instead of raw inline HTML. Framework fix would need SlotExtractor to lift-and-preserve trivial wrappers (`<span>`, `<a>`, `<button>`) around component tags.
 
 ## [0.1.3-alpha] — 2026-08-12
 
-Dogfood-driven fixes. Surfaced while writing the per-primitive / per-command / authoring pages on shelldocs.dev (30+ new sidebar entries pushed the tree past viewport height for the first time). One user-visible bug, one visual polish, both landed against the sidebar chrome.
+One sidebar-chrome bug + a broader icon vocabulary for real-world consumer sites.
 
 ### Fixed
 
@@ -39,11 +58,7 @@ Dogfood-driven fixes. Surfaced while writing the per-primitive / per-command / a
 
 ### Added
 
-- **Broader `SidebarIcons` coverage.** Hand-curated icon map grew from ~20 entries to ~50. New titles covered: `Authoring`, `CLI` (+ `Cli` alias for auto-title-cased folder names), `Packages`, `Configuration`, `Project Structure`, `Quick Start`, `Frontmatter`, `Fenced Code`, `Razor Preview`, `Inline Component Tags`, `Navigation`, plus PascalCase and space-separated variants of every content primitive (`CardGrid`/`Card Grid`, `LinkCard`/`Link Card`, `Steps`, `FileTree`/`File Tree`, `TypeTable`/`Type Table`, `CodeGroup`, `PreviewFrame`/`Preview Frame`, `ComponentPreview`/`Component Preview`) and the four CLI command names (`shelldocs init`/`add`/`dev`/`build` + bare `Init`/`Add`/`Dev`/`Build`). Longer-term this is the argument for `ShellUI.Icons` ([SHELLUI_ICONS.md](docs/SHELLUI_ICONS.md)) — hand maps don't scale. Short-term this closes the visual gap where categories a mature consumer's site actually uses rendered without an icon while the framework's own vocabulary had one.
-
-### Docs
-
-- **`docs/SHELLUI_DOGFOOD_FIXES.md`** now tracked in git. Three entries logged from the shelldocs.dev writing session (the two fixes above, plus one still-open item: `TitleFromFolderName` doesn't uppercase acronyms — `cli/` → `Cli`, `api/` → `Api`. Worked around on the consumer via explicit `meta.json.title`; framework-level fix — either a built-in acronym set or a `ShellDocsOptions.KnownAcronyms` hook — still open).
+- **Broader `SidebarIcons` coverage.** Hand-curated icon map grew from ~20 entries to ~50. New titles covered: `Authoring`, `CLI` (+ `Cli` alias for auto-title-cased folder names), `Packages`, `Configuration`, `Project Structure`, `Quick Start`, `Frontmatter`, `Fenced Code`, `Razor Preview`, `Inline Component Tags`, `Navigation`, plus PascalCase and space-separated variants of every content primitive (`CardGrid`/`Card Grid`, `LinkCard`/`Link Card`, `Steps`, `FileTree`/`File Tree`, `TypeTable`/`Type Table`, `CodeGroup`, `PreviewFrame`/`Preview Frame`, `ComponentPreview`/`Component Preview`) and the four CLI command names (`shelldocs init`/`add`/`dev`/`build` + bare `Init`/`Add`/`Dev`/`Build`). Closes the visual gap where categories a mature consumer's site actually uses rendered without an icon while the framework's own vocabulary had one. Longer-term a first-class icon package will replace this hand map.
 
 ## [0.1.2-alpha] — 2026-07-28
 
diff --git a/Directory.Build.props b/Directory.Build.props
index c00b767..6aec0b0 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -18,7 +18,7 @@
 
   <!-- Package metadata (applies to any project with IsPackable=true) -->
   <PropertyGroup>
-    <Version>0.1.4-alpha</Version>
+    <Version>0.1.5-alpha</Version>
     <Authors>ShellUI</Authors>
     <Company>ShellUI</Company>
     <Copyright>Copyright © 2026 ShellUI</Copyright>
diff --git a/src/ShellDocs.CLI/Commands/BuildCommand.cs b/src/ShellDocs.CLI/Commands/BuildCommand.cs
index c1241d4..4c3d13f 100644
--- a/src/ShellDocs.CLI/Commands/BuildCommand.cs
+++ b/src/ShellDocs.CLI/Commands/BuildCommand.cs
@@ -1,17 +1,10 @@
 using System.Diagnostics;
 using System.Text.RegularExpressions;
+using ShellDocs.Core;
 using Spectre.Console;
 
 namespace ShellDocs.CLI.Commands;
 
-/* `shelldocs build` — `dotnet publish -c Release` then post-process the
-   output for static hosts (GH Pages / Cloudflare / S3). Detects the
-   published `wwwroot/` for Blazor WASM projects and copies it to --output;
-   for server projects, copies the whole publish directory instead.
-
-   Post-processing:
-   - --base-href rewrites <base href="/" /> in index.html (for GH Pages subpaths).
-   - --spa-fallback copies index.html to 404.html (GH Pages SPA-routing trick). */
 internal static class BuildCommand
 {
     public static int Run(string dir, string output, string? baseHref, bool spaFallback)
@@ -24,6 +17,14 @@ public static int Run(string dir, string output, string? baseHref, bool spaFallb
             return 1;
         }
 
+        var contentRoot = Path.Combine(root, "content");
+        if (!Directory.Exists(contentRoot))
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] no [yellow]content/[/] directory found under [yellow]{root}[/]");
+            AnsiConsole.MarkupLine("[dim]shelldocs build needs a docs project with content/ so it can enumerate URLs to prerender.[/]");
+            return 1;
+        }
+
         var outputAbs = Path.GetFullPath(Path.Combine(root, output));
         var publishStage = Path.Combine(root, "obj", "shelldocs-publish");
 
@@ -33,32 +34,71 @@ public static int Run(string dir, string output, string? baseHref, bool spaFallb
         if (spaFallback)           AnsiConsole.MarkupLine("[dim]spa fallback:[/] [cyan]index.html → 404.html[/]");
         AnsiConsole.WriteLine();
 
-        // 1. dotnet publish to a scratch dir
         var publishExit = RunPublish(csproj, publishStage);
         if (publishExit != 0) return publishExit;
 
-        // 2. Locate static payload: wwwroot for WASM, whole dir for Server
-        var wwwroot = Path.Combine(publishStage, "wwwroot");
-        var source = Directory.Exists(wwwroot) ? wwwroot : publishStage;
-        var kind = Directory.Exists(wwwroot) ? "static (Blazor WASM)" : "server (needs a .NET host)";
-        AnsiConsole.MarkupLine($"[dim]publish kind:[/] [cyan]{kind}[/]");
+        // Belt-and-suspenders: mirror source content/ into publish. Consumer
+        // csprojs using `<Content Update="content/...">` don't actually copy
+        // .md files (Update is the wrong verb; see InitCommand notes), which
+        // would leave the running app with an empty NavigationGraph and every
+        // prerendered page as "Page not found."
+        var publishContent = Path.Combine(publishStage, "content");
+        if (!Directory.Exists(publishContent))
+        {
+            AnsiConsole.MarkupLine("[dim]content:[/] publish output has no content/ — mirroring from source");
+            CopyDirectoryOverwriting(contentRoot, publishContent);
+        }
+
+        // Home ("/") is served by Home.razor and isn't part of NavigationGraph.
+        var urls = new List<string> { "/" };
+        try
+        {
+            var graph = NavigationGraphBuilder.Build(contentRoot);
+            urls.AddRange(graph.AllUrls);
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] failed to read content/ nav graph: {ex.Message}");
+            return 1;
+        }
+        AnsiConsole.MarkupLine($"[dim]prerender:[/] discovered [cyan]{urls.Count}[/] URL(s) from content/");
 
-        // 3. Copy to output (clean first so stale files never linger)
         if (Directory.Exists(outputAbs)) Directory.Delete(outputAbs, recursive: true);
-        CopyDirectory(source, outputAbs);
+        Directory.CreateDirectory(outputAbs);
 
-        // 4. Post-process
-        var indexHtml = Path.Combine(outputAbs, "index.html");
-        if (baseHref is not null && File.Exists(indexHtml))
+        var result = PrerenderRunner.Run(publishStage, csproj, urls, outputAbs);
+        if (!result.Success)
+        {
+            AnsiConsole.MarkupLine("[red]error:[/] prerender did not complete cleanly. Output may be incomplete.");
+            return 1;
+        }
+
+        var wwwroot = Path.Combine(publishStage, "wwwroot");
+        if (Directory.Exists(wwwroot))
         {
-            RewriteBaseHref(indexHtml, baseHref);
+            CopyDirectoryMerging(wwwroot, outputAbs);
+            AnsiConsole.MarkupLine($"[dim]assets:[/] copied [cyan]wwwroot/[/] into output");
         }
-        if (spaFallback && File.Exists(indexHtml))
+        else
         {
-            File.Copy(indexHtml, Path.Combine(outputAbs, "404.html"), overwrite: true);
+            AnsiConsole.MarkupLine("[yellow]warn:[/] publish/wwwroot/ not found — output may be missing framework assets");
+        }
+
+        if (baseHref is not null)
+        {
+            var patched = RewriteBaseHrefInAllHtml(outputAbs, baseHref);
+            AnsiConsole.MarkupLine($"[dim]base-href:[/] rewrote [cyan]{patched}[/] HTML file(s)");
+        }
+        if (spaFallback)
+        {
+            var rootIndex = Path.Combine(outputAbs, "index.html");
+            if (File.Exists(rootIndex))
+            {
+                File.Copy(rootIndex, Path.Combine(outputAbs, "404.html"), overwrite: true);
+                AnsiConsole.MarkupLine("[dim]spa fallback:[/] wrote 404.html");
+            }
         }
 
-        // Cleanup scratch
         try { Directory.Delete(publishStage, recursive: true); } catch { }
 
         AnsiConsole.WriteLine();
@@ -68,10 +108,8 @@ public static int Run(string dir, string output, string? baseHref, bool spaFallb
 
     private static int RunPublish(string csproj, string publishDir)
     {
-        var psi = new ProcessStartInfo("dotnet")
-        {
-            UseShellExecute = false,
-        };
+        AnsiConsole.MarkupLine($"[dim]$[/] [cyan]dotnet publish -c Release -o {publishDir}[/]");
+        var psi = new ProcessStartInfo("dotnet") { UseShellExecute = false };
         psi.ArgumentList.Add("publish");
         psi.ArgumentList.Add(csproj);
         psi.ArgumentList.Add("-c");
@@ -89,8 +127,22 @@ private static int RunPublish(string csproj, string publishDir)
         return proc.ExitCode;
     }
 
-    // Recursive directory copy — no built-in in .NET stdlib.
-    internal static void CopyDirectory(string source, string dest)
+    // Never overwrites — protects prerendered HTML sitting in the output tree.
+    internal static void CopyDirectoryMerging(string source, string dest)
+    {
+        Directory.CreateDirectory(dest);
+        foreach (var file in Directory.GetFiles(source))
+        {
+            var target = Path.Combine(dest, Path.GetFileName(file));
+            if (!File.Exists(target)) File.Copy(file, target);
+        }
+        foreach (var subdir in Directory.GetDirectories(source))
+        {
+            CopyDirectoryMerging(subdir, Path.Combine(dest, Path.GetFileName(subdir)));
+        }
+    }
+
+    internal static void CopyDirectoryOverwriting(string source, string dest)
     {
         Directory.CreateDirectory(dest);
         foreach (var file in Directory.GetFiles(source))
@@ -99,22 +151,29 @@ internal static void CopyDirectory(string source, string dest)
         }
         foreach (var subdir in Directory.GetDirectories(source))
         {
-            CopyDirectory(subdir, Path.Combine(dest, Path.GetFileName(subdir)));
+            CopyDirectoryOverwriting(subdir, Path.Combine(dest, Path.GetFileName(subdir)));
         }
     }
 
-    /* Rewrites <base href="..." /> in index.html. `baseHref` should include
-       leading + trailing slashes ("/repo-name/"). Handles single, double,
-       and no-quote variants. */
-    internal static void RewriteBaseHref(string indexHtml, string baseHref)
+    // `baseHref` must include leading + trailing slashes ("/repo-name/").
+    internal static int RewriteBaseHrefInAllHtml(string outputDir, string baseHref)
     {
-        var html = File.ReadAllText(indexHtml);
-        var patched = Regex.Replace(
-            html,
-            @"<base\s+href\s*=\s*(""[^""]*""|'[^']*'|[^\s>]+)\s*/?>",
-            $"<base href=\"{baseHref}\" />",
-            RegexOptions.IgnoreCase);
-        File.WriteAllText(indexHtml, patched);
+        var count = 0;
+        foreach (var html in Directory.EnumerateFiles(outputDir, "*.html", SearchOption.AllDirectories))
+        {
+            var original = File.ReadAllText(html);
+            var patched = Regex.Replace(
+                original,
+                @"<base\s+href\s*=\s*(""[^""]*""|'[^']*'|[^\s>]+)\s*/?>",
+                $"<base href=\"{baseHref}\" />",
+                RegexOptions.IgnoreCase);
+            if (patched != original)
+            {
+                File.WriteAllText(html, patched);
+                count++;
+            }
+        }
+        return count;
     }
 
     private static string? FindCsproj(string dir)
diff --git a/src/ShellDocs.CLI/Commands/InitCommand.cs b/src/ShellDocs.CLI/Commands/InitCommand.cs
index 3ef9e4e..bcfb0c1 100644
--- a/src/ShellDocs.CLI/Commands/InitCommand.cs
+++ b/src/ShellDocs.CLI/Commands/InitCommand.cs
@@ -258,14 +258,29 @@ private static void ScaffoldPackages(string csproj, List<string> changes)
         AddContentCopyIfMissing(csproj, changes);
     }
 
-    // Adds a Content Update item for content markdown/meta.json so
-    // `dotnet publish` copies the markdown corpus into the publish output.
-    // Without this, ContentRoot resolves fine under `dotnet run` (source dir)
-    // but the published site has no content to render.
+    // Split-rule .md/.json copy so both `dotnet run` and `dotnet publish`
+    // carry content. Two rules because the Web SDK auto-includes .json (need
+    // Update, not Include — Include triggers NETSDK1022) but not .md.
+    // Migrates the pre-0.1.5-alpha broken single-Update form on re-run.
     internal static void AddContentCopyIfMissing(string csproj, List<string> changes)
     {
         var xml = File.ReadAllText(csproj);
-        if (new Regex(@"<Content\s+Update=""content/", RegexOptions.IgnoreCase).IsMatch(xml))
+
+        var brokenSingleUpdate = new Regex(
+            @"<Content\s+Update=""content/\*\*/\*\.md;content/\*\*/meta\.json""\s+CopyToOutputDirectory=""PreserveNewest""\s*/>",
+            RegexOptions.IgnoreCase);
+        if (brokenSingleUpdate.IsMatch(xml))
+        {
+            var replacement =
+                @"<Content Include=""content/**/*.md"" CopyToOutputDirectory=""PreserveNewest"" CopyToPublishDirectory=""PreserveNewest"" />" +
+                Environment.NewLine +
+                @"    <Content Update=""content/**/meta.json"" CopyToOutputDirectory=""PreserveNewest"" CopyToPublishDirectory=""PreserveNewest"" />";
+            File.WriteAllText(csproj, brokenSingleUpdate.Replace(xml, replacement));
+            changes.Add($"migrated [cyan]content copy rules[/] in {Path.GetFileName(csproj)} (fixes empty publish/content/)");
+            return;
+        }
+
+        if (new Regex(@"<Content\s+Include=""content/\*\*/\*\.md""", RegexOptions.IgnoreCase).IsMatch(xml))
             return;
 
         var closing = xml.LastIndexOf("</Project>", StringComparison.OrdinalIgnoreCase);
@@ -273,11 +288,12 @@ internal static void AddContentCopyIfMissing(string csproj, List<string> changes
 
         var block =
             $"  <ItemGroup>{Environment.NewLine}" +
-            $"    <Content Update=\"content/**/*.md;content/**/meta.json\" CopyToOutputDirectory=\"PreserveNewest\" />{Environment.NewLine}" +
+            $"    <Content Include=\"content/**/*.md\" CopyToOutputDirectory=\"PreserveNewest\" CopyToPublishDirectory=\"PreserveNewest\" />{Environment.NewLine}" +
+            $"    <Content Update=\"content/**/meta.json\" CopyToOutputDirectory=\"PreserveNewest\" CopyToPublishDirectory=\"PreserveNewest\" />{Environment.NewLine}" +
             $"  </ItemGroup>{Environment.NewLine}{Environment.NewLine}";
 
         File.WriteAllText(csproj, xml.Insert(closing, block));
-        changes.Add($"added [cyan]content copy-to-output[/] to {Path.GetFileName(csproj)}");
+        changes.Add($"added [cyan]content copy rules[/] to {Path.GetFileName(csproj)}");
     }
 
     private static void ScaffoldContent(string root, List<string> changes)
diff --git a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
new file mode 100644
index 0000000..cd549f7
--- /dev/null
+++ b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
@@ -0,0 +1,163 @@
+using System.Diagnostics;
+using System.Text.RegularExpressions;
+using Spectre.Console;
+
+namespace ShellDocs.CLI.Commands;
+
+internal static class PrerenderRunner
+{
+    public record Result(bool Success, int Rendered, int Failed);
+
+    // Match Kestrel's startup line: "Now listening on: http://127.0.0.1:63593"
+    private static readonly Regex KestrelListening = new(
+        @"Now listening on:\s*(?<url>https?://\S+)", RegexOptions.Compiled);
+
+    public static Result Run(string publishDir, string csproj, IReadOnlyList<string> urls, string outputDir, TimeSpan? readyTimeout = null)
+    {
+        var assemblyName = InferAssemblyName(csproj) + ".dll";
+        var assemblyPath = Path.Combine(publishDir, assemblyName);
+        if (!File.Exists(assemblyPath))
+        {
+            AnsiConsole.MarkupLine($"[red]error:[/] published assembly not found at [yellow]{assemblyPath}[/]");
+            return new Result(false, 0, 0);
+        }
+
+        AnsiConsole.MarkupLine($"[dim]prerender:[/] launching [cyan]{assemblyName}[/]");
+
+        var psi = new ProcessStartInfo("dotnet")
+        {
+            WorkingDirectory = publishDir,
+            UseShellExecute = false,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            CreateNoWindow = true,
+        };
+        psi.ArgumentList.Add(assemblyPath);
+        // Port 0 → kernel picks a free port at Kestrel bind time (no TOCTOU
+        // gap between us checking and the child using). We learn the actual
+        // port by parsing Kestrel's "Now listening on:" startup line below.
+        psi.Environment["ASPNETCORE_URLS"] = "http://127.0.0.1:0";
+        psi.Environment["ASPNETCORE_ENVIRONMENT"] = "Production";
+        psi.Environment["DOTNET_USE_POLLING_FILE_WATCHER"] = "0";
+
+        Process? proc = null;
+        try
+        {
+            proc = Process.Start(psi);
+            if (proc is null)
+            {
+                AnsiConsole.MarkupLine("[red]error:[/] failed to start published app");
+                return new Result(false, 0, 0);
+            }
+
+            // Cover crash / Ctrl+C paths in addition to the finally block.
+            var procRef = proc;
+            AppDomain.CurrentDomain.ProcessExit += (_, _) => TryKill(procRef);
+            Console.CancelKeyPress += (_, _) => TryKill(procRef);
+
+            using var listeningEvent = new ManualResetEventSlim(false);
+            string? boundUrl = null;
+
+            void OnStreamLine(string line)
+            {
+                if (boundUrl is null)
+                {
+                    var m = KestrelListening.Match(line);
+                    if (m.Success)
+                    {
+                        boundUrl = m.Groups["url"].Value.TrimEnd('/');
+                        listeningEvent.Set();
+                    }
+                }
+            }
+
+            _ = Task.Run(() => ReadLines(proc.StandardOutput, OnStreamLine));
+            _ = Task.Run(() => ReadLines(proc.StandardError, OnStreamLine));
+
+            if (!listeningEvent.Wait(readyTimeout ?? TimeSpan.FromSeconds(30)) || boundUrl is null)
+            {
+                AnsiConsole.MarkupLine("[red]error:[/] published app never announced a listening port within timeout");
+                return new Result(false, 0, 0);
+            }
+
+            AnsiConsole.MarkupLine($"[dim]prerender:[/] app listening on [cyan]{boundUrl}[/]");
+
+            using var http = new HttpClient { BaseAddress = new Uri(boundUrl), Timeout = TimeSpan.FromSeconds(30) };
+            var rendered = 0;
+            var failed = 0;
+
+            foreach (var url in urls.Distinct(StringComparer.OrdinalIgnoreCase))
+            {
+                try
+                {
+                    var response = http.GetAsync(url).GetAwaiter().GetResult();
+                    if (!response.IsSuccessStatusCode)
+                    {
+                        AnsiConsole.MarkupLine($"  [yellow]warn:[/] [cyan]{url}[/] returned [yellow]{(int)response.StatusCode}[/]");
+                        failed++;
+                        continue;
+                    }
+                    var html = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                    var outPath = UrlToFilePath(url, outputDir);
+                    Directory.CreateDirectory(Path.GetDirectoryName(outPath)!);
+                    File.WriteAllText(outPath, html);
+                    rendered++;
+                }
+                catch (Exception ex)
+                {
+                    AnsiConsole.MarkupLine($"  [red]error:[/] [cyan]{url}[/] failed: {ex.Message}");
+                    failed++;
+                }
+            }
+
+            AnsiConsole.MarkupLine($"[dim]prerender:[/] wrote [green]{rendered}[/] page(s)" + (failed > 0 ? $", [yellow]{failed}[/] failed" : ""));
+            return new Result(failed == 0, rendered, failed);
+        }
+        finally
+        {
+            if (proc is not null) TryKill(proc);
+        }
+    }
+
+    private static string InferAssemblyName(string csproj)
+    {
+        try
+        {
+            var xml = File.ReadAllText(csproj);
+            var m = Regex.Match(xml, @"<AssemblyName>\s*(?<name>[^<\s]+)\s*</AssemblyName>", RegexOptions.IgnoreCase);
+            if (m.Success) return m.Groups["name"].Value;
+        }
+        catch { }
+        return Path.GetFileNameWithoutExtension(csproj);
+    }
+
+    // "/docs/introduction" → <output>/docs/introduction/index.html so static
+    // hosts serve /docs/introduction/ without a .html suffix.
+    private static string UrlToFilePath(string url, string outputDir)
+    {
+        var trimmed = url.Trim('/');
+        if (string.IsNullOrEmpty(trimmed))
+            return Path.Combine(outputDir, "index.html");
+        var segments = trimmed.Split('/');
+        var relative = Path.Combine(segments);
+        return Path.Combine(outputDir, relative, "index.html");
+    }
+
+    private static void TryKill(Process proc)
+    {
+        try { if (!proc.HasExited) proc.Kill(entireProcessTree: true); }
+        catch { }
+    }
+
+    // Reads until EOF, handing each line to onLine. Keeps reading past the
+    // "listening" match so the child's pipes never fill up and deadlock.
+    private static void ReadLines(StreamReader reader, Action<string> onLine)
+    {
+        try
+        {
+            string? line;
+            while ((line = reader.ReadLine()) is not null) onLine(line);
+        }
+        catch { }
+    }
+}
diff --git a/src/ShellDocs.Core/NavigationGraph.cs b/src/ShellDocs.Core/NavigationGraph.cs
index 9fad0e6..a9a003d 100644
--- a/src/ShellDocs.Core/NavigationGraph.cs
+++ b/src/ShellDocs.Core/NavigationGraph.cs
@@ -63,6 +63,10 @@ public IEnumerable<NavigationNode> Flatten()
         return FlattenFrom(Root);
     }
 
+    // Visible + hidden pages. Static prerender needs both — hidden pages
+    // still route at runtime.
+    public IEnumerable<string> AllUrls => _byUrl.Keys;
+
     private static IEnumerable<NavigationNode> FlattenFrom(NavigationNode node)
     {
         yield return node;
diff --git a/src/ShellDocs.Markdown/SlotExtractor.cs b/src/ShellDocs.Markdown/SlotExtractor.cs
index e0fb75c..7274991 100644
--- a/src/ShellDocs.Markdown/SlotExtractor.cs
+++ b/src/ShellDocs.Markdown/SlotExtractor.cs
@@ -165,10 +165,10 @@ the exact source the author authored. */
         {
             /* Unknown component. Emit an error PreviewSlot so PreviewFrame can
                render a visible "Unknown component <X>" panel in the browser.
-               The pre-fix behavior returned null here, which caused the whole
+               Returning null here (the pre-fix behavior) caused the whole
                fence to render as a plain code block — silent failure that sent
-               authors hunting for a nonexistent component bug (dogfood log,
-               SHELLDOCS_FIXES.md #4). Warning still emitted for build logs. */
+               authors hunting for a nonexistent component bug. Warning still
+               emitted for build logs. */
             var msg = $"Unknown component <{name}>. Register it via `o.RegisterComponent<{name}>()` or `o.RegisterComponentsFromAssembly<TMarker>()`.";
             warnings.Add($"razor:preview references unknown component <{name}>.");
             return new PreviewSlot(NewSlotId(), null, attrs, code, "razor", childContentRaw, Error: msg);
diff --git a/tests/ShellDocs.Tests/BuildCommandTests.cs b/tests/ShellDocs.Tests/BuildCommandTests.cs
index d980bcf..dd876b7 100644
--- a/tests/ShellDocs.Tests/BuildCommandTests.cs
+++ b/tests/ShellDocs.Tests/BuildCommandTests.cs
@@ -3,10 +3,6 @@
 
 namespace ShellDocs.Tests;
 
-/* We don't shell out to `dotnet publish` in tests (slow + fragile). We test
-   the two deterministic post-processing helpers in isolation: RewriteBaseHref
-   and the recursive CopyDirectory. Everything else in BuildCommand.Run is
-   glue around Process.Start, which is best verified by hand. */
 public class BuildCommandTests : IDisposable
 {
     private readonly string _tempDir;
@@ -22,8 +18,8 @@ public BuildCommandTests()
             .FirstOrDefault(a => a.GetName().Name == "shelldocs")
             ?? Assembly.Load("shelldocs");
         var type = cli.GetType("ShellDocs.CLI.Commands.BuildCommand", throwOnError: true)!;
-        _rewrite = type.GetMethod("RewriteBaseHref", BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!;
-        _copy    = type.GetMethod("CopyDirectory",   BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!;
+        _rewrite = type.GetMethod("RewriteBaseHrefInAllHtml", BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!;
+        _copy    = type.GetMethod("CopyDirectoryMerging",    BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!;
     }
 
     public void Dispose()
@@ -31,10 +27,10 @@ public void Dispose()
         try { Directory.Delete(_tempDir, recursive: true); } catch { }
     }
 
-    private void RewriteBaseHref(string indexPath, string href) =>
-        _rewrite.Invoke(null, new object[] { indexPath, href });
+    private int RewriteBaseHrefInAllHtml(string outputDir, string href) =>
+        (int)_rewrite.Invoke(null, new object[] { outputDir, href })!;
 
-    private void CopyDirectory(string source, string dest) =>
+    private void CopyDirectoryMerging(string source, string dest) =>
         _copy.Invoke(null, new object[] { source, dest });
 
     [Theory]
@@ -46,7 +42,8 @@ public void RewriteBaseHref_HandlesQuoteVariants(string original, string href, s
     {
         var path = Path.Combine(_tempDir, "index.html");
         File.WriteAllText(path, $"<html><head>{original}</head></html>");
-        RewriteBaseHref(path, href);
+        var count = RewriteBaseHrefInAllHtml(_tempDir, href);
+        Assert.Equal(1, count);
         Assert.Contains(expected, File.ReadAllText(path));
     }
 
@@ -56,7 +53,7 @@ public void RewriteBaseHref_LeavesOtherMarkupUntouched()
         var path = Path.Combine(_tempDir, "index.html");
         var input = "<html><head><title>App</title><base href=\"/\" /><meta /></head><body></body></html>";
         File.WriteAllText(path, input);
-        RewriteBaseHref(path, "/x/");
+        RewriteBaseHrefInAllHtml(_tempDir, "/x/");
         var output = File.ReadAllText(path);
         Assert.Contains("<title>App</title>", output);
         Assert.Contains("<meta />", output);
@@ -64,7 +61,27 @@ public void RewriteBaseHref_LeavesOtherMarkupUntouched()
     }
 
     [Fact]
-    public void CopyDirectory_CopiesNestedFiles()
+    public void RewriteBaseHref_WalksAllHtmlFilesRecursively()
+    {
+        var root = Path.Combine(_tempDir, "index.html");
+        var docs = Path.Combine(_tempDir, "docs", "introduction", "index.html");
+        var deep = Path.Combine(_tempDir, "docs", "cli", "build", "index.html");
+        Directory.CreateDirectory(Path.GetDirectoryName(docs)!);
+        Directory.CreateDirectory(Path.GetDirectoryName(deep)!);
+        File.WriteAllText(root, "<html><base href=\"/\" /></html>");
+        File.WriteAllText(docs, "<html><base href=\"/\" /></html>");
+        File.WriteAllText(deep, "<html><base href=\"/\" /></html>");
+
+        var count = RewriteBaseHrefInAllHtml(_tempDir, "/repo/");
+
+        Assert.Equal(3, count);
+        Assert.Contains("<base href=\"/repo/\" />", File.ReadAllText(root));
+        Assert.Contains("<base href=\"/repo/\" />", File.ReadAllText(docs));
+        Assert.Contains("<base href=\"/repo/\" />", File.ReadAllText(deep));
+    }
+
+    [Fact]
+    public void CopyDirectoryMerging_CopiesNestedFiles()
     {
         var src = Path.Combine(_tempDir, "src");
         var dst = Path.Combine(_tempDir, "dst");
@@ -73,7 +90,7 @@ public void CopyDirectory_CopiesNestedFiles()
         File.WriteAllText(Path.Combine(src, "sub", "mid.txt"), "mid");
         File.WriteAllText(Path.Combine(src, "sub", "deep", "leaf.txt"), "leaf");
 
-        CopyDirectory(src, dst);
+        CopyDirectoryMerging(src, dst);
 
         Assert.Equal("root", File.ReadAllText(Path.Combine(dst, "root.txt")));
         Assert.Equal("mid",  File.ReadAllText(Path.Combine(dst, "sub", "mid.txt")));
@@ -81,17 +98,35 @@ public void CopyDirectory_CopiesNestedFiles()
     }
 
     [Fact]
-    public void CopyDirectory_OverwritesExistingFiles()
+    public void CopyDirectoryMerging_DoesNotOverwriteExistingFiles()
+    {
+        // Prerendered HTML in output/ must survive the wwwroot merge on top.
+        var src = Path.Combine(_tempDir, "src");
+        var dst = Path.Combine(_tempDir, "dst");
+        Directory.CreateDirectory(src);
+        Directory.CreateDirectory(dst);
+        File.WriteAllText(Path.Combine(src, "index.html"), "asset-version");
+        File.WriteAllText(Path.Combine(dst, "index.html"), "prerendered-version");
+
+        CopyDirectoryMerging(src, dst);
+
+        Assert.Equal("prerendered-version", File.ReadAllText(Path.Combine(dst, "index.html")));
+    }
+
+    [Fact]
+    public void CopyDirectoryMerging_CopiesMissingFilesEvenWhenSomeExist()
     {
         var src = Path.Combine(_tempDir, "src");
         var dst = Path.Combine(_tempDir, "dst");
         Directory.CreateDirectory(src);
         Directory.CreateDirectory(dst);
-        File.WriteAllText(Path.Combine(src, "a.txt"), "new");
-        File.WriteAllText(Path.Combine(dst, "a.txt"), "old");
+        File.WriteAllText(Path.Combine(src, "a.txt"), "src-a");
+        File.WriteAllText(Path.Combine(src, "b.txt"), "src-b");
+        File.WriteAllText(Path.Combine(dst, "a.txt"), "dst-a");
 
-        CopyDirectory(src, dst);
+        CopyDirectoryMerging(src, dst);
 
-        Assert.Equal("new", File.ReadAllText(Path.Combine(dst, "a.txt")));
+        Assert.Equal("dst-a", File.ReadAllText(Path.Combine(dst, "a.txt")));
+        Assert.Equal("src-b", File.ReadAllText(Path.Combine(dst, "b.txt")));
     }
 }