Ensure the use of polyglot is consistent

src/frontend/src/content/docs/app-host/executable-resources.mdx

@@ -276,7 +276,7 @@ const app = await builder.addExecutable("api", "uvicorn", ".", ["main:app", "--r
 
 ### `withEnvironment` API unification in Aspire 13.3
 
-Aspire 13.3 unified polyglot AppHost environment assignment behind a single `withEnvironment(name, value)` pattern. The public TypeScript API accepts plain strings, reference expressions, endpoint references, parameter resources, supported resources that expose connection strings, expression values, and awaitable forms of supported values.
+Aspire 13.3 unified non-C# AppHost environment assignment behind a single `withEnvironment(name, value)` pattern. The public TypeScript API accepts plain strings, reference expressions, endpoint references, parameter resources, supported resources that expose connection strings, expression values, and awaitable forms of supported values.
 
 When upgrading to Aspire 13.3, replace every earlier per-kind environment helper call with `withEnvironment(name, value)`. The 13.3 TypeScript SDK doesn't generate compatibility aliases for those helpers.
 

src/frontend/src/content/docs/app-host/with-terminal.mdx

@@ -74,16 +74,9 @@ The terminal session is described by a set of options with sensible defaults:
 | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Columns`           | `120`   | The initial number of columns for the terminal grid.                                                                                                            |
 | `Rows`              | `30`    | The initial number of rows for the terminal grid.                                                                                                               |
+| `Shell`             | `null`  | The shell to launch for the session. When `null`, the default is used: for containers this is typically `/bin/sh`; for executables the process itself is the terminal program. |
 | `ShowTerminalHost`  | `false` | Whether the hidden per-replica terminal host resources appear in the dashboard and CLI resource lists. Set to `true` to diagnose terminal-host startup or connectivity issues. |
 
-<Aside type="tip">
-`Columns` and `Rows` must each be `1` or greater. Configuring either with zero or a negative value in the `WithTerminal(...)` callback throws an `ArgumentOutOfRangeException` immediately instead of failing later during terminal-host startup.
-</Aside>
-
-<Aside type="note">
-The resource being run is always the terminal program: for executables that's the process itself, and for containers it's the container's own process. There's no way to select a different shell to launch for the session—an earlier `Shell` option that appeared to do this was removed because it was never wired up to the underlying pseudo-terminal and had no effect.
-</Aside>
-
 <Tabs syncKey='aspire-lang'>
 <TabItem id='csharp' label='C#'>
 
@@ -118,7 +111,7 @@ await builder.build().run();
 ```
 
 <Aside type="note">
-In TypeScript AppHosts, `withTerminal()` currently applies the default options shown above. Configurable options are coming to the polyglot API as `WithTerminal` is finalized (tracked by [microsoft/aspire#18105](https://github.com/microsoft/aspire/issues/18105)).
+In TypeScript AppHosts, `withTerminal()` currently applies the default options shown above. Configurable options are coming to the non-C# API as `WithTerminal` is finalized (tracked by [microsoft/aspire#18105](https://github.com/microsoft/aspire/issues/18105)).
 </Aside>
 
 </TabItem>

src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

@@ -119,7 +119,7 @@ XML doc comments are the primary source for generated SDK API documentation. The
 
 Use `ats-*` override tags when the standard C# XML documentation doesn't translate well to generated SDK docs — for example, when a `<summary>` references C#-specific types or language constructs that have no direct equivalent in TypeScript. The supported overrides are:
 
-- `<ats-summary>` — overrides `<summary>` in polyglot docs
+- `<ats-summary>` — overrides `<summary>` in [polyglot](/get-started/glossary/#polyglot) docs
 - `<ats-param name="...">` — overrides `<param>` for a specific parameter
 - `<ats-returns>` — overrides `<returns>`
 - `<ats-remarks>` — overrides `<remarks>`

src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx

@@ -96,7 +96,7 @@ The AppHost is the orchestration layer. Your choice here changes how you express
 
 Aspire offers two C# AppHost styles:
 
-**File-based AppHost** — a single `apphost.cs` file that uses `#:sdk` and `#:package` directives. No `.csproj`, no solution integration required. Best for polyglot repos or quick setups.
+**File-based AppHost** — a single `apphost.cs` file that uses `#:sdk` and `#:package` directives. No `.csproj`, no solution integration required. Best for repos with [polyglot](/get-started/glossary/#polyglot) code or quick setups.
 
 **Project-based AppHost** — a traditional `AppHost.csproj` that lives inside a `.sln` alongside your other C# projects. Uses `ProjectReference` items and the generated `Projects` namespace for strongly-typed `AddProject<T>()` calls. Best when your repo is already a .NET solution and you want IDE-integrated orchestration.
 

src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx

@@ -14,7 +14,7 @@ import debugSessions from '@assets/get-started/code-extension-debug.png';
 import debugSessionsLight from '@assets/get-started/code-extension-debug-light.png';
 import { Kbd } from 'starlight-kbd/components';
 
-The official Aspire extension for [Visual Studio Code](https://code.visualstudio.com/) turns VS Code into a first-class environment for building, debugging, and shipping polyglot Aspire apps.
+The official Aspire extension for [Visual Studio Code](https://code.visualstudio.com/) turns VS Code into a first-class environment for building, debugging, and shipping [polyglot](/get-started/glossary/#polyglot) Aspire apps.
 Press <Kbd windows='F5' /> to build your AppHost, start your resources, and debug supported resource types — C#, TypeScript, Python, browser apps, and Azure Functions — alongside the Aspire dashboard.
 
 :::note[Prerequisites]

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

@@ -10,7 +10,7 @@ This page answers common questions about what Aspire is, how it fits into your w
 
 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.
+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 teams that use [polyglot](/get-started/glossary/#polyglot) code.
 
 Learn more: [Build your first Aspire app](/get-started/first-app/)
 

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

@@ -4,6 +4,8 @@ description: Key terms and concepts used throughout Aspire documentation — App
 ---
 
 import { Aside } from '@astrojs/starlight/components';
+import PivotSelector from '@components/PivotSelector.astro';
+import Pivot from '@components/Pivot.astro';
 
 This glossary defines the key terms and concepts you'll encounter when working with Aspire. Bookmark this page as a quick reference.
 
@@ -13,16 +15,27 @@ These are the foundational concepts you need to understand when working with Asp
 
 ### AppHost
 
-The **AppHost** is the orchestration project where you define your entire application's architecture in C# code. It's a special Aspire project that:
+The **AppHost** is the orchestration project where you define your entire application's architecture. It's a special Aspire project that:
 
-- Declares what services, databases, and containers make up your application
-- Defines how resources depend on each other
-- Configures how resources communicate
-- Orchestrates startup order during local development
-- Generates deployment artifacts for production
+- Declares what services, databases, and containers make up your application.
+- Defines how resources depend on each other.
+- Configures how resources communicate.
+- Orchestrates startup order during local development.
+- Generates deployment artifacts for production.
 
 Think of it as the "control tower" for your distributed application.
 
+<PivotSelector
+  title="Select your programming language"
+  key="aspire-lang"
+  marginTop={1}
+  options={[
+    { id: 'csharp', title: 'C#' },
+    { id: 'typescript', title: 'TypeScript' },
+  ]}
+/>
+
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 // This IS the AppHost - Program.cs in your AppHost project
 var builder = DistributedApplication.CreateBuilder(args);
@@ -33,6 +46,21 @@ var api = builder.AddProject<Projects.Api>("api")
 
 builder.Build().Run();
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+// This IS the AppHost in a TypeScript project
+const builder = await createBuilder();
+
+const db = await builder.addPostgres("db");
+await builder.addProject("api", "../Api/Api.csproj")
+    .withReference(db);
+
+await builder.build().run();
+```
+</Pivot>
 
 ### Resource
 
@@ -72,6 +100,10 @@ Aspire helps you orchestrate all these pieces together.
 
 When you add `builder.AddServiceDefaults()` to a project, you get production-ready observability and resilience out of the box.
 
+### Polyglot
+
+In this repository, **polyglot** means relating to code and applications written in multiple languages, including TypeScript, C#, Python, Go, Java, and Rust. Aspire supports polyglot code in AppHosts, generated SDKs, others projects, and related tooling.
+
 ---
 
 ## APIs and patterns
@@ -86,50 +118,87 @@ These are the key APIs and patterns you'll use when building Aspire applications
 2. Sets up service discovery so your code can find the other resource
 3. Creates a dependency relationship for startup ordering
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var db = builder.AddPostgres("db");
 var api = builder.AddProject<Projects.Api>("api")
     .WithReference(db);  // API now has DATABASE connection info injected
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const db = await builder.addPostgres("db");
+await builder.addProject("api", "../Api/Api.csproj")
+    .withReference(db);  // API now has DATABASE connection info injected
+```
+</Pivot>
 
 The API project will receive environment variables like:
 - `ConnectionStrings__db` - The database connection string
 - Service discovery configuration for the "db" resource
 
 ### WaitFor
 
-`WaitFor()` tells Aspire to delay starting a resource until its dependency is ready:
+`WaitFor()`/`waitFor()` tells Aspire to delay starting a resource until its dependency is ready:
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var db = builder.AddPostgres("db");
 var api = builder.AddProject<Projects.Api>("api")
     .WithReference(db)
     .WaitFor(db);  // Don't start API until database is healthy
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const db = await builder.addPostgres("db");
+await builder.addProject("api", "../Api/Api.csproj")
+    .withReference(db)
+    .waitFor(db);  // Don't start API until database is healthy
+```
+</Pivot>
 
 <Aside type="tip">
-  Without `WaitFor()`, your API might start and immediately crash because the database isn't ready yet. This prevents race conditions during startup.
+  Without `WaitFor()`/`waitFor()`, your API might start and immediately crash because the database isn't ready yet. This prevents race conditions during startup.
 </Aside>
 
 ### WaitForCompletion
 
 `WaitForCompletion()` waits for a resource to finish and exit (not just start). Useful for setup scripts:
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var migrate = builder.AddProject<Projects.DbMigration>("migrate");
 var api = builder.AddProject<Projects.Api>("api")
     .WaitForCompletion(migrate);  // Wait for migrations to complete
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const migrate = await builder.addProject("migrate", "../DbMigration/DbMigration.csproj");
+await builder.addProject("api", "../Api/Api.csproj")
+    .waitForCompletion(migrate);  // Wait for migrations to complete
+```
+</Pivot>
 
 ### WaitForStart
 
 `WaitForStart()` waits only for a resource to reach the running state, without waiting for health checks to pass:
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var db = builder.AddPostgres("db");
 var api = builder.AddProject<Projects.Api>("api")
     .WaitForStart(db);  // Start as soon as db is running, don't wait for healthy
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const db = await builder.addPostgres("db");
+await builder.addProject("api", "../Api/Api.csproj")
+    .waitForStart(db);  // Start as soon as db is running, don't wait for healthy
+```
+</Pivot>
 
 <Aside type="tip">
   Use `WaitForStart()` when you need looser coupling—your service can handle initial connection failures via retry policies. Use `WaitFor()` when you need strict dependency on health.
@@ -287,20 +356,35 @@ These patterns appear frequently in Aspire applications.
 
 Many hosting integrations support running as an **emulator** for local development:
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var storage = builder.AddAzureStorage("storage")
     .RunAsEmulator();  // Uses Azurite container locally
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const storage = await builder.addAzureStorage("storage");
+await storage.runAsEmulator();  // Uses Azurite container locally
+```
+</Pivot>
 
 This lets you develop against Azure, AWS, or other cloud services without needing actual cloud accounts during development.
 
 ### Existing resource pattern
 
 Connect to resources that already exist (not managed by Aspire):
 
+<Pivot id="csharp">
 ```csharp title="AppHost.cs"
 var existingDb = builder.AddConnectionString("db");
 ```
+</Pivot>
+<Pivot id="typescript">
+```typescript title="apphost.mts"
+const existingDb = await builder.addConnectionString("db");
+```
+</Pivot>
 
 Aspire resolves this from `ConnectionStrings:db` (or environment variable `ConnectionStrings__db`) in the AppHost configuration and passes it through as a single connection string value.
 
@@ -334,4 +418,3 @@ These terms appear frequently in API documentation and advanced usage:
 
 - [What is Aspire?](/get-started/what-is-aspire/)
 - [Create your first Aspire app](/get-started/first-app/)
-- [AppHost overview](/get-started/app-host/)

src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx

@@ -464,36 +464,6 @@ In publish mode, Aspire creates an `AzureHostedAgentResource` and publishes the
 
 For C# AppHosts, the parameterless `AsHostedAgent()` overload reuses an existing Foundry project from the app model or creates one automatically. TypeScript AppHosts pass the project resource explicitly.
 
-### Select a hosted agent protocol
-
-`AsHostedAgent` defaults to the Responses protocol version `2.0.0`. If your hosted agent implements a different protocol or protocol version, use the C# `AsHostedAgent(project, protocol, version)` overload or the polyglot/TypeScript `asHostedAgentWithProtocol` export. For example, some Microsoft Agent Framework (MAF) agents use the Invocations protocol:
-
-<Tabs syncKey='aspire-lang'>
-<TabItem id='csharp' label='C#'>
-
-```csharp
-builder.AddPythonApp("agent-python", "../agent", "main:app")
-    .WithReference(project)
-    .WithReference(chat)
-    .AsHostedAgent(project, HostedAgentProtocol.Invocations, "1.0.0");
-```
-
-</TabItem>
-<TabItem id='typescript' label='TypeScript'>
-
-```typescript
-await builder
-  .addPythonApp('agent-python', '../agent', 'main:app')
-  .withReference(project)
-  .withReference(chat)
-  .asHostedAgentWithProtocol(project, HostedAgentProtocol.Invocations, '1.0.0');
-```
-
-</TabItem>
-</Tabs>
-
-The defaulted `asHostedAgent` entry point and the explicit `asHostedAgentWithProtocol` entry point are both exported to polyglot AppHosts, so existing AppHosts that call `asHostedAgent(project, options?)` continue to work unchanged with the Responses `2.0.0` default. Reach for `asHostedAgentWithProtocol` only when you need a protocol or version other than the default.
-
 ### Add and publish a prompt agent
 
 For prompt-only scenarios, use `AddPromptAgent` on a Foundry project:
@@ -861,7 +831,7 @@ builder.AddFoundry("foundry")
   TypeScript AppHosts can use curated provisioning helper APIs when an
   integration exposes them. This example directly customizes Azure.Provisioning
   objects through `ConfigureInfrastructure`, which is currently C#-only unless
-  the integration wraps the scenario in a polyglot-friendly helper.
+  the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper.
 </Aside>
 
 The preceding code:

src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx

@@ -232,7 +232,7 @@ var appInsights = builder.AddAzureApplicationInsights("app-insights", logAnalyti
   TypeScript AppHosts can use curated provisioning helper APIs when an
   integration exposes them. This example directly customizes Azure.Provisioning
   objects through `ConfigureInfrastructure`, which is currently C#-only unless
-  the integration wraps the scenario in a polyglot-friendly helper.
+  the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper.
 </Aside>
 
 The preceding code:

src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx

@@ -483,7 +483,7 @@ builder.Build().Run();
   TypeScript AppHosts can use curated provisioning helper APIs when an
   integration exposes them. This example directly customizes Azure.Provisioning
   objects through `ConfigureInfrastructure`, which is currently C#-only unless
-  the integration wraps the scenario in a polyglot-friendly helper.
+  the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper.
 </Aside>
 
 The preceding code:

src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx

@@ -340,7 +340,7 @@ builder.Build().Run();
   TypeScript AppHosts can use curated provisioning helper APIs when an
   integration exposes them. This example directly customizes Azure.Provisioning
   objects through `ConfigureInfrastructure`, which is currently C#-only unless
-  the integration wraps the scenario in a polyglot-friendly helper.
+  the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper.
 </Aside>
 
 The preceding code:

src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx

@@ -446,7 +446,7 @@ storage.ConfigureInfrastructure(infra =>
   TypeScript AppHosts can use curated provisioning helper APIs when an
   integration exposes them. This example directly customizes Azure.Provisioning
   objects through `ConfigureInfrastructure`, which is currently C#-only unless
-  the integration wraps the scenario in a polyglot-friendly helper.
+  the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper.
 </Aside>
 
 #### Service-specific requirements

src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx

@@ -353,7 +353,7 @@ builder.Build().Run();
 </Aside>
 
 <Aside type="note">
-  The `RavenDBServerSettings`-based overload of `AddRavenDB` is only available from C# AppHosts. It includes certificate and licensing configuration that is not compatible with the polyglot TypeScript AppHost.
+  The `RavenDBServerSettings`-based overload of `AddRavenDB` is only available from C# AppHosts. It includes certificate and licensing configuration that is not compatible with the non-C# TypeScript AppHost.
 </Aside>
 
 ## Connection properties

src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx

@@ -323,7 +323,7 @@ await builder.build().run();
 </TabItem>
 </Tabs>
 
-The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The polyglot TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`).
+The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The non-C# TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`).
 
 ## Health checks