Add FAQ page and homepage FAQ link

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

@@ -402,6 +402,10 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = {
           label: 'Troubleshooting',
           slug: 'get-started/troubleshooting',
         },
+        {
+          label: 'FAQ',
+          slug: 'get-started/faq',
+        },
       ],
     },
     {

src/frontend/src/content/docs/get-started/faq.mdx

@@ -0,0 +1,185 @@
+---
+title: Frequently asked questions (FAQ)
+description: Answers to common questions about Aspire, including the AppHost, dashboard, integrations, TypeScript support, deployment, and how Aspire compares to other tools.
+---
+
+This page answers common questions about what Aspire is, how it fits into your workflow, what it can do for you, and how it compares to other technologies.
+
+### What is Aspire?
+
+Aspire is an agent-ready, code-first tool to compose, debug, and deploy any distributed app. It makes it easier to build, run, debug, and deploy services across any language, stack, or cloud. It's free and open source at [github.com/microsoft/aspire](https://github.com/microsoft/aspire).
+
+Its central idea is the **AppHost**: the place where you declare your services, resources, dependencies, endpoints, parameters, and relationships in code instead of scattering that information across many config files. AppHosts can be written in **C# or TypeScript**, which makes Aspire a strong fit for polyglot teams.
+
+Learn more: [Build your first Aspire app](/get-started/first-app/)
+
+### What problem does Aspire solve?
+
+Aspire makes multi-service development easier to understand and operate. It reduces the friction of working on connected services. It gives teams one place to model the app, start related services together, wire dependencies, inspect telemetry, and reduce configuration drift across development and deployment workflows.
+
+### What is the AppHost, and why is it so important?
+
+The AppHost is Aspire's control center. It's a map for all of the pieces of your distributed app and the **single source of truth** for your app's architecture: projects, containers, databases, endpoints, volumes, parameters, and the relationships between them. The same AppHost model is used across inner-loop development, deployment, and CI/CD workflows.
+
+Learn more: [What is the AppHost?](/get-started/app-host/)
+
+### What does Aspire actually give me out of the box?
+
+Aspire brings together four especially useful capabilities:
+
+1. **Code-first orchestration** for your app's resources and relationships.
+2. **A dashboard** for logs, metrics, traces, and resource health.
+3. **Opinionated defaults** through integrations that handle service discovery, health checks, telemetry, and resilient communication.
+4. **A lifecycle-friendly, agent-friendly CLI** for creating, running, publishing, deploying, inspecting, and troubleshooting apps.
+
+Every part of the lifecycle can be inspected and automated by humans or agents.
+
+Learn more: [Aspire dashboard overview](/dashboard/overview/), [CLI overview](/reference/cli/overview/), [Integrations gallery](/integrations/gallery/)
+
+### What kinds of integrations does Aspire provide?
+
+Aspire provides integrations for many of the building blocks that show up in real systems: databases, caches, messaging systems, storage services, observability backends, and cloud resources. These integrations help you model resources in the AppHost, connect services with references, and inject the right configuration such as connection strings, URLs, and environment variables automatically.
+
+Learn more: [Integrations gallery](/integrations/gallery/), [`aspire add`](/reference/cli/commands/aspire-add/)
+
+### How do Aspire integrations fit with existing apps?
+
+Integrations are additive. You can introduce them one by one as your system needs them, whether your app is new or already running in production. A common pattern is to model a shared resource such as PostgreSQL, Redis, or a message broker in the AppHost and then reference it from the services that need it.
+
+Learn more: [Integrations gallery](/integrations/gallery/), [`aspire init`](/reference/cli/commands/aspire-init/)
+
+### What is the Aspire dashboard?
+
+The dashboard is the most visible part of the developer experience, but it is not the whole story. When you run an Aspire app, the dashboard provides real-time visibility into resources, logs, metrics, traces, configuration, and health so you can understand how the system is behaving.
+
+Learn more: [Aspire dashboard overview](/dashboard/overview/)
+
+### Do I have to rewrite my app to use Aspire?
+
+**No.** Aspire is designed to complement the technologies you already use rather than requiring a rewrite into one framework or one cloud. It can orchestrate apps across many languages like C#, Python, JavaScript, Node.js, Go, and Java, and it supports a TypeScript or C# AppHost. For deployment, it works through configured targets and integrations instead of requiring one proprietary hosting model.
+
+Learn more: [What is the AppHost?](/get-started/app-host/), [Deployment overview](/deployment/overview/#compute-environments)
+
+### Is Aspire only for .NET apps?
+
+**No.** .NET is an especially strong experience in Aspire, but the app model is broader than one framework or runtime. Aspire is designed to coordinate services across multiple stacks, and the TypeScript AppHost makes it a natural fit for existing JavaScript and TypeScript applications as well.
+
+Learn more: [TypeScript AppHost support](/whats-new/aspire-13-2/#-typescript-apphost-support-preview)
+
+### Can I write the AppHost in TypeScript?
+
+**Yes.** A TypeScript AppHost (`apphost.ts`) is a first-class option for existing JavaScript and TypeScript applications. That experience uses commands such as `aspire init --language typescript` and AppHost APIs such as `addNodeApp`, `addViteApp`, and `addJavaScriptApp`.
+
+Learn more: [`aspire init`](/reference/cli/commands/aspire-init/), [TypeScript AppHost support](/whats-new/aspire-13-2/#-typescript-apphost-support-preview)
+
+### Is Aspire only for brand-new projects?
+
+**No.** Aspire can be adopted incrementally. You can add an AppHost to an existing codebase, register the resources you already have, and bring the system under Aspire orchestration step by step without rewriting everything at once.
+
+Learn more: [`aspire init`](/reference/cli/commands/aspire-init/)
+
+### How is Aspire different from Docker Compose?
+
+The simplest confident answer is: **Docker Compose is container-first YAML; Aspire is app-model-first code.** Compose focuses on describing containers and their runtime settings. Aspire focuses on describing the whole distributed application and its relationships, then layering in orchestration, service discovery, integrations, telemetry, and dashboard-driven insight.
+
+That said, Docker is one of the many computing environments Aspire supports and can publish Docker Compose artifacts.
+
+Learn more: [Docker integration](/integrations/compute/docker/), [Aspire app lifecycle guide](/deployment/app-lifecycle/)
+
+### What does "agent-ready" mean?
+
+Aspire is designed to work with AI agents and copilots as naturally as it works with human developers. Its CLI is interactive and machine-readable, and its built-in MCP (Model Context Protocol) server exposes app resources, logs, traces, and documentation to AI agents. Because the AppHost is a code-first, structured model — not scattered YAML or config files — agents can read your app topology, diagnose issues from traces, and modify your architecture programmatically. The `aspire agent` command manages AI agent environment configuration.
+
+Learn more: [MCP tools](/reference/cli/commands/aspire-mcp/), [`aspire agent`](/reference/cli/commands/aspire-agent/)
+
+### What languages and stacks does Aspire support?
+
+Aspire is a multi-language platform. The AppHost can be written in **C# or TypeScript**. Services can be written in any language:
+
+- **C# / .NET** — First-class project references, service defaults, and integrations
+- **Python** — `AddPythonApp`, `AddUvicornApp`, `AddPythonModule` with uv/pip/venv package management and automatic Dockerfile generation
+- **JavaScript / TypeScript** — `AddJavaScriptApp`, `AddViteApp`, `AddNodeApp` with npm/yarn/pnpm auto-detection
+- **Go, Java, Rust** — Via community toolkit integrations and code generation packages
+- **Any containerized app** — Anything that runs in a container can be added to the AppHost
+
+Database resources automatically expose connection strings in multiple formats (URI, JDBC, individual properties) so any language can connect without custom wiring.
+
+Learn more: [Integrations gallery](/integrations/gallery/)
+
+### How does Aspire compare to Pulumi, Terraform, or Bicep?
+
+These tools are best thought of as **complements**, not competitors:
+
+- **Pulumi / Terraform / Bicep** focus on provisioning and managing infrastructure resources and cloud environments.
+- **Aspire** focuses on modeling the application itself: its services, dependencies, orchestration, discovery, telemetry, and developer workflow.
+
+A good practical framing is: use Aspire to build, run, debug, and deploy the **application topology**, while IaC tools provision **environment and platform resources**.
+
+Learn more: [Aspire app lifecycle guide](/deployment/app-lifecycle/)
+
+### How does Aspire compare to Kubernetes?
+
+Kubernetes is a production orchestration platform. Aspire is an application model and developer workflow that helps you describe, connect, and observe your services. Aspire is not a one-for-one Kubernetes replacement; it is an application composition experience that can feed real deployment targets, like Kubernetes.
+
+Learn more: [Deployment overview](/deployment/overview/#compute-environments)
+
+### How does Aspire compare to Dapr or other service-runtime frameworks?
+
+Dapr provides runtime building blocks such as pub/sub, bindings, state, and service invocation. Aspire focuses on application composition, orchestration, integration wiring, and observability. They address different layers of the problem and can be used together when that combination makes sense.
+
+Learn more: [Dapr integration](/integrations/frameworks/dapr/)
+
+### Does Aspire replace Docker Compose, Kubernetes, or my deployment platform?
+
+**No.** Aspire helps you model, run, observe, publish, and deploy distributed apps, but you still choose the actual compute environments and deployment targets that fit your platform strategy.
+
+Learn more: [Deployment overview](/deployment/overview/#compute-environments), [`aspire deploy`](/reference/cli/commands/aspire-deploy/)
+
+### How does Aspire fit into the development-to-production lifecycle?
+
+Aspire supports a consistent lifecycle:
+
+1. **`aspire run`** for inner-loop development and debugging.
+2. **`aspire deploy`** for deployment to configured compute environments.
+3. **`aspire publish`** and related CI/CD steps for release artifacts and deployment workflows.
+
+The key idea is that the same AppHost configuration flows across these stages.
+
+Learn more: [Aspire app lifecycle guide](/deployment/app-lifecycle/), [`aspire run`](/reference/cli/commands/aspire-run/), [`aspire deploy`](/reference/cli/commands/aspire-deploy/), [`aspire publish`](/reference/cli/commands/aspire-publish/)
+
+### What commands matter most when introducing Aspire?
+
+If you want the shortest useful list, start with these:
+
+- `aspire new` — create a new Aspire app
+- `aspire init` — initialize Aspire in an existing codebase
+- `aspire init --language typescript` — create a TypeScript AppHost for JS/TS apps
+- `aspire add` — add hosting integrations
+- `aspire run` — run the AppHost for development
+- `aspire deploy` — deploy to configured targets
+- `aspire publish` — generate deployment artifacts
+- `aspire logs`, `aspire docs`, and `aspire doctor` — inspect, learn, and troubleshoot
+
+Learn more: [CLI overview](/reference/cli/overview/), [`aspire init`](/reference/cli/commands/aspire-init/), [`aspire run`](/reference/cli/commands/aspire-run/)
+
+### Is the deployment manifest still recommended?
+
+**No.** The deployment manifest is deprecated. The current path is to use `aspire publish` and `aspire deploy` with supported deployment targets and workflows.
+
+Learn more: [`aspire publish`](/reference/cli/commands/aspire-publish/), [`aspire deploy`](/reference/cli/commands/aspire-deploy/)
+
+### How should I talk about Aspire confidently without overclaiming?
+
+Prefer language like this:
+
+- "Aspire is an agent-ready, code-first tool to compose, debug, and deploy any distributed app."
+- "One app model from dev to deploy reduces configuration drift between environments."
+- "Built-in observability with zero setup — logs, traces, metrics, and health checks out of the box."
+- "Any language, any stack — define them in the AppHost and Aspire wires them together."
+- "Aspire works with your existing tools and clouds, not instead of them."
+
+Avoid vague hype or incorrect claims like:
+
+- "Aspire replaces everything in your platform."
+- "Aspire is only a dashboard."
+- "Aspire only works for brand-new .NET apps."

src/frontend/src/content/docs/index.mdx

@@ -211,4 +211,10 @@ Get started with Aspire by installing the CLI, then dive into the Docs to learn
     title="Explore docs"
     description="Learn how to model, run, and deploy apps with Aspire."
   />
+  <LinkCard
+    icon="open-book"
+    href="/get-started/faq/"
+    title="FAQ"
+    description="Find answers to frequently asked questions"
+  />
 </CardGrid>