🤓 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/certificate-configuration.mdx

@@ -5,6 +5,7 @@ description: Configure HTTPS endpoints and certificate trust for Aspire resource
 ---
 
 import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import OsAwareTabs from '@components/OsAwareTabs.astro';
 
 Aspire provides two complementary sets of certificate APIs:
 
@@ -36,7 +37,31 @@ Many of the certificate features in Aspire rely on a development certificate. Be
 
 ### Using the Aspire CLI (recommended)
 
-The preferred way to manage the development certificate is to use the [Aspire CLI](/get-started/install-cli/). When you run `aspire run`, the CLI automatically ensures the development certificate is created and trusted. No additional manual steps are required.
+The preferred way to manage the development certificate is to use the [Aspire CLI](/get-started/install-cli/). When you run `aspire run` in an interactive session, the CLI automatically ensures the development certificate is created and trusted. No additional manual steps are required.
+
+For non-C# AppHosts (such as [TypeScript](/app-host/typescript-apphost/) or Python AppHosts), the `dotnet` first-run experience that normally creates the HTTPS development certificate never runs, because these AppHosts launch a prebuilt native binary instead of invoking `dotnet`. The Aspire CLI fills this gap when `aspire run` starts and no development certificate exists:
+
+- In an interactive session—and on Linux, where establishing trust doesn't require a prompt—the CLI creates *and* trusts the certificate, just as it does for C# AppHosts.
+- In a non-interactive session on macOS or Windows (for example, in CI), the CLI can't show the macOS Keychain password prompt or the Windows trust dialog, so it *generates* the certificate without trusting it. This lets servers such as Kestrel load the certificate from the personal store, even though it isn't trusted. If the certificate can't be generated, a warning is displayed and the run continues.
+
+To opt out of automatic certificate generation, set the `ASPIRE_CLI_GENERATE_HTTPS_CERTIFICATE` environment variable to `false`. This mirrors the .NET SDK's `DOTNET_GENERATE_ASPNET_CERTIFICATE` opt-out:
+
+<OsAwareTabs syncKey="terminal">
+<div slot="unix">
+
+```bash title="Disable automatic HTTPS certificate generation"
+ASPIRE_CLI_GENERATE_HTTPS_CERTIFICATE=false aspire run
+```
+
+</div>
+<div slot="windows">
+
+```powershell title="Disable automatic HTTPS certificate generation"
+$env:ASPIRE_CLI_GENERATE_HTTPS_CERTIFICATE="false"; aspire run
+```
+
+</div>
+</OsAwareTabs>
 
 You can also manage certificates explicitly with the Aspire CLI: