[docs] Remove misleading WithTerminal Shell option

[aspire-repo-bot]

Documents changes from microsoft/aspire#18991

@mitchdenny

Targeting release/13.5 based on the source PR milestone 13.5.

Why

microsoft/aspire#18991 removed the experimental TerminalOptions.Shell property because it was a no-op: DCP always runs the resource's own process (or the container's process) as the terminal program, and the Shell value was never wired into the underlying pseudo-terminal. The docs previously documented Shell as a real, working option in the configuration table, which is now inaccurate and misleading.

What changed

• src/frontend/src/content/docs/app-host/with-terminal.mdx: removed the Shell row from the options table and replaced it with a note explaining that the resource's own process is always the terminal program and that shell selection is not supported (with a brief mention that the removed Shell option never had any effect).

No new pages were created; this is a targeted update to the existing WithTerminal guide.

Generated by PR Documentation Check · auto · 38.4 AIC · ⌖ 7.49 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1478. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

Updates the Aspire App Host documentation for WithTerminal to remove a misleading option that no longer exists (and never had functional effect), aligning the docs with the upstream change in microsoft/aspire#18991.

Changes:

• Removed the TerminalOptions.Shell entry from the WithTerminal options table.
• Added a note clarifying that the resource’s own process is always the terminal program and that selecting an alternate shell isn’t supported.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Adam Ratzman (adamint)]

I checked the removed Shell option and mixed-version parser behavior against the CLI implementation. This looks good.

[David Pine (IEvangelist)]

Docs accuracy review — automated (Phase A + Phase B)

Verdict: COMMENT — the change is accurate. The notes below are for transparency; nothing here is blocking.

• Phase A source of truth: microsoft/aspire release/13.5 @ 8ab6999850d96e0023670799edbd4bdc245ad63c
• Claims extracted: 4 — ✅ verified: 2, 🟡 verified-with-nuance: 2, ⚪ unverifiable: 0, ❌ contradicted: 0
• Phase B (doc-tester): exercised /app-host/with-terminal/ — 0 critical, 0 warnings; page renders cleanly (HTTP 200, 0 console errors).

This PR removes the Shell row from the terminal-options table and adds an <Aside> clarifying that no shell can be selected for the session. Both changes match the source of truth.

Phase A — Claim verification

There are no contradicted or unverifiable claims, so there are no blocking inline comments. Evidence for every claim is below.

Verified & verified-with-nuance claims (4)

ID	PR location	Claim	Verdict	Evidence (microsoft/aspire @ 8ab6999850)
A1	table, removed Shell row (old L77)	Shell is not a member of the terminal options	✅ verified	src/Aspire.Hosting/ApplicationModel/TerminalAnnotation.cs — TerminalOptions exposes only Columns, Rows, ShowTerminalHost. A \bShell\b search returns no property anywhere in src/Aspire.Hosting. Removing the row is correct.
A2	table rows (context)	Defaults are Columns=120, Rows=30, ShowTerminalHost=false	✅ verified	TerminalAnnotation.cs — Columns default 120, Rows default 30, ShowTerminalHost (bool) default false.
A3	Aside (new L79–81)	The earlier Shell option "was never wired up to the underlying pseudo-terminal and had no effect"	🟡 verified-with-nuance	Shell is entirely absent from TerminalOptions and unreferenced across src/Aspire.Hosting on this branch — fully consistent with "removed / no effect." Nuance: the causal history ("never wired up") cannot be positively proven from the current tree; only the property's total absence is observable.
A4	Aside (new L80)	"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."	🟡 verified-with-nuance	TerminalResourceBuilderExtensions.WithTerminal remarks: "DCP allocates a pseudo-terminal (PTY) per replica and a hidden terminal host process bridges the PTY traffic." A hidden TerminalHostResource bridges the PTY to the parent resource; there is no shell-selection or /bin/sh spawning anywhere. Nuance: the "container's own process" phrasing is an accurate author characterization of the PTY-bridge design rather than a verbatim source string.

Phase B — Doc-tester results (blind user, no source access)

Routes exercised: /app-host/with-terminal/ (the only route affected by this PR's diff).

Critical issues: none.

Warnings: none.

Passed checks:

• Page compiles and renders (HTTP 200) with 0 console errors / 0 warnings.
• The "Configure the terminal" options table lists exactly Columns (120), Rows (30), and ShowTerminalHost (false) — the Shell row is gone, matching the diff.
• The new note renders as a standard Starlight <Aside type="note"> and reads clearly. The word "Shell" now appears only inside that aside (1 occurrence on the page), confirming the table row was removed.

Recommendations: none.

Knowledge gaps (blind-user perspective):

• The aside states behavior as fact ("for containers it's the container's own process … never wired up … had no effect") that a reader cannot validate from the page alone. Phase A independently confirmed it is accurate, so no change is needed.

Test-environment note: the with-terminal page is new on release/13.5 and is not yet present on this review worktree's base branch, so its sidebar-topic registration was added locally only to render the page. That scaffolding was reverted afterward and is not part of the PR; it did not alter the page body under test.