docs: Card-based Guides discovery page with category filtering

src/components/GuidesLanding.astro

@@ -0,0 +1,236 @@
+---
+// 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.
+//
+// Categories use a problem/solution (use-case) taxonomy that cuts across
+// the filesystem directory structure. Each guide is assigned to exactly
+// one category via the GUIDE_CATEGORIES map below.
+import { getCollection } from 'astro:content';
+
+// Use-case categories — ordered as they appear in the filter pill bar.
+const CATEGORY_LABELS: Record<string, string> = {
+	setup: 'Set up your environment',
+	agents: 'Work with agents',
+	automate: 'Automate your workflow',
+	connect: 'Connect external services',
+	'build-deploy': 'Build & deploy apps',
+	'review-debug': 'Review & debug',
+};
+
+// Map guide paths (relative to guides/) to use-case categories.
+// Guides not listed here fall back to a directory-based default.
+const GUIDE_CATEGORIES: Record<string, string> = {
+	// Set up your environment — first steps + tool installation
+	'getting-started/welcome-to-warp': 'setup',
+	'getting-started/10-coding-features-you-should-know': 'setup',
+	'getting-started/how-to-customize-warps-appearance': 'setup',
+	'getting-started/how-to-make-warps-ui-more-minimal': 'setup',
+	'external-tools/how-to-set-up-claude-code': 'setup',
+	'external-tools/how-to-set-up-codex-cli': 'setup',
+	'external-tools/how-to-set-up-gemini-cli': 'setup',
+	'external-tools/how-to-set-up-ollama': 'setup',
+	'external-tools/how-to-set-up-opencode': 'setup',
+
+	// Work with agents — prompting, voice, images, parallel tasks
+	'agent-workflows/how-to-attach-agent-session-context-to-github-prs': 'agents',
+	'agent-workflows/how-to-run-unattended-agents': 'agents',
+	'agent-workflows/how-to-run-multiple-ai-coding-agents': 'agents',
+	'agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents': 'agents',
+	'agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase': 'agents',
+	'agent-workflows/how-to-run-3-agents-in-parallel-summarize-logs-analyze-pr-modify-ui': 'agents',
+	'agent-workflows/how-to-edit-agent-code-in-warp': 'agents',
+	'agent-workflows/using-images-as-context-with-warp': 'agents',
+	'agent-workflows/understanding-your-codebase': 'agents',
+	'agent-workflows/running-multiple-agents-at-once-with-warp': 'agents',
+	'agent-workflows/warp-for-product-managers': 'agents',
+	'agent-workflows/warp-vs-claude-code': 'agents',
+
+	// Automate your workflow — rules, profiles, prompts, skills
+	'configuration/how-to-create-project-rules-for-an-existing-project-astro-typescript-tailwind': 'automate',
+	'configuration/how-to-set-coding-best-practices': 'automate',
+	'configuration/how-to-set-tech-stack-preferences-with-rules': 'automate',
+	'configuration/how-to-set-coding-preferences-with-rules': 'automate',
+	'configuration/how-to-configure-yolo-and-strategic-agent-profiles': 'automate',
+	'configuration/how-to-use-agent-profiles-efficiently': 'automate',
+	'configuration/creating-rules-for-agents': 'automate',
+	'configuration/trigger-reusable-actions-with-saved-prompts': 'automate',
+	'configuration/how-to-set-up-self-serve-data-analytics-with-skills': 'automate',
+	'configuration/how-to-sync-your-monorepos': 'automate',
+
+	// Connect external services — MCP servers
+	'external-tools/sentry-mcp-fix-sentry-error-in-empower-website': 'connect',
+	'external-tools/figma-remote-mcp-create-a-website-from-a-figma-file-from-scratch': 'connect',
+	'external-tools/linear-mcp-retrieve-issue-data': 'connect',
+	'external-tools/linear-mcp-updating-tickets-with-a-lean-build-approach': 'connect',
+	'external-tools/github-mcp-summarizing-open-prs-and-creating-gh-issues': 'connect',
+	'external-tools/puppeteer-mcp-scraping-amazon-web-reviews': 'connect',
+	'external-tools/context7-mcp-update-astro-project-with-best-practices': 'connect',
+	'external-tools/sqlite-and-stripe-mcp-basic-queries-you-can-make-after-set-up': 'connect',
+	'external-tools/using-mcp-servers-with-warp': 'connect',
+
+	// Build & deploy apps — end-to-end builds, Docker, K8s, cloud, frontend
+	'build-an-app-in-warp/building-a-real-time-chat-app-github-mcp-railway': 'build-deploy',
+	'build-an-app-in-warp/building-a-chrome-extension-d3js-javascript-html-css': 'build-deploy',
+	'build-an-app-in-warp/building-warps-input-with-warp': 'build-deploy',
+	'devops/how-to-analyze-cloud-run-logs-gcloud': 'build-deploy',
+	'devops/how-to-create-a-production-ready-docker-setup': 'build-deploy',
+	'devops/improve-your-kubernetes-workflow-kubectl-helm': 'build-deploy',
+	'frontend/how-to-actually-code-ui-that-matches-your-mockup-react-tailwind': 'build-deploy',
+	'frontend/how-to-replace-a-ui-element-in-warp-rust-codebase': 'build-deploy',
+
+	// Review & debug — PR review, code review, testing, database, secrets
+	'agent-workflows/how-to-review-ai-generated-code': 'review-debug',
+	'agent-workflows/how-to-review-prs-like-a-senior-dev': 'review-debug',
+	'getting-started/how-to-master-warps-code-review-panel': 'review-debug',
+	'devops/how-to-generate-unit-and-security-tests-to-debug-faster': 'review-debug',
+	'devops/how-to-write-sql-commands-inside-a-postgres-repl': 'review-debug',
+	'devops/how-to-create-priority-matrix-for-database-optimization': 'review-debug',
+	'devops/how-to-prevent-secrets-from-leaking': 'review-debug',
+};
+
+/** Resolve a guide's use-case category from its path. */
+function resolveCategory(guideId: string): string {
+	// Strip 'guides/' prefix and file extension to get the lookup key
+	const key = guideId.replace(/^guides\//, '').replace(/\.mdx?$/, '');
+	return GUIDE_CATEGORIES[key] || 'agents'; // fallback
+}
+
+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 = resolveCategory(doc.id);
+		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 (preserving CATEGORY_LABELS order)
+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="group" aria-label="Filter guides by category">
+		{featured.length > 0 && (
+			<button
+				aria-pressed="true"
+				class="warp-guide-filter-pill active"
+				data-filter="featured"
+			>
+				Featured ({featured.length})
+			</button>
+		)}
+		<button
+			aria-pressed="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
+					aria-pressed="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-pressed', 'false');
+				});
+				pill.classList.add('active');
+				pill.setAttribute('aria-pressed', '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

@@ -1,10 +1,13 @@
 ---
-title: "How to: Edit Agent Code in Warp"
+title: "Edit agent code in Warp"
 description: >-
   Review, edit, and refine AI-generated code diffs directly in Warp — accept,
   reject, or modify changes before applying them.
 sidebar:
-  label: "Edit Agent code in Warp"
+  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

@@ -1,11 +1,14 @@
 ---
-title: "How to: Explain Your Codebase Using Warp (Rust Codebase)"
+title: "Explain your codebase using Warp (Rust codebase)"
 description: >-
   Use Warp's coding agents with semantic and symbol search to explore,
   understand, and modify unfamiliar codebases — demonstrated on a large Rust
   project.
 sidebar:
   label: "Explain your codebase using Warp"
+tags:
+  - "agents"
+
 ---
 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

@@ -1,10 +1,15 @@
 ---
-title: How to review AI-generated code
+title: Review AI-generated code
 description: >-
   Review AI-generated code in Warp with visual diffs and inline comments —
   works with Claude Code, Codex, or any CLI agent.
 sidebar:
   label: "Review AI-generated code"
+featured: true
+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

@@ -1,10 +1,14 @@
 ---
-title: "How To: Review PRs Like A Senior Dev"
+title: "Review PRs like a senior dev"
 description: >-
   Prompt Warp's coding agent to generate structured PR reviews with risk
   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

@@ -1,10 +1,13 @@
 ---
-title: "How To: Run 3 Agents in Parallel"
+title: "Run 3 agents in parallel"
 description: >-
   Run three agent tasks simultaneously in Warp — modify UI, analyze code
   reviews, and summarize production logs in parallel.
 sidebar:
   label: "Run 3 agents in parallel"
+tags:
+  - "agents"
+
 ---
 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

@@ -1,10 +1,14 @@
 ---
-title: How to run multiple AI coding agents
+title: Run multiple AI coding agents
 description: >-
   Run Claude Code, Codex, Warp Agent, and other coding agents across worktrees,
   tabs, and cloud orchestration with clear task ownership.
 sidebar:
   label: "Run multiple AI coding agents"
+featured: true
+tags:
+  - "agents"
+
 ---
 
 Use multiple coding agents, including Warp Agent, Claude Code, Codex, and other CLI agents, when work can be split into independent tasks, reviewed from separate branches, or delegated to cloud agents while you keep working locally. In Warp, you can coordinate agents in three ways:

src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx

@@ -5,6 +5,7 @@ description: >-
   the Oz CLI, or the Oz API, then inspect every run.
 sidebar:
   label: "Run unattended agents"
+featured: true
 tags:
   - "agents"
   - "cloud-agents"

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

@@ -1,10 +1,13 @@
 ---
-title: How to use voice and images to prompt coding agents
+title: Use voice and images to prompt coding agents
 description: >-
   Use voice and image context to prompt coding agents faster in Warp — works
   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

@@ -1,10 +1,13 @@
 ---
-title: Running Multiple Agents At Once With Warp
+title: Run multiple agents at once with Warp
 description: >-
   Run multiple agent tasks simultaneously in Warp — revert PRs, edit
   shortcuts, and add tests across repos without losing context.
 sidebar:
   label: "Run multiple agents at once"
+tags:
+  - "agents"
+
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';