Restructure AI coding agents docs: skill-first, MCP as sub-pages

src/frontend/config/head.attrs.ts

@@ -24,7 +24,8 @@ export const headAttrs: HeadAttr[] = [
 					.NET, observability, otel, opentelemetry, dashboard, service discovery, integrations,
 					C#, csharp, multi-language, polyglot, python, go, node.js, javascript, typescript,
 					vite, react, blazor, wasm, webassembly, aspnetcore, minimal apis,
-					docker, containers, kubernetes, compose
+					docker, containers, kubernetes, compose,
+					AI, MCP, model context protocol, AI coding agents, agentic development, copilot, cursor, claude code, vibe coding
 				`
         .replace(/\s*\n\s*/g, ' ')
         .trim(),

src/frontend/config/redirects.mjs

@@ -59,4 +59,5 @@ export const redirects = {
   '/app-host/polyglot-apphost/': '/app-host/typescript-apphost/',
   '/app-host/polyglot-migration/': '/app-host/typescript-apphost-migration/',
   '/app-host/polyglot-troubleshooting/': '/app-host/typescript-apphost-troubleshooting/',
+  '/get-started/configure-mcp/': '/get-started/ai-coding-agents/',
 };

src/frontend/config/sidebar/docs.topics.ts

@@ -405,26 +405,40 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = {
           slug: 'get-started/add-aspire-existing-app',
         },
         {
-          label: 'Configure the MCP server',
+          label: 'Use AI coding agents',
+          collapsed: false,
           translations: {
-            da: 'Konfigurer MCP-serveren',
-            de: 'MCP-Server konfigurieren',
-            en: 'Configure the MCP server',
-            es: 'Configurar el servidor MCP',
-            fr: 'Configurer le serveur MCP',
-            hi: 'MCP सर्वर कॉन्फ़िगर करें',
-            id: 'Konfigurasi server MCP',
-            it: 'Configurare il server MCP',
-            ja: 'MCP サーバーの構成',
-            ko: 'MCP 서버 구성',
-            'pt-BR': 'Configurar o servidor MCP',
-            'pt-PT': 'Configurar o servidor MCP',
-            ru: 'Настройка сервера MCP',
-            tr: 'MCP sunucusunu yapılandırın',
-            uk: 'Налаштування сервера MCP',
-            'zh-CN': '配置 MCP 服务器',
+            da: 'AI-kodningsagenter',
+            de: 'KI-Coding-Agenten',
+            en: 'AI coding agents',
+            es: 'Agentes de codificación con IA',
+            fr: 'Agents de codage IA',
+            hi: 'AI कोडिंग एजेंट',
+            id: 'Agen pengkodean AI',
+            it: 'Agenti di codifica IA',
+            ja: 'AI コーディングエージェント',
+            ko: 'AI 코딩 에이전트',
+            'pt-BR': 'Agentes de codificação com IA',
+            'pt-PT': 'Agentes de codificação com IA',
+            ru: 'ИИ-агенты для кодирования',
+            tr: 'AI kodlama ajanları',
+            uk: 'ШІ-агенти для кодування',
+            'zh-CN': 'AI 编码代理',
           },
-          slug: 'get-started/configure-mcp',
+          items: [
+            {
+              label: 'Overview',
+              slug: 'get-started/ai-coding-agents',
+            },
+            {
+              label: 'Aspire MCP server',
+              slug: 'get-started/aspire-mcp-server',
+            },
+            {
+              label: 'Resource MCP servers',
+              slug: 'get-started/resource-mcp-servers',
+            },
+          ],
         },
         {
           label: 'Troubleshooting',

src/frontend/src/content/docs/dashboard/copilot.mdx

@@ -12,7 +12,7 @@ import structuredLogsExplainError from '@assets/dashboard/copilot/structuredlogs
 import traceDetailsExplainTrace from '@assets/dashboard/copilot/tracedetails-explaintrace.png';
 
 <Aside type="tip" title="New in Aspire 13.1">
-Starting with Aspire 13.1, you can configure the MCP server automatically using the `aspire agent init` command. See [Configure MCP](/get-started/configure-mcp/) for the recommended approach.
+Starting with Aspire 13.1, you can configure the MCP server automatically using the `aspire agent init` command. See [AI coding agents](/get-started/ai-coding-agents/) for the recommended approach.
 </Aside>
 
 Introducing GitHub Copilot in the Aspire dashboard! GitHub Copilot is your new AI debugging assistant.

src/frontend/src/content/docs/dashboard/mcp-server.mdx

@@ -8,7 +8,7 @@ import { Aside, Steps } from '@astrojs/starlight/components';
 import mcpDialogImage from '@assets/dashboard/mcp-server/mcp-dialog.png';
 
 <Aside type="tip" title="New in Aspire 13.1">
-Starting with Aspire 13.1, you can configure the MCP server automatically using the `aspire agent init` command. See [Configure MCP](/get-started/configure-mcp/) for the recommended approach.
+Starting with Aspire 13.1, you can configure the MCP server automatically using the `aspire agent init` command. See [AI coding agents](/get-started/ai-coding-agents/) for the recommended approach.
 </Aside>
 
 This page describes manual MCP configuration for Aspire versions 9.0 through 13.0, or for situations where you need more control over the configuration.

src/frontend/src/content/docs/diagnostics/aspiremcp001.mdx

@@ -79,4 +79,4 @@ Suppress the warning with either of the following methods:
 
 ## See also
 
-- [Configure MCP](/get-started/configure-mcp/) - Learn about Model Context Protocol configuration
+- [AI coding agents](/get-started/ai-coding-agents/) - Learn about Model Context Protocol configuration

src/frontend/src/content/docs/diagnostics/aspirepostgres001.mdx

@@ -84,4 +84,4 @@ Suppress the warning with either of the following methods:
 ## See also
 
 - [PostgreSQL integration](/integrations/databases/postgres/postgres-host/) - Learn about PostgreSQL hosting integration
-- [Configure MCP](/get-started/configure-mcp/) - Learn about Model Context Protocol configuration
+- [AI coding agents](/get-started/ai-coding-agents/) - Learn about Model Context Protocol configuration

src/frontend/src/content/docs/get-started/ai-coding-agents.mdx

@@ -0,0 +1,168 @@
+---
+title: Use AI coding agents
+description: Set up your AI coding agents with skills, MCP servers, and browser automation tailored to Aspire.
+---
+
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+import { Aside, Steps, Tabs, TabItem, FileTree } from '@astrojs/starlight/components';
+import { Image } from 'astro:assets';
+import AsciinemaPlayer from '@components/AsciinemaPlayer.astro';
+import LoopingVideo from '@components/LoopingVideo.astro';
+import LearnMore from '@components/LearnMore.astro';
+
+Aspire provides a first-class setup experience for AI coding agents. Run `aspire agent init` in your project and your AI assistant — whether it's GitHub Copilot, Claude Code, or another MCP-compatible tool — can immediately understand, build, debug, and monitor your distributed applications.
+
+## Why Aspire for coding agents
+
+Aspire gives coding agents the same visibility into your running application that a developer has. The resource data, structured logs, and distributed traces you see in the [Aspire Dashboard](/dashboard/overview/) are exposed to agents through the [Aspire MCP server](/get-started/aspire-mcp-server/) and the [Aspire CLI](/get-started/install-cli). Whether a person is debugging in the dashboard or an agent is diagnosing through MCP, they see the same picture.
+
+The Aspire CLI is built for agent-driven workflows — every command works non-interactively to not block and prompts and supports `--format Json` for structured plain text output. Key commands include `aspire start` (background execution), `aspire start --isolated` (parallel worktrees), `aspire wait` (block until healthy), `aspire describe`, `aspire logs`, and `aspire docs search`.
+
+The Aspire skill file (installed by `aspire agent init`) teaches agents all of these patterns automatically.
+
+## Get started
+
+When you create a new Aspire project with `aspire new` or `aspire init`, you're prompted to configure AI agent environments. You can also run `aspire agent init` at any time to set up or update the configuration.
+
+<Steps>
+
+1. Open a terminal in your Aspire project directory (the folder containing your AppHost).
+
+1. Run the following command:
+
+   ```bash title="Aspire CLI"
+   aspire agent init
+   ```
+
+1. Select the components you want to configure:
+
+   - **Aspire skill file** (recommended) — teaches your AI agent how to use Aspire CLI commands
+   - **Playwright CLI** — enables browser automation for testing web resources
+   - **Aspire MCP server** — gives your AI agent runtime access to resources, logs, and traces
+
+</Steps>
+
+<AsciinemaPlayer 
+  src="/casts/agent-init.cast" 
+  poster="npt:0:08" 
+  autoPlay={true}
+  cols={256}
+  rows={10} />
+
+## What gets configured
+
+The `aspire agent init` command detects your AI development environment and creates the appropriate configuration files:
+
+### Aspire skill file
+
+The skill file teaches your AI coding agent how to work with Aspire. It includes a CLI command reference, key workflows (starting apps, debugging issues, adding integrations), and important rules to follow. The file is created in the format your agent expects:
+
+<FileTree>
+
+- .github/skills/aspire/
+  - SKILL.md  GitHub Copilot
+- .claude/skills/aspire/
+  - SKILL.md  Claude Code
+
+</FileTree>
+
+The skill file guides your agent on how to:
+
+- Start and manage your Aspire application (`aspire start`, `aspire stop`, `aspire describe`)
+- Debug issues using structured logs and distributed traces
+- Add integrations with `aspire add` and search documentation with `aspire docs`
+- Use resource MCP tools for database queries and other resource-specific operations
+
+### Aspire MCP server
+
+The MCP server gives your AI agent direct runtime access to your running Aspire application — resource status, logs, traces, and commands. See [Aspire MCP server](/get-started/aspire-mcp-server/) for configuration details, available tools, and the security model.
+
+## Migrate from AGENTS.md
+
+If your project has an `AGENTS.md` file from a previous version of Aspire, you can migrate to the new skill file format. The skill file provides better structure and is recognized natively by AI coding agents.
+
+<Steps>
+
+1. Run `aspire agent init` and select **Install Aspire skill file**.
+
+2. The skill files are created at `.github/skills/aspire/SKILL.md` and `.claude/skills/aspire/SKILL.md`.
+
+3. Review and delete the old `AGENTS.md` file — the skill file replaces it.
+
+</Steps>
+
+<Aside type="tip">
+The skill file is more structured than `AGENTS.md` and includes a complete CLI command reference table, workflow patterns, and rules that the agent follows automatically. You can customize it for your project's specific needs.
+</Aside>
+
+## Your first prompts
+
+Once configured, start your preferred AI coding environment. Try asking your agent:
+
+> "Start the Aspire app and show me the resource status."
+
+> "Analyze HTTP request performance for my API."
+
+> "Add a Redis cache to my AppHost."
+
+<Tabs>
+  <TabItem label="VS Code" id="demo-vscode">
+    <LoopingVideo
+      aria-label="VS Code with GitHub Copilot using Aspire MCP to list resources"
+      controls={true}
+      sources={[
+        {
+          src: "/mcp-vscode-list-resources.mp4",
+          type: "video/mp4",
+          title: "VS Code demonstrating Aspire MCP integration with GitHub Copilot"
+        }
+      ]}
+    />
+  </TabItem>
+  <TabItem label="Claude Code" id="demo-claude">
+    <AsciinemaPlayer 
+      src="/casts/mcp-claudecode-cli.cast"
+      poster="npt:0:27"
+      autoPlay={true}
+      cols={256}
+      rows={28} />
+  </TabItem>
+  <TabItem label="Copilot CLI" id="demo-copilot">
+    <AsciinemaPlayer 
+      src="/casts/mcp-copilot-cli.cast"
+      poster="npt:0:22"
+      autoPlay={true}
+      cols={256}
+      rows={28} />
+  </TabItem>
+  <TabItem label="OpenCode" id="demo-opencode">
+    <AsciinemaPlayer 
+      src="/casts/mcp-opencode-cli.cast"
+      poster="npt:0:14"
+      autoPlay={true}
+      cols={256}
+      rows={28} />
+  </TabItem>
+</Tabs>
+
+## Supported AI assistants
+
+The `aspire agent init` command supports the following AI assistants:
+
+- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) with GitHub Copilot
+- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)
+- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
+- [OpenCode](https://opencode.ai/docs/mcp-servers/)
+
+<Aside type="note">
+The Aspire MCP server uses the STDIO transport protocol and may work with other agentic coding environments that support this MCP communication protocol.
+</Aside>
+
+## See also
+
+- [Aspire MCP server](/get-started/aspire-mcp-server/) — tools, security, and troubleshooting for the MCP server
+- [aspire agent command](/reference/cli/commands/aspire-agent/)
+- [aspire agent init command](/reference/cli/commands/aspire-agent-init/)
+- [aspire agent mcp command](/reference/cli/commands/aspire-agent-mcp/)
+- [Dashboard security considerations](/dashboard/security-considerations/)
+- [GitHub Copilot in the Dashboard](/dashboard/copilot/)