diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..42a3ecb
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,7 @@
+# Code owners for template/stable.
+#
+# GitHub uses this file (combined with the branch's
+# `require_code_owner_reviews` protection rule) to enforce that every PR
+# targeting this branch is approved by at least one listed owner. The line
+# below applies repo-wide; either owner can satisfy the requirement.
+*       @Yimin-Jin @huimiu
diff --git a/.github/scripts/generate_sample_catalog.mjs b/.github/scripts/generate_sample_catalog.mjs
new file mode 100644
index 0000000..75e63c4
--- /dev/null
+++ b/.github/scripts/generate_sample_catalog.mjs
@@ -0,0 +1,894 @@
+// @ts-check
+/**
+ * Generate samples/hosted-agent/sample-catalog.json from the foundry-samples repository.
+ *
+ * Walks the hosted-agents tree in microsoft-foundry/foundry-samples once via
+ * the git-tree API, parses each sample's azure.yaml (the azd service
+ * manifest) for protocol and model requirements, derives displayName from the
+ * directory name, and — when AZURE_OPENAI_* secrets are set — fills the
+ * description with a short LLM-generated sentence sourced from the sample's
+ * README.md.
+ *
+ * Usage:
+ *   node generate_sample_catalog.mjs <commitSha>
+ *
+ * Environment variables:
+ *   GITHUB_TOKEN        Optional GitHub token for API authentication.
+ *   REPO_ROOT           Repository root (defaults to two levels up from this script).
+ *   SAMPLES_REPO_URL    Source repo URL (defaults to https://github.com/microsoft-foundry/foundry-samples/).
+ *   AZURE_OPENAI_*      Optional; when set, descriptions are LLM-generated.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const REPO_ROOT = process.env.REPO_ROOT || resolve(__dirname, '..', '..');
+const SAMPLES_REPO_URL = process.env.SAMPLES_REPO_URL || 'https://github.com/microsoft-foundry/foundry-samples/';
+const SAMPLES_REPO_API = 'https://api.github.com/repos/microsoft-foundry/foundry-samples';
+const OUTPUT_PATH = join(REPO_ROOT, 'samples', 'hosted-agent', 'sample-catalog.json');
+const OVERRIDES_PATH = join(REPO_ROOT, 'samples', 'hosted-agent', 'sample-overrides.json');
+
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN || '';
+
+// Languages, frameworks, and protocols are discovered dynamically from the
+// samples repo tree (see discoverLanguagesAndFrameworks / parseAzureYaml)
+// instead of being restricted by an allowlist. These blacklists are the
+// explicit escape hatch to exclude a specific discovered value; empty by
+// default means "no restriction" — everything discovered is kept.
+/** @type {string[]} */
+const BLOCKED_LANGUAGES = [];
+/** @type {string[]} */
+const BLOCKED_FRAMEWORKS = [];
+/** @type {string[]} */
+const BLOCKED_PROTOCOLS = [];
+
+/** @type {Record<string, {title: string, placeholder: string, options: Record<string, string>}>} */
+const DIMENSION_DEFAULTS = {
+    language: {
+        title: 'Select a Language',
+        placeholder: 'Choose the language for your agent',
+        options: {
+            python: 'Python',
+            csharp: 'C# (.NET)',
+        },
+    },
+    framework: {
+        title: 'Select a Framework',
+        placeholder: 'Choose the framework for your agent',
+        // Insertion order here drives the option order in the generated catalog
+        // (see buildDimensions). Keep the most actively promoted framework first.
+        options: {
+            'copilot-sdk': 'Copilot SDK',
+            'agent-framework': 'Agent Framework',
+            'bring-your-own': 'Bring Your Own',
+            'langgraph': 'LangGraph',
+        },
+    },
+    protocol: {
+        title: 'Select a Protocol',
+        placeholder: 'Choose the protocol for your agent',
+        options: {
+            responses: 'Responses API',
+            invocations: 'Invocations API',
+            invocations_ws: 'Invocations (WebSocket)',
+        },
+    },
+};
+
+const TEMPLATE_SELECTION = {
+    title: 'Select a Template',
+    placeholder: 'Choose a template for your agent',
+};
+
+// Path segments must be alphanumeric, hyphens, underscores, or dots
+const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+
+// Category segments to EXCLUDE at the position immediately under a framework
+// (`<framework>/<category>/...`). This is a BLACK-LIST: empty by default means
+// every discovered category is surfaced; add a segment here to drop an upstream
+// grouping you don't want in the picker yet. Flat templates that sit directly
+// under a framework (e.g. csharp `agent-framework/hello-world`) have no category
+// segment and are always surfaced (see findTemplateDirsUnder).
+/** @type {Set<string>} */
+const BLOCKED_CATEGORY_SEGMENTS = new Set();
+
+// De-dupes the per-category "skipped" log line so an excluded category that
+// spans many templates is reported once, not once per template.
+/** @type {Set<string>} */
+const skippedCategoriesLogged = new Set();
+
+/**
+ * Collected anomaly messages surfaced in CI step summary so reviewers do not
+ * silently merge a catalog with missing/derived data. Always populated, even
+ * when running locally without a step-summary file.
+ * @type {string[]}
+ */
+const warnings = [];
+
+/**
+ * Record a warning that should appear in the CI step summary, and mirror it
+ * to stderr for live log visibility.
+ * @param {string} message
+ */
+function warn(message) {
+    warnings.push(message);
+    console.warn(`WARN: ${message}`);
+}
+
+/**
+ * @param {string} url
+ * @returns {Promise<any>}
+ */
+async function fetchJson(url) {
+    /** @type {Record<string, string>} */
+    const headers = {
+        'User-Agent': 'microsoft-foundry-for-vscode-sync',
+        Accept: 'application/vnd.github+json',
+    };
+    if (GITHUB_TOKEN) {
+        headers['Authorization'] = `Bearer ${GITHUB_TOKEN}`;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} for ${url}`);
+    }
+    return response.json();
+}
+
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchText(url) {
+    /** @type {Record<string, string>} */
+    const headers = { 'User-Agent': 'microsoft-foundry-for-vscode-sync' };
+    if (GITHUB_TOKEN) {
+        headers['Authorization'] = `Bearer ${GITHUB_TOKEN}`;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} for ${url}`);
+    }
+    return response.text();
+}
+
+/**
+ * Validate that a path segment is safe: no traversal, no special chars, no
+ * leading-dot directories (e.g. `.claude`, `.github`) which are tooling
+ * metadata, not sample templates.
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isSafePathSegment(segment) {
+    if (segment === '.' || segment === '..' || segment.startsWith('.')) {
+        return false;
+    }
+    return SAFE_PATH_SEGMENT.test(segment);
+}
+
+/**
+ * Parse the commit SHA from the CLI argument.
+ * @returns {string}
+ */
+function parseCommitShaArg() {
+    const sha = process.argv[2] || '';
+    if (!sha) {
+        console.error('Usage: node generate_sample_catalog.mjs <commitSha>');
+        process.exit(1);
+    }
+    if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
+        throw new Error(`Invalid commit SHA: "${sha}"`);
+    }
+    return sha;
+}
+
+/**
+ * Fetch the full recursive git tree for a ref. One API call covers the entire
+ * `samples/` hierarchy, which is much cheaper (and more accurate) than walking
+ * the `/contents/` endpoint level-by-level — and it lets us discover samples
+ * at arbitrary nesting depths (e.g. `bring-your-own/voicelive/<template>`)
+ * without hard-coding the layout.
+ *
+ * @param {string} ref
+ * @returns {Promise<{tree: Array<{path: string, type: string}>, truncated: boolean}>}
+ */
+async function fetchRepoTree(ref) {
+    const data = await fetchJson(`${SAMPLES_REPO_API}/git/trees/${ref}?recursive=1`);
+    const tree = Array.isArray(data?.tree) ? data.tree : [];
+    return { tree, truncated: Boolean(data?.truncated) };
+}
+
+/**
+ * Discover the languages and frameworks present in the samples repo tree,
+ * then drop any listed in the (empty by default) BLOCKED_LANGUAGES /
+ * BLOCKED_FRAMEWORKS blacklists. A "language" is the path segment directly
+ * under `samples/` that owns a `hosted-agents/` folder; a "framework" is the
+ * segment directly under `hosted-agents/`. Discovering these dynamically —
+ * instead of hard-coding an allowlist — means new upstream languages or
+ * frameworks are picked up automatically, while the blacklists remain an
+ * explicit way to exclude a specific value. Hidden or unsafe segments (those
+ * failing isSafePathSegment, e.g. `.github`) are ignored.
+ *
+ * @param {Array<{path: string, type: string}>} tree
+ * @returns {{ languages: string[], frameworks: string[] }}
+ */
+function discoverLanguagesAndFrameworks(tree) {
+    /** @type {Set<string>} */
+    const languages = new Set();
+    /** @type {Set<string>} */
+    const frameworks = new Set();
+    const pattern = /^samples\/([^/]+)\/hosted-agents\/([^/]+)(?:\/|$)/;
+
+    for (const entry of tree) {
+        const match = entry.path.match(pattern);
+        if (!match) {
+            continue;
+        }
+        const [, language, framework] = match;
+        if (isSafePathSegment(language) && !BLOCKED_LANGUAGES.includes(language)) {
+            languages.add(language);
+        }
+        if (isSafePathSegment(framework) && !BLOCKED_FRAMEWORKS.includes(framework)) {
+            frameworks.add(framework);
+        }
+    }
+
+    return {
+        languages: [...languages].sort(),
+        frameworks: [...frameworks].sort(),
+    };
+}
+
+/**
+ * Find sample template directories under a `hosted-agents/<framework>/` prefix.
+ * A template is identified by the presence of an `azure.yaml` (the azd service
+ * manifest). When nested azure.yaml files exist (e.g. a sub-agent declared
+ * inside a parent sample), only the OUTERMOST one is treated as a catalog
+ * template — the inner files are part of the parent sample. Hidden directories
+ * (segments beginning with `.`, e.g. `.claude/skills`) are skipped, as are
+ * segments that fail the `SAFE_PATH_SEGMENT` check.
+ *
+ * Nested templates are kept unless their category segment is listed in
+ * `BLOCKED_CATEGORY_SEGMENTS` (empty by default, so everything is surfaced);
+ * flat templates directly under the framework (csharp's
+ * `agent-framework/<template>` layout) have no category and are always kept.
+ * Add a segment to the blacklist to drop an unwanted upstream grouping.
+ *
+ * @param {Array<{path: string, type: string}>} tree
+ * @param {string} prefix Path prefix ending in `/`, e.g. `samples/python/hosted-agents/agent-framework/`.
+ * @returns {string[]} Repo-relative template directory paths, outermost only.
+ */
+function findTemplateDirsUnder(tree, prefix) {
+    const candidates = tree
+        .filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix) && entry.path.endsWith('/azure.yaml'))
+        .map((entry) => entry.path.slice(0, -'/azure.yaml'.length))
+        .filter((dir) => {
+            const rel = dir.slice(prefix.length);
+            if (!rel) {
+                return false;
+            }
+            const segments = rel.split('/');
+            if (!segments.every((seg) => isSafePathSegment(seg))) {
+                return false;
+            }
+            // Flat templates sit directly under the framework
+            // (`<framework>/<template>`, e.g. csharp `agent-framework/hello-world`)
+            // and have no category segment — always surface them.
+            if (segments.length === 1) {
+                return true;
+            }
+            // Nested templates (`<framework>/<category>/...`) are kept unless the
+            // category is explicitly blacklisted. Empty blacklist => everything is
+            // surfaced (fail-open), matching the language/framework/protocol lists.
+            const category = segments[0];
+            if (!BLOCKED_CATEGORY_SEGMENTS.has(category)) {
+                return true;
+            }
+            if (!skippedCategoriesLogged.has(category)) {
+                skippedCategoriesLogged.add(category);
+                console.log(`Skipping category "${category}" (in BLOCKED_CATEGORY_SEGMENTS); e.g. ${dir}`);
+            }
+            return false;
+        })
+        // Lexicographic sort serves two purposes: (1) a parent path always
+        // sorts before its descendants, so the `startsWith` check below
+        // correctly keeps only the outermost azure.yaml; (2) it preserves
+        // upstream's `NN-` numeric prefix ordering in the picker.
+        .sort();
+
+    /** @type {string[]} */
+    const outermost = [];
+    for (const dir of candidates) {
+        if (!outermost.some((existing) => dir.startsWith(`${existing}/`))) {
+            outermost.push(dir);
+        }
+    }
+    return outermost;
+}
+
+/**
+ * Infer protocol when `azure.yaml` does not declare one explicitly. Looks for
+ * a `responses` or `invocations` segment in the path, then for the substring
+ * in the leaf directory name (common for samples like
+ * `hello-world-invocations-voicelive`). Falls back to `responses` and emits a
+ * warning so the catalog reviewer can verify the choice.
+ *
+ * @param {string} templatePath
+ * @returns {'responses' | 'invocations'}
+ */
+function inferProtocolFromPath(templatePath) {
+    const segments = templatePath.split('/');
+    if (segments.includes('responses')) {
+        return 'responses';
+    }
+    if (segments.includes('invocations')) {
+        return 'invocations';
+    }
+    const leaf = segments[segments.length - 1].toLowerCase();
+    if (leaf.includes('invocations')) {
+        return 'invocations';
+    }
+    if (leaf.includes('responses')) {
+        return 'responses';
+    }
+    warn(`Could not infer protocol for "${templatePath}"; defaulting to "responses". Add a "- protocol:" entry to azure.yaml or a sample-overrides.json entry to silence this.`);
+    return 'responses';
+}
+
+/**
+ * Minimal parser for a sample's azure.yaml (the azd service manifest).
+ * Extracts the declared protocol(s) from the hosted-agent service's
+ * `protocols:` list and whether the sample requires a Foundry model. A sample
+ * requires a model when it either consumes one (an
+ * AZURE_AI_MODEL_DEPLOYMENT_NAME env var) or provisions one (an `ai-project`
+ * `deployments:` block — which replaced the model resource that used to live
+ * in agent.manifest.yaml). Does NOT use eval or a real YAML library — a line
+ * scan is sufficient for these fields. Any declared protocol is accepted
+ * except those listed in BLOCKED_PROTOCOLS (empty by default).
+ * @param {string} content
+ * @returns {{ protocols: string[], requiresModel: boolean }}
+ */
+function parseAzureYaml(content) {
+    /** @type {{ protocols: string[], requiresModel: boolean }} */
+    const result = { protocols: [], requiresModel: false };
+
+    for (const line of content.split('\n')) {
+        const stripped = line.trim();
+        if (stripped.startsWith('- protocol:')) {
+            const value = stripped.split(':')[1]?.trim();
+            if (value && !BLOCKED_PROTOCOLS.includes(value)) {
+                result.protocols.push(value);
+            }
+        }
+        // Model consumer: the agent reads a Foundry model deployment name.
+        if (stripped.startsWith('- name:') && stripped.includes('AZURE_AI_MODEL_DEPLOYMENT_NAME')) {
+            result.requiresModel = true;
+        }
+        // Model provider: the ai-project service declares one or more model
+        // deployments to provision (the azure.yaml successor to a manifest
+        // `kind: model` resource).
+        if (stripped === 'deployments:') {
+            result.requiresModel = true;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Fetch and parse a sample directory's azure.yaml.
+ * @param {string} samplePath
+ * @param {string} ref
+ * @returns {Promise<{ protocols: string[], requiresModel: boolean } | null>}
+ */
+async function fetchAzureYaml(samplePath, ref) {
+    const rawUrl = `https://raw.githubusercontent.com/microsoft-foundry/foundry-samples/${ref}/${samplePath}/azure.yaml`;
+    try {
+        const content = await fetchText(rawUrl);
+        return parseAzureYaml(content);
+    } catch {
+        return null;
+    }
+}
+
+// Azure OpenAI configuration (from GitHub Secrets via env vars)
+const AZURE_OPENAI_ENDPOINT = process.env.AZURE_OPENAI_ENDPOINT || '';
+const AZURE_OPENAI_API_KEY = process.env.AZURE_OPENAI_API_KEY || '';
+const AZURE_OPENAI_DEPLOYMENT = process.env.AZURE_OPENAI_DEPLOYMENT || 'gpt-4o-mini';
+
+/**
+ * Fetch README.md content for a sample directory.
+ * @param {string} samplePath
+ * @param {string} ref
+ * @returns {Promise<string | null>}
+ */
+async function fetchReadme(samplePath, ref) {
+    const rawUrl = `https://raw.githubusercontent.com/microsoft-foundry/foundry-samples/${ref}/${samplePath}/README.md`;
+    try {
+        return await fetchText(rawUrl);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Call Azure OpenAI to generate a description from README content. We
+ * intentionally do NOT ask the LLM for displayName — the folder name (with
+ * numeric-prefix stripped, dashes turned into spaces, and Title Case)
+ * produces more consistent results across the catalog and is easier for PMs
+ * to predict at review time.
+ *
+ * @param {string} readmeContent
+ * @param {string} samplePath
+ * @returns {Promise<{ description: string } | null>}
+ */
+async function generateWithLLM(readmeContent, samplePath) {
+    if (!AZURE_OPENAI_ENDPOINT || !AZURE_OPENAI_API_KEY) {
+        return null;
+    }
+
+    const apiUrl = `${AZURE_OPENAI_ENDPOINT}/openai/deployments/${AZURE_OPENAI_DEPLOYMENT}/chat/completions?api-version=2024-08-01-preview`;
+
+    const systemPrompt = `You generate one-sentence descriptions for a VS Code template picker.
+The user has already selected language, framework, and protocol before seeing these items, so the description must NOT repeat those choices.
+
+Rules:
+- One sentence, max 100 characters
+- Plain text, no markdown
+- Describe what the sample does, not how it is implemented
+- Do NOT include language names, protocol names, framework names, or words like "Sample" / "Demo"
+
+Examples:
+  {"description": "Minimal agent that echoes a response from a Foundry model."}
+  {"description": "Conversational agent with multi-turn session history."}
+  {"description": "Agent with local function tools for hotel search."}
+  {"description": "Agent that discovers and invokes tools from a remote MCP server."}
+  {"description": "Agent that saves and retrieves notes using function calling."}
+
+Respond ONLY with a JSON object: {"description": "..."}`;
+
+    const userPrompt = `Path: ${samplePath}
+
+README.md:
+${readmeContent.substring(0, 2000)}`;
+
+    const body = {
+        messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPrompt },
+        ],
+        temperature: 0,
+        max_tokens: 120,
+    };
+
+    try {
+        const response = await fetch(apiUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'api-key': AZURE_OPENAI_API_KEY,
+            },
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            warn(`LLM API returned ${response.status} for ${samplePath}; description will be left empty.`);
+            return null;
+        }
+
+        const data = await response.json();
+        const content = data.choices?.[0]?.message?.content?.trim();
+        if (!content) {
+            return null;
+        }
+
+        // Parse JSON response — strip markdown code fences if present
+        const jsonStr = content.replace(/^```json\s*/, '').replace(/\s*```$/, '');
+        const parsed = JSON.parse(jsonStr);
+
+        const description = typeof parsed.description === 'string' ? parsed.description.trim() : '';
+        if (!description) {
+            return null;
+        }
+
+        return { description };
+    } catch (/** @type {any} */ err) {
+        warn(`LLM call failed for ${samplePath}: ${err.message}`);
+        return null;
+    }
+}
+
+/**
+ * Brand and acronym casing overrides applied during displayName derivation.
+ * Keys are lower-case tokens; values are the canonical user-facing rendering.
+ * Add entries here when a new acronym or brand appears in a sample folder
+ * name so the template picker doesn't show "Github" / "Mcp" / "Sdk".
+ * @type {Record<string, string>}
+ */
+const DISPLAY_NAME_TOKEN_CASING = {
+    ag: 'AG',
+    ai: 'AI',
+    api: 'API',
+    aws: 'AWS',
+    cli: 'CLI',
+    gcp: 'GCP',
+    github: 'GitHub',
+    llm: 'LLM',
+    mcp: 'MCP',
+    openai: 'OpenAI',
+    rag: 'RAG',
+    sdk: 'SDK',
+    sso: 'SSO',
+    ui: 'UI',
+};
+
+/**
+ * Derive a displayName from the template's directory name. Strips a leading
+ * numeric ordering prefix (`09-`, `12_`) so upstream reorderings don't bleed
+ * into the picker, then converts dash/underscore tokens into Title Case
+ * words and applies `DISPLAY_NAME_TOKEN_CASING` for known acronyms/brands:
+ * `09-declarative-customer-support` -> `Declarative Customer Support`,
+ * `azure-search-rag` -> `Azure Search RAG`.
+ *
+ * @param {string} samplePath
+ * @returns {string}
+ */
+function displayNameFromPath(samplePath) {
+    const dirName = samplePath.split('/').pop() || '';
+    return dirName
+        .replace(/^\d+[-_]/, '')
+        .split(/[-_]/)
+        .filter((w) => w.length > 0)
+        .map((w) => DISPLAY_NAME_TOKEN_CASING[w.toLowerCase()] ?? (w.charAt(0).toUpperCase() + w.slice(1)))
+        .join(' ');
+}
+
+/**
+ * Scan the foundry-samples repo and build the flat template list. Uses one
+ * recursive git-tree call to enumerate every `azure.yaml` under each
+ * `<language>/hosted-agents/<framework>/` prefix, regardless of intermediate
+ * directories. Languages and frameworks are discovered dynamically from the
+ * tree (see discoverLanguagesAndFrameworks) rather than hard-coded, then
+ * filtered through the BLOCKED_LANGUAGES/BLOCKED_FRAMEWORKS blacklists. This
+ * supports both the canonical layout (`<framework>/<protocol>/<template>`),
+ * the flat layout (`<framework>/<template>`), and category-grouped layouts
+ * such as `bring-your-own/voicelive/hello-world-invocations-voicelive`.
+ *
+ * @param {string} commitSha
+ * @returns {Promise<Array<{language: string, framework: string, protocol: string, displayName: string, description: string, path: string, requiresModel: boolean}>>}
+ */
+async function scanTemplates(commitSha) {
+    /** @type {Array<{language: string, framework: string, protocol: string, displayName: string, description: string, path: string, requiresModel: boolean}>} */
+    const templates = [];
+
+    const { tree, truncated } = await fetchRepoTree(commitSha);
+    if (truncated) {
+        warn(`GitHub git-tree API returned truncated=true for ${commitSha}; some samples may be missing from the catalog. Consider pinning to a smaller subtree or re-running.`);
+    }
+
+    const { languages, frameworks } = discoverLanguagesAndFrameworks(tree);
+
+    for (const language of languages) {
+        for (const framework of frameworks) {
+            const prefix = `samples/${language}/hosted-agents/${framework}/`;
+            const templateDirs = findTemplateDirsUnder(tree, prefix);
+
+            for (const templatePath of templateDirs) {
+                const azureInfo = await fetchAzureYaml(templatePath, commitSha);
+                if (!azureInfo) {
+                    warn(`Could not fetch or parse azure.yaml for "${templatePath}"; skipping this template.`);
+                    continue;
+                }
+
+                /** @type {string} */
+                const protocol = azureInfo.protocols.length > 0
+                    ? azureInfo.protocols[0]
+                    : inferProtocolFromPath(templatePath);
+
+                const requiresModel = azureInfo.requiresModel;
+
+                templates.push({
+                    language,
+                    framework,
+                    protocol,
+                    displayName: '',
+                    description: '',
+                    path: templatePath,
+                    requiresModel,
+                });
+            }
+        }
+    }
+
+    return templates;
+}
+
+/**
+ * Build the dimensions section from discovered templates and defaults.
+ * Option order follows the insertion order of `DIMENSION_DEFAULTS[dim].options`
+ * so we have UX control (e.g. promote `copilot-sdk` ahead of
+ * `agent-framework`). Any id seen in the scanned templates but not declared in
+ * the defaults is appended at the end in alphabetical order, so a new
+ * framework added upstream does not break the build — just shows up last.
+ *
+ * @param {Array<{language: string, framework: string, protocol: string}>} templates
+ */
+function buildDimensions(templates) {
+    /** @type {Record<string, {title: string, placeholder: string, options: Array<{id: string, displayName: string}>}>} */
+    const dimensions = {};
+
+    for (const dimKey of /** @type {const} */ (['language', 'framework', 'protocol'])) {
+        const defaults = DIMENSION_DEFAULTS[dimKey];
+        const seenIds = new Set(templates.map((t) => t[dimKey]));
+        const declaredOrder = Object.keys(defaults.options);
+        const orderedIds = [
+            ...declaredOrder.filter((id) => seenIds.has(id)),
+            ...[...seenIds].filter((id) => !declaredOrder.includes(id)).sort(),
+        ];
+        const options = orderedIds.map((id) => ({
+            id,
+            displayName: defaults.options[id] || id,
+        }));
+        dimensions[dimKey] = {
+            title: defaults.title,
+            placeholder: defaults.placeholder,
+            options,
+        };
+    }
+
+    return dimensions;
+}
+
+/**
+ * Preserve existing displayName and description from the current catalog.
+ * Only non-empty existing values are kept — never overwritten.
+ * @param {Array<{displayName: string, description: string, path: string}>} templates
+ */
+function mergeExistingDisplayFields(templates) {
+    if (!existsSync(OUTPUT_PATH)) {
+        return;
+    }
+
+    try {
+        const existing = JSON.parse(readFileSync(OUTPUT_PATH, 'utf-8'));
+        /** @type {Map<string, {displayName?: string, description?: string}>} */
+        const existingByPath = new Map();
+        for (const t of existing.templates || []) {
+            if (t.path) {
+                existingByPath.set(t.path, t);
+            }
+        }
+
+        const scannedPaths = new Set(templates.map((t) => t.path));
+        for (const template of templates) {
+            const prev = existingByPath.get(template.path);
+            if (prev) {
+                if (prev.displayName) {
+                    template.displayName = prev.displayName;
+                }
+                if (prev.description) {
+                    template.description = prev.description;
+                }
+            }
+        }
+        // Surface paths that exist in the prior catalog but were not produced
+        // by this scan — upstream likely renamed or removed the sample, and any
+        // PM-edited displayName/description on it has been dropped.
+        for (const [path, prev] of existingByPath) {
+            if (scannedPaths.has(path)) {
+                continue;
+            }
+            const hadEdits = Boolean(prev.displayName || prev.description);
+            const suffix = hadEdits ? ' Previously-edited displayName/description were dropped.' : '';
+            warn(`Template "${path}" was in the previous catalog but no longer matches any scanned sample (upstream may have renamed or removed it).${suffix}`);
+        }
+    } catch (/** @type {any} */ err) {
+        warn(`Could not read existing catalog at ${OUTPUT_PATH}: ${err.message}. Existing displayName/description values were NOT preserved this run.`);
+    }
+}
+
+/**
+ * Load source-controlled per-path overrides. Returns an empty map when the
+ * file is missing or unreadable so generation never fails on it.
+ *
+ * @returns {Map<string, Record<string, unknown>>}
+ */
+function loadOverrides() {
+    /** @type {Map<string, Record<string, unknown>>} */
+    const byPath = new Map();
+    if (!existsSync(OVERRIDES_PATH)) {
+        return byPath;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(OVERRIDES_PATH, 'utf-8'));
+        const entries = (raw && typeof raw === 'object' && raw.byPath) || {};
+        for (const [path, fields] of Object.entries(entries)) {
+            if (fields && typeof fields === 'object') {
+                byPath.set(path, /** @type {Record<string, unknown>} */ (fields));
+            }
+        }
+    } catch (/** @type {any} */ err) {
+        warn(`Could not read sample-overrides.json: ${err.message}`);
+    }
+    return byPath;
+}
+
+/**
+ * Shallow-merge per-path overrides onto scanned templates. Lets us correct
+ * structural fields (e.g. `framework: "copilot-sdk"` for a sample that lives
+ * under `bring-your-own/` upstream) without touching upstream or hand-editing
+ * the generated catalog. Unknown override paths are logged but never fail
+ * the build — upstream may have moved a sample.
+ *
+ * @param {Array<{path: string} & Record<string, unknown>>} templates
+ * @param {Map<string, Record<string, unknown>>} overrides
+ */
+function applyOverrides(templates, overrides) {
+    if (overrides.size === 0) {
+        return;
+    }
+    /** @type {Set<string>} */
+    const seenPaths = new Set();
+    for (const template of templates) {
+        seenPaths.add(template.path);
+        const fields = overrides.get(template.path);
+        if (fields) {
+            Object.assign(template, fields);
+        }
+    }
+    for (const path of overrides.keys()) {
+        if (!seenPaths.has(path)) {
+            warn(`Override for "${path}" did not match any scanned template; check sample-overrides.json (upstream may have moved or renamed the sample).`);
+        }
+    }
+}
+
+/**
+ * Auto-fill empty displayName and description fields.
+ *
+ * displayName is ALWAYS derived from the template's directory name when empty
+ * — the LLM is not consulted, because folder-name derivation is deterministic
+ * and PM-predictable. Existing PM-curated displayName values are preserved by
+ * the prior `mergeExistingDisplayFields` step, so this only affects newly
+ * scanned templates.
+ *
+ * description is filled by the LLM (when configured) using the sample's
+ * README as context. Without LLM credentials the description stays empty and
+ * gets surfaced as an anomaly in the step summary.
+ *
+ * @param {Array<{displayName: string, description: string, path: string}>} templates
+ * @param {string} commitSha
+ */
+async function autoFillDisplayFields(templates, commitSha) {
+    // Fill displayName first — deterministic, no API calls.
+    for (const template of templates) {
+        if (!template.displayName) {
+            template.displayName = displayNameFromPath(template.path);
+        }
+    }
+
+    const needsDescription = templates.filter((t) => !t.description);
+    if (needsDescription.length === 0) {
+        console.log('All templates already have a description.');
+    } else {
+        const hasLLM = Boolean(AZURE_OPENAI_ENDPOINT && AZURE_OPENAI_API_KEY);
+        if (hasLLM) {
+            console.log(`Generating descriptions for ${needsDescription.length} templates using LLM...`);
+            for (const template of needsDescription) {
+                const readme = await fetchReadme(template.path, commitSha);
+                if (!readme) {
+                    continue;
+                }
+                const result = await generateWithLLM(readme, template.path);
+                if (result?.description) {
+                    template.description = result.description;
+                }
+            }
+        } else {
+            console.log(`${needsDescription.length} templates need a description but no LLM is configured; leaving empty (will be flagged as anomalies).`);
+        }
+    }
+
+    // displayName always gets filled by the folder-name fallback above, so
+    // anomaly detection here is description-only.
+    for (const template of templates) {
+        if (!template.description) {
+            warn(`Template "${template.path}" is missing: description. PM should fill it before merge.`);
+        }
+    }
+}
+
+async function main() {
+    const commitSha = parseCommitShaArg();
+    console.log(`Using commit: ${commitSha}`);
+
+    console.log('Scanning templates...');
+    const templates = await scanTemplates(commitSha);
+    console.log(`Found ${templates.length} templates`);
+
+    // Step 1: Preserve existing PM-curated displayName/description values.
+    mergeExistingDisplayFields(templates);
+
+    // Step 2: Apply source-controlled per-path overrides (structural fields like
+    // `framework` that the upstream tree layout cannot express on its own).
+    applyOverrides(templates, loadOverrides());
+
+    // Step 3: Fill remaining empties — displayName from folder name (always),
+    // description from the LLM when configured.
+    await autoFillDisplayFields(templates, commitSha);
+
+    const dimensions = buildDimensions(templates);
+
+    const catalog = {
+        commitSha,
+        repo: SAMPLES_REPO_URL,
+        generatedAt: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+        dimensions,
+        templateSelection: TEMPLATE_SELECTION,
+        templates,
+    };
+
+    const outputDir = dirname(OUTPUT_PATH);
+    mkdirSync(outputDir, { recursive: true });
+    writeFileSync(OUTPUT_PATH, JSON.stringify(catalog, null, 4) + '\n', 'utf-8');
+
+    console.log(`Wrote ${OUTPUT_PATH}`);
+
+    writeSummary(templates.length);
+}
+
+/**
+ * Append a Markdown report to `$GITHUB_STEP_SUMMARY` (when running in CI) that
+ * surfaces the warnings collected during this run. Reviewers otherwise have
+ * to scroll through raw job logs to notice anomalies like templates missing
+ * descriptions or unmatched overrides. Locally (no env var) this is a no-op.
+ *
+ * @param {number} templateCount
+ */
+function writeSummary(templateCount) {
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (!summaryPath) {
+        if (warnings.length > 0) {
+            console.warn(`\nCatalog generation produced ${warnings.length} warning(s) (see WARN lines above).`);
+        }
+        return;
+    }
+
+    const lines = [
+        '',
+        '## Sample Catalog Generation',
+        '',
+        `- Templates discovered: **${templateCount}**`,
+        `- Warnings emitted: **${warnings.length}**`,
+        '',
+    ];
+
+    if (warnings.length > 0) {
+        lines.push('### ⚠ Anomalies');
+        lines.push('');
+        lines.push('These were logged during generation and may need human attention before merging:');
+        lines.push('');
+        for (const message of warnings) {
+            lines.push(`- ${message}`);
+        }
+        lines.push('');
+    } else {
+        lines.push('No anomalies detected. ✅');
+        lines.push('');
+    }
+
+    try {
+        appendFileSync(summaryPath, lines.join('\n'), 'utf-8');
+    } catch (/** @type {any} */ err) {
+        console.warn(`Could not append to GITHUB_STEP_SUMMARY: ${err.message}`);
+    }
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
diff --git a/.github/workflows/sync-sample-catalog.yml b/.github/workflows/sync-sample-catalog.yml
new file mode 100644
index 0000000..0055a41
--- /dev/null
+++ b/.github/workflows/sync-sample-catalog.yml
@@ -0,0 +1,214 @@
+name: Sync Sample Catalog
+
+on:
+  workflow_dispatch:
+    inputs:
+      commit_sha:
+        description: "Commit SHA from microsoft-foundry/foundry-samples to pin to (leave blank to use the latest main commit)"
+        required: false
+        type: string
+        default: ""
+
+# Least-privilege for the default GITHUB_TOKEN: only what `actions/checkout`
+# needs. All writes (push branch + create PR) are performed via the GitHub
+# App token generated below, not GITHUB_TOKEN.
+permissions:
+  contents: read
+
+# A single in-flight sync at a time — a re-trigger cancels any earlier run
+# rather than racing it for the same PR branch.
+concurrency:
+  group: sync-sample-catalog-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    env:
+      PR_LABEL_CANDIDATES: |
+        automated-pr
+        area:samples
+        area:hosted-agent
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.SYNC_APP_ID }}
+          private-key: ${{ secrets.SYNC_APP_PRIVATE_KEY }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Resolve commit SHA
+        id: resolve-sha
+        shell: bash
+        env:
+          INPUT_SHA: ${{ inputs.commit_sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          if [[ -n "$INPUT_SHA" ]]; then
+            sha="$INPUT_SHA"
+            source="user-supplied input"
+          else
+            # No SHA provided: pin to the current tip of foundry-samples@main
+            # so the dispatcher doesn't have to look it up by hand.
+            sha=$(gh api repos/microsoft-foundry/foundry-samples/commits/main --jq .sha)
+            source="latest microsoft-foundry/foundry-samples@main"
+          fi
+          if [[ ! "$sha" =~ ^[0-9a-f]{7,40}$ ]]; then
+            echo "Resolved SHA is not a valid git object: $sha" >&2
+            exit 1
+          fi
+          echo "Using SHA $sha (source: $source)"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          echo "- Pinned SHA: \`$sha\` ($source)" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Generate sample catalog
+        env:
+          REPO_ROOT: ${{ github.workspace }}
+          GITHUB_TOKEN: ${{ github.token }}
+          AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
+          AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
+          AZURE_OPENAI_DEPLOYMENT: ${{ secrets.AZURE_OPENAI_DEPLOYMENT }}
+        run: node .github/scripts/generate_sample_catalog.mjs "${{ steps.resolve-sha.outputs.sha }}"
+
+      - name: Detect catalog changes
+        id: diff
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          catalog_file="samples/hosted-agent/sample-catalog.json"
+
+          if [[ ! -f "$catalog_file" ]]; then
+            echo "Catalog file not generated."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Stage the file so git diff detects both new and modified files
+          git add "$catalog_file"
+
+          if git diff --cached --quiet -- "$catalog_file"; then
+            echo "No changes to sample catalog."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Catalog has changes:"
+          git diff --cached --stat -- "$catalog_file"
+
+          {
+            echo "## Sample Catalog Sync"
+            echo
+            echo "The sample catalog was regenerated from \`microsoft-foundry/foundry-samples\`."
+            echo
+            echo "### Changed files"
+            echo "- \`$catalog_file\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve pull request labels
+        if: steps.diff.outputs.has_changes == 'true'
+        id: labels
+        shell: bash
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+
+          existing_labels=$(gh api --paginate repos/${{ github.repository }}/labels --jq '.[].name')
+          matched_labels=""
+
+          while IFS= read -r candidate; do
+            if [[ -z "$candidate" ]]; then
+              continue
+            fi
+
+            if grep -Fqx "$candidate" <<< "$existing_labels"; then
+              matched_labels+="$candidate"
+              matched_labels+=$'\n'
+            fi
+          done <<< "$PR_LABEL_CANDIDATES"
+
+          {
+            echo "labels<<EOF"
+            printf '%s' "$matched_labels"
+            echo
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Generate PR branch name
+        if: steps.diff.outputs.has_changes == 'true'
+        id: branch
+        shell: bash
+        run: |
+          date_suffix=$(date -u +%Y%m%d)
+          echo "name=ci/sync-sample-catalog-${{ github.ref_name }}-${date_suffix}" >> "$GITHUB_OUTPUT"
+
+      - name: Create draft pull request
+        if: steps.diff.outputs.has_changes == 'true'
+        id: cpr
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          branch: ${{ steps.branch.outputs.name }}
+          base: ${{ github.ref_name }}
+          delete-branch: true
+          draft: always-true
+          commit-message: |
+            ci: sync sample catalog from foundry-samples (${{ github.ref_name }})
+          title: "ci: sync sample catalog from foundry-samples (${{ github.ref_name }})"
+          body: |
+            ## Summary
+            This automated draft PR updates `samples/hosted-agent/sample-catalog.json` by scanning
+            the `microsoft-foundry/foundry-samples` repository for hosted-agent sample templates.
+
+            ## What changed
+            - New templates added or removed based on the upstream repo structure.
+            - `commitSha` pinned to the upstream commit supplied via the `commit_sha` workflow input.
+            - `requiresModel` and `protocol` values re-derived from each sample's `agent.yaml`.
+            - `displayName` derived from each template's folder name; `description` LLM-generated when empty.
+            - PM-edited `displayName` and `description` values are preserved from the previous catalog.
+
+            ## Reviewer Checks
+            - Confirm new templates have correct `language`, `framework`, and `protocol` values.
+            - Review the auto-generated `description` for any new templates.
+            - Confirm no PM-edited display fields were accidentally lost.
+          labels: ${{ steps.labels.outputs.labels }}
+          add-paths: |
+            samples/hosted-agent/sample-catalog.json
+
+      - name: Report PR result
+        if: steps.diff.outputs.has_changes == 'true'
+        shell: bash
+        env:
+          PR_OPERATION: ${{ steps.cpr.outputs.pull-request-operation }}
+          PR_URL: ${{ steps.cpr.outputs.pull-request-url }}
+          PR_NUMBER: ${{ steps.cpr.outputs.pull-request-number }}
+        run: |
+          echo "PR operation: $PR_OPERATION"
+          echo "PR URL: $PR_URL"
+
+          {
+            echo
+            echo "## Pull Request"
+            echo
+            if [[ -n "$PR_URL" ]]; then
+              echo "- Operation: \`$PR_OPERATION\`"
+              echo "- PR: [#${PR_NUMBER:-?}]($PR_URL)"
+            else
+              echo "- No pull request was created or updated (peter-evans/create-pull-request returned no URL)."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/samples/hosted-agent/sample-catalog.json b/samples/hosted-agent/sample-catalog.json
new file mode 100644
index 0000000..4dd5dac
--- /dev/null
+++ b/samples/hosted-agent/sample-catalog.json
@@ -0,0 +1,61 @@
+{
+    "commitSha": "a1d8b8f19e5e552283b3e91208d44f4b72553d44",
+    "repo": "https://github.com/microsoft-foundry/foundry-samples/",
+    "generatedAt": "2026-07-07T09:51:25Z",
+    "dimensions": {
+        "language": {
+            "title": "Select a Language",
+            "placeholder": "Choose the language for your agent",
+            "options": [
+                {
+                    "id": "python",
+                    "displayName": "Python"
+                }
+            ]
+        },
+        "framework": {
+            "title": "Select a Framework",
+            "placeholder": "Choose the framework for your agent",
+            "options": [
+                {
+                    "id": "bring-your-own",
+                    "displayName": "Bring Your Own"
+                }
+            ]
+        },
+        "protocol": {
+            "title": "Select a Protocol",
+            "placeholder": "Choose the protocol for your agent",
+            "options": [
+                {
+                    "id": "invocations",
+                    "displayName": "Invocations API"
+                }
+            ]
+        }
+    },
+    "templateSelection": {
+        "title": "Select a Template",
+        "placeholder": "Choose a template for your agent"
+    },
+    "templates": [
+        {
+            "language": "python",
+            "framework": "bring-your-own",
+            "protocol": "invocations",
+            "displayName": "Diagnostic Agent",
+            "description": "Runs network probes on hostnames and returns a JSON report of connectivity results.",
+            "path": "samples/python/hosted-agents/bring-your-own/invocations/diagnostic-agent",
+            "requiresModel": false
+        },
+        {
+            "language": "python",
+            "framework": "bring-your-own",
+            "protocol": "invocations",
+            "displayName": "Langgraph Chat",
+            "description": "Conversational agent with session history and built-in time and calculator tools.",
+            "path": "samples/python/hosted-agents/bring-your-own/invocations/langgraph-chat",
+            "requiresModel": true
+        }
+    ]
+}
diff --git a/samples/hosted-agent/sample-overrides.json b/samples/hosted-agent/sample-overrides.json
new file mode 100644
index 0000000..43a3b06
--- /dev/null
+++ b/samples/hosted-agent/sample-overrides.json
@@ -0,0 +1,8 @@
+{
+    "byPath": {
+        "samples/python/hosted-agents/bring-your-own/invocations/github-copilot": {
+            "framework": "copilot-sdk",
+            "requiresModel": false
+        }
+    }
+}