docs: Card-based Guides discovery page with category filtering

src/components/GuidesLanding.astro

@@ -0,0 +1,157 @@
+---
+// Pure Astro component for the Guides card-based discovery page.
+// Renders the full card grid at build time; a small inline script
+// handles filter-pill interactivity on the client.
+import { getCollection } from 'astro:content';
+
+const CATEGORY_LABELS: Record<string, string> = {
+	'getting-started': 'Getting started',
+	'agent-workflows': 'Agent workflows',
+	configuration: 'Configuration',
+	'external-tools': 'External tools',
+	'build-an-app-in-warp': 'Build an app',
+	devops: 'DevOps',
+	frontend: 'Frontend & UI',
+};
+
+const allDocs = await getCollection('docs', (entry) =>
+	entry.id.startsWith('guides/') && entry.id !== 'guides' && !entry.id.endsWith('/index'),
+);
+
+interface GuideData {
+	title: string;
+	description: string;
+	href: string;
+	category: string;
+	categoryLabel: string;
+	tags: string[];
+	featured: boolean;
+}
+
+const guides: GuideData[] = allDocs
+	.filter((doc) => {
+		const parts = doc.id.replace(/^guides\//, '').split('/');
+		return parts.length >= 2;
+	})
+	.map((doc) => {
+		const category = doc.id.replace(/^guides\//, '').split('/')[0];
+		return {
+			title: (doc.data as any).sidebar?.label || doc.data.title,
+			description: doc.data.description || '',
+			href: '/' + doc.id.replace(/\.mdx?$/, '') + '/',
+			category,
+			categoryLabel: CATEGORY_LABELS[category] || category,
+			tags: (doc.data as any).tags || [],
+			featured: (doc.data as any).featured || false,
+		};
+	});
+
+const featured = guides.filter((g) => g.featured);
+
+// Derive ordered categories
+const categories = Object.keys(CATEGORY_LABELS).filter((cat) =>
+	guides.some((g) => g.category === cat),
+);
+---
+
+<div class="warp-guide-grid-container not-content">
+	{/* Filter pills — Featured is the default; All shows everything flat */}
+	<div class="warp-guide-filters" role="tablist" aria-label="Filter guides by category">
+		{featured.length > 0 && (
+			<button
+				role="tab"
+				aria-selected="true"
+				class="warp-guide-filter-pill active"
+				data-filter="featured"
+			>
+				Featured ({featured.length})
+			</button>
+		)}
+		<button
+			role="tab"
+			aria-selected="false"
+			class="warp-guide-filter-pill"
+			data-filter="all"
+		>
+			All ({guides.length})
+		</button>
+		{categories.map((cat) => {
+			const count = guides.filter((g) => g.category === cat).length;
+			return (
+				<button
+					role="tab"
+					aria-selected="false"
+					class="warp-guide-filter-pill"
+					data-filter={cat}
+				>
+					{CATEGORY_LABELS[cat]} ({count})
+				</button>
+			);
+		})}
+	</div>
+
+	{/* Single card grid — filtering is handled client-side */}
+	<div class="warp-guide-card-grid">
+		{guides.map((guide) => (
+			<a
+				href={guide.href}
+				class="warp-guide-card"
+				data-category={guide.category}
+				data-featured={guide.featured ? 'true' : undefined}
+			>
+				<span class="warp-guide-card-category">{guide.categoryLabel}</span>
+				<h3 class="warp-guide-card-title">{guide.title}</h3>
+				{guide.description && <p class="warp-guide-card-desc">{guide.description}</p>}
+				{guide.tags.length > 0 && (
+					<div class="warp-guide-card-tags">
+						{guide.tags.map((tag) => (
+							<span class="warp-guide-card-tag">{tag}</span>
+						))}
+					</div>
+				)}
+			</a>
+		))}
+	</div>
+</div>
+
+<script is:inline>
+	// Client-side filter pill interactivity
+	(() => {
+		const container = document.querySelector('.warp-guide-grid-container');
+		if (!container) return;
+
+		const pills = container.querySelectorAll('.warp-guide-filter-pill');
+		const cards = container.querySelectorAll('.warp-guide-card');
+
+		pills.forEach((pill) => {
+			pill.addEventListener('click', () => {
+				const filter = pill.getAttribute('data-filter');
+
+				// Update pill states
+				pills.forEach((p) => {
+					p.classList.remove('active');
+					p.setAttribute('aria-selected', 'false');
+				});
+				pill.classList.add('active');
+				pill.setAttribute('aria-selected', 'true');
+
+				// Filter cards
+				cards.forEach((card) => {
+					let show = false;
+					if (filter === 'all') {
+						show = true;
+					} else if (filter === 'featured') {
+						show = card.hasAttribute('data-featured');
+					} else {
+						show = card.getAttribute('data-category') === filter;
+					}
+					card.style.display = show ? '' : 'none';
+				});
+			});
+		});
+
+		// Apply initial filter (Featured is default)
+		const defaultPill = container.querySelector('.warp-guide-filter-pill.active');
+		if (defaultPill) defaultPill.click();
+	})();
+</script>

src/content.config.ts

@@ -2,10 +2,25 @@ import { defineCollection } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 import { topicSchema } from 'starlight-sidebar-topics/schema';
+import { z } from 'astro/zod';
 
 export const collections = {
 	// `topicSchema` adds a `topic` frontmatter field used by
 	// `starlight-sidebar-topics` to associate unlisted pages with a topic ID.
 	// See guides/agent-workflows/warp-vs-claude-code.mdx for an example.
-	docs: defineCollection({ loader: docsLoader(), schema: docsSchema({ extend: topicSchema }) }),
+	//
+	// Custom fields added for the Guides card-based discovery page:
+	// - `tags`: topic/task tags for filtering (e.g. ["mcp", "agents", "docker"])
+	// - `featured`: marks guides for the curated "Featured" section
+	docs: defineCollection({
+		loader: docsLoader(),
+		schema: docsSchema({
+			extend: topicSchema.merge(
+				z.object({
+					tags: z.array(z.string()).optional(),
+					featured: z.boolean().optional().default(false),
+				}),
+			),
+		}),
+	}),
 };

src/content/docs/guides/agent-workflows/how-to-edit-agent-code-in-warp.mdx

@@ -5,6 +5,9 @@ description: >-
   reject, or modify changes before applying them.
 sidebar:
   label: "Edit Agent code in Warp"
+tags:
+  - "agents"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase.mdx

@@ -6,6 +6,10 @@ description: >-
   project.
 sidebar:
   label: "Explain your codebase using Warp"
+tags:
+  - "agents"
+featured: true
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';

src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx

@@ -5,6 +5,10 @@ description: >-
   works with Claude Code, Codex, or any CLI agent.
 sidebar:
   label: "Review AI-generated code"
+tags:
+  - "agents"
+  - "code-review"
+
 ---
 
 Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. This guide provides a practical workflow for reviewing agent-generated code in Warp, catching common issues, and giving structured feedback that the agent can act on. Plan on about 10 minutes to complete.

src/content/docs/guides/agent-workflows/how-to-review-prs-like-a-senior-dev.mdx

@@ -5,6 +5,10 @@ description: >-
   assessment, critical issues, and merge confidence scoring.
 sidebar:
   label: "Review PRs like a senior dev"
+tags:
+  - "agents"
+  - "code-review"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';

src/content/docs/guides/agent-workflows/how-to-run-3-agents-in-parallel-summarize-logs-analyze-pr-modify-ui.mdx

@@ -5,6 +5,10 @@ description: >-
   reviews, and summarize production logs in parallel.
 sidebar:
   label: "Run 3 agents in parallel"
+tags:
+  - "agents"
+featured: true
+
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';

src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx

@@ -6,6 +6,9 @@ description: >-
   once.
 sidebar:
   label: "Run multiple AI coding agents"
+tags:
+  - "agents"
+
 ---
 
 Different agents have different strengths. Claude Code might handle refactoring well while Codex might excel at test generation. Instead of choosing one, you can run them in parallel. Assign different tasks to different agents, compare their outputs on the same problem, or have one agent build while another reviews. This guide shows you how to set up a multi-agent workflow in Warp and manage it effectively. Plan on about 15 minutes.

src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx

@@ -5,6 +5,9 @@ description: >-
   with Claude Code, Codex, and any CLI agent.
 sidebar:
   label: "Use voice and images to prompt coding agents"
+tags:
+  - "agents"
+
 ---
 
 Typing detailed prompts for coding agents can be slow. Describing a bug from a screenshot, dictating a complex refactoring plan, or explaining a UI change from a design mockup are examples of tasks that are faster with voice and images than with text alone. This guide shows you how to use multimodal input with any CLI coding agent running in Warp in about 5 minutes.

src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx

@@ -5,6 +5,9 @@ description: >-
   shortcuts, and add tests across repos without losing context.
 sidebar:
   label: "Run multiple agents at once"
+tags:
+  - "agents"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/agent-workflows/understanding-your-codebase.mdx

@@ -5,6 +5,9 @@ description: >-
   generate architecture summaries, and onboard to unfamiliar features fast.
 sidebar:
   label: "Understand your codebase"
+tags:
+  - "agents"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/agent-workflows/using-images-as-context-with-warp.mdx

@@ -5,6 +5,9 @@ description: >-
   generate UI code, debug visual issues, and match Figma designs.
 sidebar:
   label: "Use images as context"
+tags:
+  - "agents"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/agent-workflows/warp-for-product-managers.mdx

@@ -3,6 +3,9 @@ title: "5 agent workflows for product managers"
 description: >-
   Five agent workflows that automate status updates, documentation, Slack search,
   and meeting prep for product managers.
+tags:
+  - "agents"
+
 ---
 Most PM work breaks down into three activities: gathering information, synthesizing it, and communicating the result. These five workflows use Warp's agents and MCP integrations to automate the gathering and speed up the synthesis, so you spend less time switching between tools and more time making decisions. Each workflow takes 5–10 minutes to set up.
 

src/content/docs/guides/agent-workflows/warp-vs-claude-code.mdx

@@ -7,6 +7,10 @@ description: >-
 # field associates the page with the Guides topic so starlight-sidebar-topics
 # can resolve it without listing it under any group.
 topic: guides
+tags:
+  - "agents"
+  - "third-party-tools"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/build-an-app-in-warp/building-a-chrome-extension-d3js-javascript-html-css.mdx

@@ -5,6 +5,10 @@ description: >-
   coordinate multiple agents, and publish to the Chrome Web Store.
 sidebar:
   label: "Build a Chrome extension"
+tags:
+  - "build-app"
+  - "frontend"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';

src/content/docs/guides/build-an-app-in-warp/building-a-real-time-chat-app-github-mcp-railway.mdx

@@ -5,6 +5,11 @@ description: >-
   from idea to production, all inside Warp.
 sidebar:
   label: "Build a real-time chat app"
+tags:
+  - "build-app"
+  - "mcp"
+featured: true
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';

src/content/docs/guides/build-an-app-in-warp/building-a-slackbot.mdx

@@ -5,6 +5,9 @@ description: >-
   directly from Slack using Docker and GitHub integration.
 sidebar:
   label: "Build a Slackbot"
+tags:
+  - "build-app"
+
 ---
 import { Steps } from '@astrojs/starlight/components';
 

src/content/docs/guides/build-an-app-in-warp/building-warps-input-with-warp.mdx

@@ -5,6 +5,10 @@ description: >-
   a UI component change in a large Rust codebase.
 sidebar:
   label: "Build Warp's input component"
+tags:
+  - "build-app"
+  - "frontend"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/configuration/creating-rules-for-agents.mdx

@@ -5,6 +5,9 @@ description: >-
   patterns or dependency management — so agents follow your standards.
 sidebar:
   label: "Create Rules for Agents"
+tags:
+  - "rules"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 

src/content/docs/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.mdx

@@ -5,6 +5,9 @@ description: >-
   and execution speed — demonstrated with YOLO and Strategic examples.
 sidebar:
   label: "Configure YOLO and strategic Agent Profiles"
+tags:
+  - "profiles"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';

src/content/docs/guides/configuration/how-to-create-project-rules-for-an-existing-project-astro-typescript-tailwind.mdx

@@ -5,6 +5,10 @@ description: >-
   understand your project's setup, commands, architecture, and conventions.
 sidebar:
   label: "Create project Rules for an existing project"
+tags:
+  - "rules"
+featured: true
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps, FileTree } from '@astrojs/starlight/components';

src/content/docs/guides/configuration/how-to-set-coding-best-practices.mdx

@@ -5,6 +5,9 @@ description: >-
   documentation quality across AI-generated code.
 sidebar:
   label: "Set coding best practices"
+tags:
+  - "rules"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 import { Steps } from '@astrojs/starlight/components';