feat(guides): merge every product repo's guides into the Guides tab

CLAUDE.md

@@ -17,7 +17,7 @@ Applies to all user-facing writing on the website (docs, marketing, blog). Inter
 
 ## Docs Routing
 
-- The site-wide docs overview is `/docs/`; the Guides tab is `/guides/` (the Actors bundle's `learn` section plus website-owned guides in `src/content/guides/`); the Deploy tab is `/docs/deploy/{self-host,byoc,cloud}/`. Product documentation stays at `/{product}/docs/` and `/{product}/integrations/`.
+- The site-wide docs overview is `/docs/`; the Guides tab is `/guides/` (every product bundle's `content/guides/` and `guides` sidebar key, merged in product order with same-titled groups combined; the website owns only the overview in `src/content/guides/index.mdx`); the Deploy tab is `/docs/deploy/{self-host,byoc,cloud}/`. Product documentation stays at `/{product}/docs/` and `/{product}/integrations/`.
 - The route prefixes live in `src/sitemap/deploy.ts` and `src/sitemap/guides.ts`. Derive hrefs from them; never hand-write `/orchestrate/`, `/{product}/self-host/`, or `/actors/learn/`, which are redirects.
 
 ## Docs Pages

DARK_MODE_ASSETS.md

@@ -24,7 +24,7 @@ Run `node scripts/check-theme.mjs` against a dev server to verify the CSS-handle
 | Product wordmarks `src/images/products/*-logo.svg` | `ProductBadge`, `ProductLockup`, `StackSection` | Always white inside an ink or accent tile (AGENTS.md rule). No change needed. |
 | Inline SVG diagrams that hardcode the light palette (`#1b1916`, `#56524a`, `#8a8578`, `#2E4034`, `#ffffff`, `#faf8f3`, `#e7ece7`) as presentation attributes | Vendored docs under `vendor/*/docs` (versions, tracing, dynamic-apps, agentOS architecture, quickstarts) and dated blog posts | `theme.css` remaps each hex to its dark token with `[fill="…" i]` / `[stroke="…" i]` selectors inside `.docs-article` and `.blog-article`; CSS wins over a presentation attribute. Surface remaps are guarded by `svg:has(ink-or-pine)` so they never touch another palette. Website-owned diagrams (`src/components/docs/*Diagram.astro`, `src/content/self-host/**`) were converted to `rgb(var(--site-*, fallback))` tokens instead and need no remap. |
 | Inline SVG diagrams drawn in a foreign palette (agentOS `security-model`, `architecture/posix-syscalls`, `architecture/packages-and-command-resolution` use Tailwind zinc/slate/indigo/emerald) | `vendor/agentos/docs` | `theme.css` applies `invert(1) hue-rotate(180deg)` to any `.docs-article svg[role="img"]` that uses neither tokens, `currentColor`, nor the site palette. |
-| Excalidraw PNG diagrams on an opaque white plate (`assets.rivet.dev/website/docs/general/runtime-modes/*.png`, `endpoints/endpoint-env-vars.png`, `website/learn/act-1/scene-1/*.png`) | `vendor/docs/docs/content/runtime-modes.mdx`, `endpoints.mdx`; `src/content/guides/a-radically-simpler-architecture.mdx` | `theme.css` applies `invert(1) hue-rotate(180deg)` to `.docs-article img[alt*="diagram" i]` and to `.theme-diagram-invert`. Vendored `<img>`s match on their alt text; the two guide figures whose alt lacks "diagram" carry the class. Screenshots never match. |
+| Excalidraw PNG diagrams on an opaque white plate (`assets.rivet.dev/website/docs/general/runtime-modes/*.png`, `endpoints/endpoint-env-vars.png`, `website/learn/act-1/scene-1/*.png`) | `vendor/docs/docs/content/runtime-modes.mdx`, `endpoints.mdx`; `vendor/actors/docs/content/guides/a-radically-simpler-architecture.mdx` | `theme.css` applies `invert(1) hue-rotate(180deg)` to `.docs-article img[alt*="diagram" i]` and to `.theme-diagram-invert`. Vendored `<img>`s match on their alt text; the two guide figures whose alt lacks "diagram" carry the class. Screenshots never match. |
 | Mermaid fences (`pre.mermaid`, only in `src/content/posts/2026-06-17-introducing-the-rust-sdk/page.mdx` outside the Learn section) | `MermaidScript.astro` | Picks `neutral`/`dark` from the background luminance at render, keeps the source in `data-mermaid-source`, and re-renders on the `theme-change` event so a toggle does not leave a stale light diagram. |
 
 ## Intentionally unchanged

HIDDEN.md

@@ -12,19 +12,10 @@ working — they are just unreachable from the nav.
 | Product | Tab | Why | To restore |
 | --- | --- | --- | --- |
 | All | Use Cases | The other three are stubs, and agentOS retired its page (`/agentos/use-cases/` redirects to `/guides/`) | Write them, add `"use-cases"` back to each `tabs` |
-| Actors | Learn | Cookbooks are thin and the section has no landing copy | Add `"learn"` to `optionalTabs` and `tabs` |
 | agentOS | Learn | Was generated from `examples/*/README.md` by a loader that did not survive the split. Content deleted; READMEs still in `~/agentos/examples/` | Port the loader or convert the READMEs to MDX |
 | Dynamic Apps | Learn | Placeholder only, deleted | Write it |
 | Workflows | Learn | Placeholder only, deleted | Write it |
 
-### Pages behind the hidden Actors Learn tab
-
-Still routed at `/actors/learn/*`, unreachable from the nav:
-
-- `a-radically-simpler-architecture` — a full essay, the strongest piece here
-- `ai-agent`, `chat-room`, `collaborative-text-editor`, `cron-jobs`,
-  `live-cursors`, `multiplayer-game`, `per-tenant-database` — cookbooks
-
 ## Hidden products
 
 | Product | Why |

redirects.mjs

@@ -341,13 +341,12 @@ function selfHostRedirects() {
 	return map;
 }
 
-// The Actors bundle's `learn` section rendered at `/actors/learn/...` before
-// it became the site-wide Guides tab at `/guides/...`. Website-owned guides in
-// `src/content/guides` never had another URL, but are included so the map
-// lists every guide.
+// The Actors bundle's guides rendered at `/actors/learn/...` before they moved
+// to the site-wide Guides tab at `/guides/...`. Guides from other bundles never
+// had another URL.
 function guidesRedirects() {
 	const map = {};
-	for (const slug of mdxSlugs(path.join(CONTENT_ROOT, 'docs/actors/learn'))) {
+	for (const slug of mdxSlugs(path.join(CONTENT_ROOT, 'docs/actors/guides'))) {
 		map[slug ? `/actors/learn/${slug}` : '/actors/learn'] = slug ? `/guides/${slug}/` : '/guides/';
 	}
 	return map;

scripts/check-sitemap.ts

@@ -13,8 +13,8 @@
  *   3. Every product docs/integrations sidebar href resolves to a content file.
  *   4. Every sidebar href appears in exactly one tab.
  *   5. Every routed, indexable product-doc page has a sidebar or content inlink.
- *   6. Every Guides sidebar href resolves to an Actors `learn` page or a
- *      website-owned guide.
+ *   6. The Guides sidebar and every bundle's `guides` content directory agree
+ *      exactly, and no two bundles define the same guide slug.
  *   7. The site Integrations sidebar (`/integrations/`) and the Actors
  *      `integrations` content directory agree exactly.
  *
@@ -37,9 +37,9 @@ import {
 } from "../src/sitemap/deploy";
 import { selfHostGuides } from "../src/sitemap/deployMatrix";
 import {
-	ACTORS_LEARN_CONTENT_PREFIX,
+	GUIDE_BUNDLES,
 	GUIDES_ROUTE_PREFIX,
-	SITE_GUIDES,
+	GUIDES_SECTION,
 } from "../src/sitemap/guides";
 import { integrationSidebar } from "../src/data/integrations";
 import {
@@ -279,9 +279,32 @@ for (const product of products) {
 	}
 }
 
-// 6. Every Guides sidebar href is an Actors `learn` page or a website guide.
+// 6. The Guides sidebar and every bundle's `guides` content directory agree
+// exactly: every href has one content file, every guide file has a sidebar
+// link, and no two bundles define the same slug.
 {
-	const learnContent = path.join(DOCS_CONTENT, ACTORS_LEARN_CONTENT_PREFIX);
+	const owners = new Map<string, string[]>();
+	for (const bundle of GUIDE_BUNDLES) {
+		const base = path.join(DOCS_CONTENT, bundle, GUIDES_SECTION);
+		for (const file of fg.sync("**/*.mdx", { cwd: base, followSymbolicLinks: true })) {
+			const slug = file.replace(/\.mdx$/, "").replace(/(^|\/)index$/, "");
+			if (!slug) {
+				errors.push(
+					`${bundle}/${GUIDES_SECTION}/index.mdx is never rendered; the Guides overview is website-owned`,
+				);
+				continue;
+			}
+			owners.set(slug, [...(owners.get(slug) ?? []), bundle]);
+		}
+	}
+	for (const [slug, bundles] of owners) {
+		if (bundles.length > 1) {
+			errors.push(
+				`${GUIDES_ROUTE_PREFIX}/${slug}/ is defined by more than one bundle: ${bundles.join(", ")}`,
+			);
+		}
+	}
+	const sidebarSlugs = new Set<string>();
 	for (const href of collectHrefs(guidesSidebar())) {
 		if (!href.startsWith(`${GUIDES_ROUTE_PREFIX}/`)) {
 			errors.push(
@@ -292,16 +315,21 @@ for (const product of products) {
 		const slug = href
 			.slice(`${GUIDES_ROUTE_PREFIX}/`.length)
 			.replace(/\/$/, "");
-		// The Guides overview is website-owned; the Actors bundle carries only
-		// the worked examples under it.
-		const siteGuide = slug
-			? SITE_GUIDES.some((guide) => guide.slug === slug) &&
-				contentFileExists(GUIDES_CONTENT, slug)
+		sidebarSlugs.add(slug);
+		const exists = slug
+			? owners.has(slug)
 			: contentFileExists(GUIDES_CONTENT, "index");
-		if (!siteGuide && !contentFileExists(learnContent, slug)) {
+		if (!exists) {
 			errors.push(`Guides sidebar links ${href}, which has no content file`);
 		}
 	}
+	for (const [slug, bundles] of owners) {
+		if (!sidebarSlugs.has(slug)) {
+			errors.push(
+				`${bundles[0]}/${GUIDES_SECTION}/${slug}.mdx is not linked from that bundle's "guides" sidebar`,
+			);
+		}
+	}
 }
 
 // 7. The site Integrations sidebar and the Actors `integrations` content

src/components/docs/GuideCards.tsx

@@ -35,7 +35,7 @@ function guideGroups(overviewHref: string): GuideGroup[] {
 /**
  * The Guides overview, generated from the same sidebar the tab is built from:
  * one heading per sidebar section, then a card per guide in it. Adding a guide
- * to the Actors bundle's sidebar or to `SITE_GUIDES` updates both.
+ * to any bundle's `guides` sidebar updates both.
  *
  * `descriptions` maps each guide href to its frontmatter description; the
  * route supplies it from the content collections.