🤓 Content for release: 13.5

.agents/skills/doc-pr-reviewer/SKILL.md

@@ -80,6 +80,40 @@ For each non-`narrative` claim:
    - `contradicted` — the source code says something different than the PR claims; include both texts
 4. Do not infer from documentation, blog posts, or other branches. The branch you actually checked out and recorded for that repo (per the **Source of truth** section — the PR's matching branch, or the documented fallback when none matches) is the only source of truth.
 
+## Current-version placeholder review
+
+When a docs PR adds or edits Aspire version strings, check whether the version
+is intended to represent the current release or an intentionally fixed version.
+The docs site provides placeholders for current-version values:
+
+| Placeholder | Use for |
+|-------------|---------|
+| `%ASPIRE_VERSION%` | Full current Aspire version, including patch (for example, `13.5.0`) |
+| `%ASPIRE_VERSION_MAJOR_MINOR%` | Current Aspire major/minor display version (for example, `13.5`) |
+
+Flag hard-coded Aspire versions as a review finding when they appear in current
+copy/paste guidance that should track the active release, including:
+
+- `Aspire.AppHost.Sdk` declarations in project files or file-based apps.
+- `#:package Aspire.*@...` file-based app package directives.
+- Aspire CLI or AppHost sample output that reports the current CLI/AppHost
+  version.
+- Getting started, installation, or "use this today" examples that should move
+  with the release branch.
+
+Do **not** require placeholders for intentionally fixed versions, including:
+
+- What's-new or release-note pages that describe a specific historical release.
+- Upgrade examples that deliberately compare old and new versions.
+- CLI examples where the point is pinning a specific version with `--version`,
+  `-Version`, or `Aspire.ProjectTemplates::...`.
+- Versioned schema URLs, package compatibility notes, minimum-version
+  requirements, third-party dependency versions, container image tags, or issue
+  reproduction snippets.
+
+If the intent is ambiguous, leave a `COMMENT` asking whether the version should
+track the current release instead of requesting changes outright.
+
 ## Phase A artifact
 
 When Phase A finishes, write down (in memory) a frozen Phase A result containing:

.github/agents/release-verifier.agent.md

@@ -121,7 +121,22 @@ Scan the documentation for version strings that should have been updated for thi
 
 Determine the immediately prior version. For `13.2` the prior is `13.1`; for `13.0` the prior is `9.5` (or whatever the last release of the previous major is). Use the existing what's-new files to determine this.
 
-#### 4b. Scan for stale version references
+#### 4b. Verify shared version placeholders
+
+Read `src/frontend/config/aspire-versions.mjs` and verify the exported current
+version constants match the release being verified:
+
+| Export | Expected value |
+|--------|----------------|
+| `currentAspireMajorMinorVersion` | `{VERSION}` (for example, `13.2`) |
+| `currentAspireVersion` | `{NUGET_VERSION}` (for example, `13.2.0`) |
+
+These constants drive the `%ASPIRE_VERSION_MAJOR_MINOR%` and
+`%ASPIRE_VERSION%` documentation placeholders. If either value is stale, flag it
+as a **critical** failure because generated docs can show the wrong current
+release version.
+
+#### 4c. Scan for stale version references
 
 Search the docs content tree for references to the prior NuGet version that appear **outside** of intentional historical context (e.g., upgrade-from examples that deliberately show the old version).
 
@@ -139,7 +154,7 @@ grep -rn 'Aspire.AppHost.Sdk.*Version="{PRIOR_NUGET_VERSION}"' src/frontend/src/
   --include="*.mdx"
 ```
 
-#### 4c. Evaluate each match
+#### 4d. Evaluate each match
 
 For every match found:
 
@@ -149,7 +164,7 @@ For every match found:
    - **Stale (should be updated)**: The reference is in current guidance, installation instructions, or sample code that a user would copy today. Flag these for update.
 3. Log each stale reference with file path, line number, and surrounding context.
 
-#### 4d. Verify new version references
+#### 4e. Verify new version references
 
 Spot-check that key documentation pages reference the release version:
 

src/frontend/astro.config.mjs

@@ -8,6 +8,8 @@ import { cookieConfig } from './config/cookie.config';
 import { locales } from './config/locales.ts';
 import { headAttrs } from './config/head.attrs.ts';
 import { socialConfig } from './config/socials.config.ts';
+import { aspireVersionPlaceholdersIntegration } from './config/aspire-version-placeholders-integration.mjs';
+import { remarkAspireVersionPlaceholders } from './config/remark-aspire-version-placeholders.mjs';
 import catppuccin from '@catppuccin/starlight';
 import lunaria from './config/lunaria-starlight.mjs';
 import mermaid from 'astro-mermaid';
@@ -48,7 +50,9 @@ export default defineConfig({
   site: 'https://aspire.dev',
   trailingSlash: 'always',
   markdown: {
-    processor: unified(),
+    processor: unified({
+      remarkPlugins: [remarkAspireVersionPlaceholders],
+    }),
   },
   redirects: redirects,
   integrations: [
@@ -238,6 +242,7 @@ export default defineConfig({
     }),
     jopSoftwarecookieconsent(cookieConfig),
     ...(isBuildTimingEnabled ? [buildTiming()] : []),
+    aspireVersionPlaceholdersIntegration(),
   ],
   build: {
     concurrency: buildConcurrency,

src/frontend/config/aspire-version-placeholders-integration.mjs

@@ -0,0 +1,91 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { replaceAspireVersionPlaceholders } from './remark-aspire-version-placeholders.mjs';
+
+// Per-page Markdown copies emitted by `starlight-page-actions` are the only
+// generated artifacts that still contain raw `%ASPIRE_VERSION%` placeholders:
+// that plugin `viteStaticCopy`s `src/content/docs/**/*.{md,mdx}` straight to
+// `dist/**/*.md` through a regex-only transform, so it never runs through the
+// `remarkAspireVersionPlaceholders` remark plugin.
+//
+// Everything else is already handled before it reaches `dist`:
+//   - `.html` pages   -> rendered via the remark pipeline (placeholders replaced
+//                        in the mdast before expressive-code renders code blocks)
+//   - `llms*.txt`     -> `starlight-llms-txt` sources rendered HTML (`render(entry)`)
+//   - `reference/**.md` -> generated from API/sample data, not docs content
+//
+// So this post-build pass only needs to touch `.md` files. Scoping it this way
+// (instead of walking every `.html`/`.txt` in `dist`) avoids re-reading the bulk
+// of the output — including the large `llms-full.txt` assets — which is what
+// previously exhausted the Node heap.
+const placeholderCopyExtensions = new Set(['.md']);
+
+// Process the Markdown copies through a small worker pool rather than a single
+// recursive `Promise.all` over the whole tree, so peak memory stays proportional
+// to the concurrency limit instead of the number of files held open at once.
+const DEFAULT_CONCURRENCY = 16;
+
+export function aspireVersionPlaceholdersIntegration() {
+  return {
+    name: 'aspire-version-placeholders',
+    hooks: {
+      'astro:build:done': async ({ dir }) => {
+        await replaceAspireVersionPlaceholdersInDirectory(fileURLToPath(dir));
+      },
+    },
+  };
+}
+
+export async function replaceAspireVersionPlaceholdersInDirectory(
+  directory,
+  concurrency = DEFAULT_CONCURRENCY
+) {
+  const files = [];
+  await collectMarkdownCopies(directory, files);
+
+  if (files.length === 0) {
+    return;
+  }
+
+  // Normalize to a finite positive integer so a stray NaN/0/negative value can't
+  // collapse the worker pool to an empty array and silently skip every file.
+  const limit = Number.isFinite(concurrency) ? Math.floor(concurrency) : DEFAULT_CONCURRENCY;
+  const workerCount = Math.min(Math.max(1, limit), files.length);
+  let cursor = 0;
+
+  const runWorker = async () => {
+    while (cursor < files.length) {
+      const filePath = files[cursor++];
+      await replaceAspireVersionPlaceholdersInFile(filePath);
+    }
+  };
+
+  await Promise.all(Array.from({ length: workerCount }, runWorker));
+}
+
+async function collectMarkdownCopies(directory, files) {
+  const entries = await readdir(directory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const resolvedPath = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      await collectMarkdownCopies(resolvedPath, files);
+      continue;
+    }
+
+    if (entry.isFile() && placeholderCopyExtensions.has(path.extname(entry.name))) {
+      files.push(resolvedPath);
+    }
+  }
+}
+
+async function replaceAspireVersionPlaceholdersInFile(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  const updated = replaceAspireVersionPlaceholders(content);
+
+  if (updated !== content) {
+    await writeFile(filePath, updated);
+  }
+}

src/frontend/config/aspire-versions.mjs

@@ -0,0 +1,7 @@
+export const currentAspireMajorMinorVersion = '13.5';
+export const currentAspireVersion = '13.5.0';
+
+export const aspireVersionPlaceholders = Object.freeze({
+  '%ASPIRE_VERSION_MAJOR_MINOR%': currentAspireMajorMinorVersion,
+  '%ASPIRE_VERSION%': currentAspireVersion,
+});

src/frontend/config/remark-aspire-version-placeholders.mjs

@@ -0,0 +1,40 @@
+import { aspireVersionPlaceholders } from './aspire-versions.mjs';
+
+const placeholderEntries = Object.entries(aspireVersionPlaceholders);
+
+export function replaceAspireVersionPlaceholders(value) {
+  return placeholderEntries.reduce(
+    (current, [placeholder, version]) => current.replaceAll(placeholder, version),
+    value
+  );
+}
+
+export function remarkAspireVersionPlaceholders() {
+  return (tree) => {
+    replaceNodeValues(tree);
+  };
+}
+
+function replaceNodeValues(node) {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+
+  if (typeof node.value === 'string') {
+    node.value = replaceAspireVersionPlaceholders(node.value);
+  }
+
+  if (Array.isArray(node.attributes)) {
+    for (const attribute of node.attributes) {
+      if (attribute && typeof attribute.value === 'string') {
+        attribute.value = replaceAspireVersionPlaceholders(attribute.value);
+      }
+    }
+  }
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) {
+      replaceNodeValues(child);
+    }
+  }
+}

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

@@ -243,6 +243,27 @@ export const dashboardTopics: StarlightSidebarTopicsUserConfig = {
       },
       slug: 'dashboard/security-considerations',
     },
+    {
+      label: 'Troubleshooting',
+      translations: {
+        da: 'Fejlfinding',
+        de: 'Fehlerbehebung',
+        en: 'Troubleshooting',
+        es: 'Solución de problemas',
+        fr: 'Dépannage',
+        hi: 'समस्या निवारण',
+        id: 'Pemecahan masalah',
+        it: 'Risoluzione dei problemi',
+        ja: 'トラブルシューティング',
+        ko: '문제 해결',
+        'pt-BR': 'Solução de problemas',
+        ru: 'Устранение неполадок',
+        tr: 'Sorun giderme',
+        uk: 'Усунення неполадок',
+        'zh-CN': '故障排除',
+      },
+      slug: 'dashboard/troubleshooting',
+    },
     {
       label: 'Telemetry',
       translations: {

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

@@ -150,6 +150,10 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = {
           label: 'External Helm charts',
           slug: 'deployment/kubernetes/helm-charts',
         },
+        {
+          label: 'Persistent volumes',
+          slug: 'deployment/kubernetes/persistent-volumes',
+        },
         {
           label: 'Ingress & Gateway API',
           slug: 'deployment/kubernetes-ingress',

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

@@ -90,6 +90,10 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = {
       label: "What's new",
       collapsed: true,
       items: [
+        {
+          label: 'Aspire 13.5',
+          slug: 'whats-new/aspire-13-5',
+        },
         {
           label: 'Aspire 13.4',
           slug: 'whats-new/aspire-13-4',
@@ -936,6 +940,10 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = {
                 ja: '実行可能リソース',
               },
             },
+            {
+              label: 'Interactive terminals',
+              slug: 'app-host/with-terminal',
+            },
           ],
         },
         {

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

@@ -538,6 +538,24 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
               slug: 'reference/cli/commands/aspire-start',
             },
             { label: 'aspire stop', slug: 'reference/cli/commands/aspire-stop' },
+            {
+              label: 'aspire terminal',
+              collapsed: true,
+              items: [
+                {
+                  label: 'aspire terminal',
+                  slug: 'reference/cli/commands/aspire-terminal',
+                },
+                {
+                  label: 'aspire terminal attach',
+                  slug: 'reference/cli/commands/aspire-terminal-attach',
+                },
+                {
+                  label: 'aspire terminal ps',
+                  slug: 'reference/cli/commands/aspire-terminal-ps',
+                },
+              ],
+            },
             {
               label: 'aspire update',
               slug: 'reference/cli/commands/aspire-update',

src/frontend/src/content/docs/app-host/configuration.mdx

@@ -24,9 +24,14 @@ AppHost configuration is provided through launch profiles:
   ]}
 />
 <Pivot id="csharp">
-In C# AppHosts, profiles live in `launchSettings.json`:
+C# AppHosts come in two forms, and each stores launch profiles differently:
 
-```json title="launchSettings.json"
+- **Project-based AppHost** (the default `dotnet new aspire-apphost` template): profiles live in `Properties/launchSettings.json`.
+- **File-based AppHost** (created with `aspire new` using the empty C# template): profiles live in `apphost.run.json`. In this template, `aspire.config.json` only points at the entry file — it does **not** contain a `profiles` block.
+
+**Project-based AppHost** — `Properties/launchSettings.json`:
+
+```json title="Properties/launchSettings.json"
 {
   "$schema": "https://json.schemastore.org/launchsettings.json",
   "profiles": {
@@ -45,6 +50,38 @@ In C# AppHosts, profiles live in `launchSettings.json`:
   }
 }
 ```
+
+**File-based AppHost** — `apphost.run.json` (profiles) and `aspire.config.json` (entry point only):
+
+```json title="apphost.run.json"
+{
+  "profiles": {
+    "https": {
+      "applicationUrl": "https://localhost:17134;http://localhost:15170",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21030",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22057"
+      }
+    }
+  }
+}
+```
+
+```json title="aspire.config.json"
+{
+  "appHost": {
+    "path": "apphost.cs"
+  }
+}
+```
+
+<Aside type="note">
+  `aspire run`, `dotnet run apphost.cs`, and C# Dev Kit all read `apphost.run.json`
+  for launch profiles when it is present. In the `aspire new` empty C# template,
+  `aspire.config.json` intentionally omits `profiles` to avoid duplicating that data.
+</Aside>
 </Pivot>
 <Pivot id="typescript">
 In TypeScript AppHosts, profiles live in `aspire.config.json`: