Rework docs navigation and move alternatives to top-level pages (#1487)

* Rework docs navigation and move alternatives to top-level pages

- Add nested docs nav with categories, collapsible groups, breadcrumbs,
  and a right-hand page outline with heading slugs.
- Move alternatives out of /docs/alternatives into /alternatives/*
  marketing pages with 301 redirects.
- Add github-slugger for heading IDs and require explicit width on
  SiteShell so new pages can't accidentally pick the narrow prose layout.
- Remove the best-practices doc from public-docs.

* Make docs content column prose-width

packages/website/vite.config.ts

@@ -22,8 +22,11 @@ function discoverDocsRoutes(): string[] {
         continue;
       }
       if (!entry.name.endsWith(".md")) continue;
-      const rel = path.relative(docsDir, full).replace(/\.md$/, "");
-      if (rel === "index") continue;
+      const rel = path
+        .relative(docsDir, full)
+        .replace(/\.md$/, "")
+        .replace(/\/index$/, "");
+      if (rel === "index" || rel === "") continue;
       routes.add(`/docs/${rel.split(path.sep).join("/")}`);
     }
   };
@@ -54,6 +57,17 @@ function discoverAgentRoutes(): string[] {
     .map((slug) => `/${slug}`);
 }
 
+function discoverAlternativeRoutes(): string[] {
+  const alternativesDir = path.join(__dirname, "src/routes/alternatives");
+  if (!fs.existsSync(alternativesDir)) return [];
+  const slugs = fs
+    .readdirSync(alternativesDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".tsx"))
+    .map((entry) => entry.name.replace(/\.tsx$/, ""))
+    .sort();
+  return ["/alternatives", ...slugs.map((slug) => `/alternatives/${slug}`)];
+}
+
 function discoverBlogRoutes(): string[] {
   const postsDir = path.join(__dirname, "posts");
   if (!fs.existsSync(postsDir)) return ["/blog"];
@@ -73,6 +87,7 @@ const sitemapPages = [
   "/download",
   "/privacy",
   ...discoverAgentRoutes(),
+  ...discoverAlternativeRoutes(),
   ...discoverDocsRoutes(),
   ...discoverBlogRoutes(),
 ].map((routePath) => ({