From 799cce238ea2f6e0b9cb4968e540bd85b7be9e54 Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Sat, 7 Nov 2026 21:07:30 +0000
Subject: [PATCH] Document template source headings in aspire new picker

---
 .../docs/reference/cli/commands/aspire-new.mdx  | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
index c557f4dcb..746a156c2 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
@@ -48,6 +48,23 @@ The `--output` option validates the provided path before creating the project:
 
 When running `aspire new` in interactive mode, the command asks one or more questions before generating the project. The available prompts depend on the template and options you provide.
 
+### Template source headings
+
+When you've configured template sources, the template picker groups templates under a heading for each source. Each heading keeps the source's friendly name (or its alias when no name is set) and shows where the templates come from:
+
+- **Git sources** use `Name (repository @ ref)`. When the source doesn't specify a ref, the heading shows `default branch`.
+- **Directory sources** use `Name (path)`.
+
+For example:
+
+```text title="Template picker headings"
+Company templates (https://github.com/example/templates @ release/templates)
+company (https://github.com/example/templates @ default branch)
+Company templates (/work/templates)
+```
+
+Long headings are cropped to fit the terminal width.
+
 ### Use \*.dev.localhost URLs?
 
 During project creation, you may be prompted: