@agent-native/core 0.129.1 → 0.130.0

package/dist/cli/create.js

@@ -73,6 +73,11 @@ const HEADLESS_OPTION = {
     label: "Headless",
     hint: "Action-first app with one hello primitive and no UI shell",
 };
+const COMMUNITY_OPTION = {
+    name: "community",
+    label: "Community template",
+    hint: "Install a third-party Agent Native app from a public GitHub repository",
+};
 /**
  * Main entry for `agent-native create [name]`.
  *
@@ -138,6 +143,11 @@ export async function createApp(name, opts) {
             await createStandaloneApp(name, { ...opts, template: shape }, clack);
             return;
         }
+        if (shape === "community") {
+            const template = await promptCommunityTemplate(clack);
+            await createStandaloneApp(name, { ...opts, template }, clack);
+            return;
+        }
         // shape === "template" → full app(s) in a workspace.
         await createWorkspaceInteractive(name, opts, clack);
         return;
@@ -150,6 +160,7 @@ export async function createApp(name, opts) {
  * choice made here implies the project structure, so we deliberately avoid a
  * separate "workspace or standalone?" question:
  *   - "template" → full app(s) in a workspace (the multi-select picker)
+ *   - "community" → a single standalone app from a public GitHub repository
  *   - "chat"     → a single standalone chat UI app
  *   - "headless" → a single standalone action-first app with no UI shell
  * Chat and headless are standalone on purpose: a monorepo is unnecessary
@@ -176,8 +187,13 @@ function startShapePromptOptions() {
             },
             {
                 value: "template",
-                label: "Full template(s)",
-                hint: "Clone complete apps (Mail, Calendar, Slides, ...) into a workspace",
+                label: "First-party template(s)",
+                hint: "Clone official apps (Mail, Calendar, Slides, ...) into a workspace",
+            },
+            {
+                value: COMMUNITY_OPTION.name,
+                label: COMMUNITY_OPTION.label,
+                hint: COMMUNITY_OPTION.hint,
             },
             {
                 value: "headless",
@@ -187,6 +203,52 @@ function startShapePromptOptions() {
         ],
     };
 }
+async function promptCommunityTemplate(clack) {
+    const selection = await clack.text({
+        message: "Which community template do you want to install?",
+        placeholder: "https://github.com/owner/repo[?app=id][#ref]",
+        validate(value) {
+            try {
+                parseCommunityPromptValue(String(value ?? ""));
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+        },
+    });
+    if (clack.isCancel(selection)) {
+        clack.cancel("Cancelled.");
+        process.exit(0);
+    }
+    return parseCommunityPromptValue(String(selection)).canonical;
+}
+async function promptCommunityWorkspaceApp(apps, clack) {
+    const selection = await clack.select({
+        message: "Which app from this community workspace do you want to install?",
+        options: apps.map((app) => ({
+            value: app.name,
+            label: app.label,
+            hint: app.label === app.name ? undefined : app.name,
+        })),
+    });
+    if (clack.isCancel(selection)) {
+        clack.cancel("Cancelled.");
+        process.exit(0);
+    }
+    return String(selection);
+}
+function communityScaffoldOptions(clack, shape, destinationAppName, targetWorkspaceCoreName) {
+    return {
+        shape,
+        destinationAppName,
+        targetWorkspaceCoreName,
+        ...(process.stdin.isTTY && process.stdout.isTTY
+            ? {
+                selectCommunityWorkspaceApp: (apps) => promptCommunityWorkspaceApp(apps, clack),
+            }
+            : {}),
+    };
+}
 /**
  * Validate a project name supplied on the command line. Mirrors the rule in
  * `promptNameIfMissing` so an invalid name is rejected before any interactive
@@ -233,6 +295,9 @@ async function createWorkspaceInteractive(name, opts, clack) {
         process.exit(1);
     }
     const s = clack.spinner();
+    for (const template of templates) {
+        showCommunityTemplateTrustNote(template, clack);
+    }
     s.start(`Scaffolding workspace "${name}"...`);
     const appNames = new Set();
     const scaffoldedApps = [];
@@ -254,17 +319,22 @@ async function createWorkspaceInteractive(name, opts, clack) {
             // Distinguish download vs local copy in the spinner so a multi-second
             // GitHub fetch doesn't look like a frozen "Scaffolding..." message.
             // Mirrors the local-vs-remote decision inside scaffoldAppTemplate.
-            const willDownload = templateName !== "headless" && templateName.startsWith("github:")
-                ? true
-                : !findLocalTemplate(normalizeTemplateName(templateName));
+            const willDownload = templateName !== "headless" &&
+                (isCommunityTemplateSelection(templateName) ||
+                    !findLocalTemplate(normalizeTemplateName(templateName)));
             s.message(willDownload
                 ? `Downloading ${titleCase(appName)} template (${i + 1}/${templates.length})...`
                 : `Scaffolding ${titleCase(appName)} (${i + 1}/${templates.length})...`);
             const appDir = path.join(targetDir, "apps", appName);
-            await scaffoldAppTemplate(appDir, templateName);
+            const resolution = await scaffoldAppTemplate(appDir, templateName, communityScaffoldOptions(clack, "workspace", appName, workspaceCoreName));
             s.message(`Configuring ${titleCase(appName)} (${i + 1}/${templates.length})...`);
             replacePlaceholders(appDir, appName, appTitleForScaffold(appName), name);
-            rewriteTrackingAppId(appDir, appName, templateName);
+            if (resolution.sourceIdentity) {
+                applyScaffoldIdentity(appDir, appName, templateName, resolution.sourceIdentity);
+            }
+            else {
+                rewriteTrackingAppId(appDir, appName, templateName);
+            }
             workspacifyApp({
                 appDir,
                 appName,
@@ -275,8 +345,11 @@ async function createWorkspaceInteractive(name, opts, clack) {
                 dispatchDependencyVersion: getDispatchDependencyVersion(),
                 toolkitDependencyVersion: getToolkitDependencyVersion(),
             });
-            fixPackageJsonName(appDir, appName, templateName);
-            fixWebManifestName(appDir, appName, templateName);
+            fixPackageJsonName(appDir, appName, templateName, {
+                ...resolution,
+                shape: "workspace",
+            });
+            fixWebManifestName(appDir, appName, templateName, resolution.sourceIdentity);
             rewriteNetlifyToml(appDir, appName, "workspace");
             renameGitignore(appDir);
             // Each app owns its own .claude / .agents symlinks.
@@ -337,10 +410,10 @@ async function createWorkspaceInteractive(name, opts, clack) {
 }
 function workspaceAppNameForTemplateSelection(templateName) {
     const normalized = normalizeTemplateName(templateName);
-    if (!normalized.startsWith("github:"))
+    const community = parseCommunityTemplateSelection(normalized, false);
+    if (!community)
         return templateName;
-    const repo = normalized.slice("github:".length).trim();
-    const repoName = repo.split("/").filter(Boolean).pop() ?? "app";
+    const repoName = community.app ?? community.repo.split("/").pop() ?? "app";
     let appName = repoName
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, "-")
@@ -499,11 +572,17 @@ async function scaffoldOneAppIntoWorkspace(workspace, appName, templateName, cla
         process.exit(1);
     }
     const s = clack.spinner();
+    showCommunityTemplateTrustNote(templateName, clack);
     s.start(`Working... no action needed. Scaffolding apps/${appName} from ${templateName}.`);
     try {
-        const resolution = await scaffoldAppTemplate(appDir, templateName);
+        const resolution = await scaffoldAppTemplate(appDir, templateName, communityScaffoldOptions(clack, "workspace", appName, workspace.workspaceCoreName));
         replacePlaceholders(appDir, appName, appTitleForScaffold(appName), path.basename(workspace.workspaceRoot));
-        rewriteTrackingAppId(appDir, appName, templateName);
+        if (resolution.sourceIdentity) {
+            applyScaffoldIdentity(appDir, appName, templateName, resolution.sourceIdentity);
+        }
+        else {
+            rewriteTrackingAppId(appDir, appName, templateName);
+        }
         workspacifyApp({
             appDir,
             appName,
@@ -518,7 +597,7 @@ async function scaffoldOneAppIntoWorkspace(workspace, appName, templateName, cla
             ...resolution,
             shape: "workspace",
         });
-        fixWebManifestName(appDir, appName, templateName);
+        fixWebManifestName(appDir, appName, templateName, resolution.sourceIdentity);
         rewriteNetlifyToml(appDir, appName, "workspace");
         renameGitignore(appDir);
         setupAgentSymlinks(appDir);
@@ -556,20 +635,7 @@ async function createStandaloneApp(name, opts, clack) {
     if (!template) {
         const picked = await clack.select({
             message: "Which template would you like to use?",
-            options: [
-                {
-                    value: HEADLESS_OPTION.name,
-                    label: HEADLESS_OPTION.label,
-                    hint: HEADLESS_OPTION.hint,
-                },
-                ...onRampFirst(coreTemplates())
-                    .filter((t) => t.name !== HEADLESS_OPTION.name)
-                    .map((t) => ({
-                    value: t.name,
-                    label: t.label,
-                    hint: t.hint,
-                })),
-            ],
+            options: standaloneTemplatePromptOptions(),
         });
         if (clack.isCancel(picked)) {
             clack.cancel("Cancelled.");
@@ -578,12 +644,17 @@ async function createStandaloneApp(name, opts, clack) {
         template = picked;
     }
     template = normalizeTemplateName(template);
+    if (template === COMMUNITY_OPTION.name) {
+        template = await promptCommunityTemplate(clack);
+    }
     const s = clack.spinner();
+    showCommunityTemplateTrustNote(template, clack);
     s.start(template === "headless"
         ? "Scaffolding the headless agent app..."
-        : `Downloading the ${template} template from GitHub...`);
+        : (communityTemplateDownloadMessage(template) ??
+            `Downloading the ${template} template from GitHub...`));
     try {
-        const resolution = await scaffoldAppTemplate(targetDir, template);
+        const resolution = await scaffoldAppTemplate(targetDir, template, communityScaffoldOptions(clack, "standalone", name));
         s.message(`Setting up ${name}…`);
         postProcessStandalone(name, targetDir, template, resolution);
         s.stop("App created!");
@@ -611,6 +682,27 @@ async function createStandaloneApp(name, opts, clack) {
         clack.outro(`Done! Next steps:\n\n  cd ${name}\n  pnpm install\n  pnpm dev`);
     }
 }
+function standaloneTemplatePromptOptions() {
+    return [
+        {
+            value: HEADLESS_OPTION.name,
+            label: HEADLESS_OPTION.label,
+            hint: HEADLESS_OPTION.hint,
+        },
+        ...onRampFirst(coreTemplates())
+            .filter((t) => t.name !== HEADLESS_OPTION.name)
+            .map((t) => ({
+            value: t.name,
+            label: t.label,
+            hint: t.hint,
+        })),
+        {
+            value: COMMUNITY_OPTION.name,
+            label: COMMUNITY_OPTION.label,
+            hint: COMMUNITY_OPTION.hint,
+        },
+    ];
+}
 /**
  * Remove a partially-scaffolded target directory after a scaffold failure so a
  * retry doesn't hit the "Directory already exists" guard. Best-effort — the
@@ -630,11 +722,12 @@ function cleanupOnFailure(targetDir) {
 /**
  * Scaffold a single app template into `targetDir`. Resolves:
  *   - "headless" / legacy "blank" → bundled action-first template
- *   - "github:user/repo" → download the whole repo
+ *   - "community:user/repo[#ref]" → download and validate the whole repo
+ *   - legacy "github:user/repo[#ref]" and clean GitHub HTTPS URLs → community
  *   - first-party template name → use a bundled copy or download its subdir
  *     from BuilderIO/agent-native
  */
-async function scaffoldAppTemplate(targetDir, template) {
+async function scaffoldAppTemplate(targetDir, template, options = {}) {
     fs.mkdirSync(path.dirname(targetDir), { recursive: true });
     // Normalize legacy / renamed aliases.
     let resolved = normalizeTemplateName(template);
@@ -650,13 +743,38 @@ async function scaffoldAppTemplate(targetDir, template) {
             templateRef: getGitHubTemplateRefCandidates()[0],
         };
     }
-    if (resolved.startsWith("github:")) {
-        const repo = resolved.slice("github:".length);
-        await downloadGitHubRepo(repo, targetDir);
-        return {};
+    const community = parseCommunityTemplateSelection(resolved, false);
+    if (community) {
+        const stagingDir = path.join(path.dirname(targetDir), `.agent-native-community-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        try {
+            const ref = await downloadGitHubRepo(community.repo, stagingDir, community.ref);
+            const source = await resolveCommunityTemplateSource(stagingDir, community, options);
+            copyDir(source.sourceDir, targetDir);
+            if (source.workspaceRoot) {
+                normalizeCommunityWorkspaceAppDependencies(targetDir, source.workspaceRoot, {
+                    shape: options.shape,
+                    destinationAppName: options.destinationAppName ?? path.basename(targetDir),
+                    targetWorkspaceCoreName: options.targetWorkspaceCoreName,
+                    sourceIdentity: source.sourceIdentity,
+                });
+            }
+            return {
+                templateSource: "github",
+                templateRef: ref,
+                sourceIdentity: source.sourceIdentity,
+                communityTemplate: {
+                    source: `https://github.com/${community.repo}`,
+                    ref,
+                    ...(source.app ? { app: source.app } : {}),
+                },
+            };
+        }
+        finally {
+            fs.rmSync(stagingDir, { recursive: true, force: true });
+        }
     }
     if (!getTemplate(resolved)) {
-        throw new Error(`Unknown template "${template}". Known: ${allTemplateNames().join(", ")} — or use github:user/repo for community templates.`);
+        throw new Error(`Unknown template "${template}". Known first-party templates: ${allTemplateNames().join(", ")}. For a community template, use community:owner/repo.`);
     }
     // If running from the framework monorepo with a local templates/ dir, use
     // that. Otherwise download from GitHub. This keeps `agent-native create`
@@ -718,8 +836,149 @@ function normalizeTemplateName(template) {
     if (template === "image" || template === "images" || template === "asset") {
         return "assets";
     }
+    const community = parseCommunityTemplateSelection(template, false);
+    if (community)
+        return community.canonical;
     return template;
 }
+function parseCommunityTemplateSelection(selection, required = true) {
+    const value = selection.trim();
+    let raw;
+    if (value.startsWith("community:")) {
+        raw = value.slice("community:".length).trim();
+    }
+    else if (value.startsWith("github:")) {
+        raw = value.slice("github:".length).trim();
+    }
+    else if (value.startsWith("https://github.com/")) {
+        raw = value;
+    }
+    else {
+        if (!required)
+            return undefined;
+        throw new ValidationError(`Invalid community template "${selection}". Use community:owner/repo, optionally with #branch, #tag, or #commit.`);
+    }
+    if (!raw) {
+        throw new ValidationError("A community template repository is required. Use owner/repo or a GitHub URL.");
+    }
+    let repo;
+    let app;
+    let ref;
+    if (raw.includes("://")) {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            throw new ValidationError(`Invalid GitHub repository URL "${raw}". Expected https://github.com/owner/repo.`);
+        }
+        const parts = url.pathname.split("/").filter(Boolean);
+        if (url.protocol !== "https:" ||
+            url.hostname !== "github.com" ||
+            url.port ||
+            url.username ||
+            url.password ||
+            parts.length !== 2) {
+            throw new ValidationError(`Invalid GitHub repository URL "${raw}". Expected https://github.com/owner/repo with an optional #ref.`);
+        }
+        repo = `${parts[0]}/${parts[1].replace(/\.git$/, "")}`;
+        app = parseCommunityAppSearchParams(url.searchParams, raw);
+        if (url.hash.length > 1) {
+            try {
+                ref = decodeURIComponent(url.hash.slice(1));
+            }
+            catch {
+                throw new ValidationError(`Invalid encoded Git ref in "${raw}".`);
+            }
+        }
+    }
+    else {
+        const hash = raw.indexOf("#");
+        const beforeHash = hash === -1 ? raw : raw.slice(0, hash);
+        const query = beforeHash.indexOf("?");
+        repo = (query === -1 ? beforeHash : beforeHash.slice(0, query)).replace(/\.git$/, "");
+        if (query !== -1) {
+            app = parseCommunityAppSearchParams(new URLSearchParams(beforeHash.slice(query + 1)), raw);
+        }
+        ref = hash === -1 ? undefined : raw.slice(hash + 1);
+    }
+    validateRepoName(repo);
+    if (app !== undefined)
+        validateCommunityAppSelector(app);
+    if (ref !== undefined)
+        validateGitRef(ref);
+    return {
+        repo,
+        ...(app ? { app } : {}),
+        ...(ref ? { ref } : {}),
+        canonical: `community:${repo}${app ? `?app=${app}` : ""}${ref ? `#${ref}` : ""}`,
+    };
+}
+function parseCommunityAppSearchParams(params, source) {
+    const entries = [...params.entries()];
+    if (entries.length === 0)
+        return undefined;
+    if (entries.length !== 1 || entries[0]?.[0] !== "app" || !entries[0][1]) {
+        throw new ValidationError(`Invalid community template selector in "${source}". Only ?app=<app-name> is supported.`);
+    }
+    return entries[0][1];
+}
+function validateCommunityAppSelector(app) {
+    if (app === "dispatch") {
+        throw new ValidationError("Dispatch cannot be installed from a community workspace.");
+    }
+    const error = getWorkspaceAppIdValidationError(app);
+    if (error)
+        throw new ValidationError(error);
+}
+function isCommunityTemplateSelection(selection) {
+    return parseCommunityTemplateSelection(selection, false) !== undefined;
+}
+function parseCommunityPromptValue(value) {
+    const trimmed = value.trim();
+    const selection = trimmed.startsWith("community:") ||
+        trimmed.startsWith("github:") ||
+        trimmed.startsWith("https://github.com/")
+        ? trimmed
+        : `community:${trimmed}`;
+    return parseCommunityTemplateSelection(selection);
+}
+function validateGitRef(ref) {
+    if (!ref ||
+        !/^[a-zA-Z0-9][a-zA-Z0-9._/+-]*$/.test(ref) ||
+        ref.includes("..") ||
+        ref.includes("//") ||
+        ref.includes("@{") ||
+        ref.endsWith("/") ||
+        ref.endsWith(".") ||
+        ref.split("/").some((part) => !part || part.endsWith(".lock"))) {
+        throw new ValidationError(`Invalid Git ref "${ref}". Use a branch, tag, or commit SHA without spaces or Git ref control characters.`);
+    }
+}
+function communityTemplateTrustMessage(selection) {
+    const community = parseCommunityTemplateSelection(selection, false);
+    if (!community)
+        return undefined;
+    return [
+        `${community.repo} is third-party code and is not reviewed or maintained by Agent Native.`,
+        "The CLI downloads source only; it does not install dependencies or run template scripts.",
+        "Review the generated files before running pnpm install.",
+        community.ref
+            ? `Requested ref: ${community.ref}`
+            : "No ref supplied; the CLI will try main, then master.",
+    ].join("\n");
+}
+function communityTemplateDownloadMessage(selection) {
+    const community = parseCommunityTemplateSelection(selection, false);
+    return community
+        ? `Downloading community template ${community.repo} from GitHub...`
+        : undefined;
+}
+function showCommunityTemplateTrustNote(selection, clack) {
+    const message = communityTemplateTrustMessage(selection);
+    if (message)
+        clack.note(message, "Community template — review before use");
+}
 /**
  * Find a local packages/<name> directory (for framework development).
  * Returns undefined when running as a published npm package.
@@ -867,13 +1126,12 @@ async function scaffoldRequiredPackages(templateNames, workspaceRoot) {
 function postProcessStandalone(name, targetDir, templateName, resolution) {
     const appTitle = appTitleForScaffold(name);
     replacePlaceholders(targetDir, name, appTitle);
-    rewriteTrackingAppId(targetDir, name, templateName);
-    rewriteAgentChatAppId(targetDir, name, templateName);
+    applyScaffoldIdentity(targetDir, name, templateName, resolution?.sourceIdentity);
     fixPackageJsonName(targetDir, name, templateName, {
         ...resolution,
         shape: "standalone",
     });
-    fixWebManifestName(targetDir, name, templateName);
+    fixWebManifestName(targetDir, name, templateName, resolution?.sourceIdentity);
     rewriteNetlifyToml(targetDir, name, "standalone");
     for (const base of ["learnings"]) {
         const defaultsFile = path.join(targetDir, `${base}.defaults.md`);
@@ -1157,12 +1415,14 @@ export function detectWorkspace(startDir) {
 }
 export { parseWorkspaceScope };
 /** @internal — exported for E2E tests */
-export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
+export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, standaloneTemplatePromptOptions as _standaloneTemplatePromptOptions, parseCommunityTemplateSelection as _parseCommunityTemplateSelection, communityTemplateTrustMessage as _communityTemplateTrustMessage, communityTemplateTarballUrl as _communityTemplateTarballUrl, assertCommunityTemplateRoot as _assertCommunityTemplateRoot, assertSafeCommunityArchiveListing as _assertSafeCommunityArchiveListing, validateCommunityArchive as _validateCommunityArchive, resolveCommunityTemplateSource as _resolveCommunityTemplateSource, discoverCommunityWorkspaceApps as _discoverCommunityWorkspaceApps, normalizeCommunityWorkspaceAppDependencies as _normalizeCommunityWorkspaceAppDependencies, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, applyScaffoldIdentity as _applyScaffoldIdentity, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
 /* ─────────────────────────────────────────────────────────────────────────
  * Download / copy helpers
  * ───────────────────────────────────────────────────────────────────────── */
 function validateRepoName(repo) {
-    if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) {
+    const parts = repo.split("/");
+    if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo) ||
+        parts.some((part) => part === "." || part === "..")) {
         throw new ValidationError(`Invalid repository name "${repo}". Expected format: user/repo`);
     }
 }
@@ -1173,7 +1433,18 @@ function tarExtractArgs(tarPath, destDir, options = {}) {
             pattern,
         ])
         : [];
-    return ["xzf", tarPath, "--strip-components=1", ...excludes, "-C", destDir];
+    const safeOwnership = options.untrustedCommunityArchive
+        ? ["--no-same-owner", "--no-same-permissions"]
+        : [];
+    return [
+        "xzf",
+        tarPath,
+        "--strip-components=1",
+        ...safeOwnership,
+        ...excludes,
+        "-C",
+        destDir,
+    ];
 }
 function execFileBuffer(command, args, options) {
     return new Promise((resolve, reject) => {
@@ -1208,6 +1479,9 @@ async function downloadAndExtract(url, destDir, options = {}) {
     const tarPath = path.join(destDir, ".download.tar.gz");
     fs.writeFileSync(tarPath, tarball);
     try {
+        if (options.untrustedCommunityArchive) {
+            validateCommunityArchive(tarPath);
+        }
         execFileSync("tar", tarExtractArgs(tarPath, destDir, options), {
             stdio: "pipe",
         });
@@ -1216,6 +1490,40 @@ async function downloadAndExtract(url, destDir, options = {}) {
         fs.unlinkSync(tarPath);
     }
 }
+function validateCommunityArchive(tarPath) {
+    const listing = execFileSync("tar", ["tvzf", tarPath], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    assertSafeCommunityArchiveListing(listing);
+}
+function assertSafeCommunityArchiveListing(listing) {
+    const unsafeEntry = listing.split(/\r?\n/).find((line) => {
+        if (line.startsWith("h"))
+            return true;
+        if (!line.startsWith("l"))
+            return false;
+        return !isCanonicalAgentSymlinkListing(line);
+    });
+    if (unsafeEntry) {
+        throw new ValidationError("Community template archives may only contain Agent Native's canonical internal symlinks (CLAUDE.md and .claude/skills). Remove other symbolic or hard links and try again.");
+    }
+}
+function isCanonicalAgentSymlinkListing(line) {
+    const match = line.match(/\s(\S+)\s+->\s+(\S+)\s*$/);
+    if (!match)
+        return false;
+    const archivePath = match[1];
+    const target = match[2];
+    const parts = archivePath.split("/");
+    if (parts.some((part) => !part || part === "." || part === ".." || part.includes("\\"))) {
+        return false;
+    }
+    return ((parts.at(-1) === "CLAUDE.md" && target === "AGENTS.md") ||
+        (parts.at(-2) === ".claude" &&
+            parts.at(-1) === "skills" &&
+            target === "../.agents/skills"));
+}
 /** Resolves to the ref that actually succeeded so callers can record it. */
 async function downloadGitHubSubdir(repo, subdir, targetDir, refOverride) {
     validateRepoName(repo);
@@ -1249,10 +1557,332 @@ async function downloadGitHubSubdir(repo, subdir, targetDir, refOverride) {
     }
     throw new Error(`Failed to download templates from ${repo}. Tried refs:\n${errors.join("\n")}`);
 }
-async function downloadGitHubRepo(repo, targetDir) {
+async function downloadGitHubRepo(repo, targetDir, requestedRef) {
     validateRepoName(repo);
-    const tarUrl = githubTarballUrl(repo, "main", "branch");
-    await downloadAndExtract(tarUrl, targetDir);
+    const refs = requestedRef ? [requestedRef] : ["main", "master"];
+    const errors = [];
+    for (const ref of refs) {
+        try {
+            await downloadAndExtract(communityTemplateTarballUrl(repo, ref), targetDir, { untrustedCommunityArchive: true });
+            return ref;
+        }
+        catch (error) {
+            errors.push(`  ${ref}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
+            cleanupOnFailure(targetDir);
+        }
+    }
+    throw new Error(`Failed to download community template ${repo}. Tried refs:\n${errors.join("\n")}\nThe repository must be public, and the requested branch, tag, or commit must exist.`);
+}
+function communityTemplateTarballUrl(repo, ref) {
+    return `https://codeload.github.com/${repo}/tar.gz/${encodeURIComponent(ref)}`;
+}
+function assertCommunityTemplateRoot(targetDir, repo) {
+    const packagePath = path.join(targetDir, "package.json");
+    if (!fs.existsSync(packagePath)) {
+        throw new ValidationError(`Community template ${repo} is not an Agent Native app at the repository root: package.json was not found. Point to a repository whose root is the app.`);
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+    }
+    catch {
+        throw new ValidationError(`Community template ${repo} has an unreadable package.json at the repository root.`);
+    }
+    const dependencyGroups = [
+        pkg.dependencies,
+        pkg.devDependencies,
+        pkg.peerDependencies,
+    ];
+    const usesAgentNativeCore = dependencyGroups.some((group) => group !== null &&
+        typeof group === "object" &&
+        !Array.isArray(group) &&
+        typeof group["@agent-native/core"] ===
+            "string");
+    if (!usesAgentNativeCore) {
+        throw new ValidationError(`Community template ${repo} is not an Agent Native app at the repository root. Its package.json must directly depend on @agent-native/core in dependencies, devDependencies, or peerDependencies.`);
+    }
+}
+async function resolveCommunityTemplateSource(stagingDir, selection, options = {}) {
+    const rootPkg = readPackageJsonObject(path.join(stagingDir, "package.json"));
+    const agentNative = rootPkg?.["agent-native"] &&
+        typeof rootPkg["agent-native"] === "object" &&
+        !Array.isArray(rootPkg["agent-native"])
+        ? rootPkg["agent-native"]
+        : undefined;
+    const hasWorkspaceCoreMarker = agentNative && Object.hasOwn(agentNative, "workspaceCore");
+    const workspaceCore = agentNative?.workspaceCore;
+    if (hasWorkspaceCoreMarker &&
+        (typeof workspaceCore !== "string" || !workspaceCore.trim())) {
+        throw new ValidationError(`Community repository ${selection.repo} has invalid agent-native.workspaceCore metadata. Expected a non-empty workspace package name.`);
+    }
+    const isWorkspace = typeof workspaceCore === "string";
+    if (!isWorkspace) {
+        assertCommunityTemplateRoot(stagingDir, selection.repo);
+        const sourceIdentity = readCommunitySourceIdentity(stagingDir, selection.repo);
+        if (selection.app) {
+            throw new ValidationError(`Community repository ${selection.repo} is a single app at its root. Remove ?app=${selection.app}; app selectors are only for workspace repositories.`);
+        }
+        return { sourceDir: stagingDir, sourceIdentity };
+    }
+    const workspaceApps = discoverCommunityWorkspaceApps(stagingDir);
+    if (workspaceApps.length === 0) {
+        throw new ValidationError(`Community workspace ${selection.repo} has no installable apps. Dispatch cannot be installed from a community workspace, and apps must directly depend on @agent-native/core.`);
+    }
+    let selectedApp = selection.app;
+    if (!selectedApp) {
+        if (!options.selectCommunityWorkspaceApp) {
+            throw new ValidationError(`Community workspace ${selection.repo} requires an app selection, but no interactive terminal is available. Select one with ?app=<app-name>. Available apps: ${workspaceApps.map((app) => app.name).join(", ")}.`);
+        }
+        else {
+            selectedApp = await options.selectCommunityWorkspaceApp(workspaceApps.map(({ name, label }) => ({ name, label })));
+            validateCommunityAppSelector(selectedApp);
+        }
+    }
+    const selected = workspaceApps.find((app) => app.name === selectedApp);
+    if (!selected) {
+        throw new ValidationError(`App "${selectedApp}" was not found in community workspace ${selection.repo}. Available apps: ${workspaceApps.map((app) => app.name).join(", ")}.`);
+    }
+    return {
+        sourceDir: selected.dir,
+        sourceIdentity: selected.sourceIdentity,
+        app: selected.name,
+        workspaceRoot: stagingDir,
+    };
+}
+function discoverCommunityWorkspaceApps(workspaceRoot) {
+    const appsDir = path.join(workspaceRoot, "apps");
+    if (!fs.existsSync(appsDir))
+        return [];
+    return fs
+        .readdirSync(appsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .flatMap((entry) => {
+        const appDir = path.join(appsDir, entry.name);
+        const packagePath = path.join(appDir, "package.json");
+        if (!fs.existsSync(packagePath))
+            return [];
+        const pkg = readPackageJsonObject(packagePath);
+        if (!pkg) {
+            throw new ValidationError(`Community workspace app "${entry.name}" has an unreadable package.json.`);
+        }
+        if (getWorkspaceAppIdValidationError(entry.name))
+            return [];
+        if (!packageDirectlyDependsOnAgentNativeCore(pkg))
+            return [];
+        const sourceIdentity = readCommunitySourceIdentity(appDir, `${path.basename(workspaceRoot)}/${entry.name}`);
+        const packageName = sourceIdentity.appName.split("/").pop() ?? sourceIdentity.appName;
+        if (packageName === "dispatch")
+            return [];
+        return [
+            {
+                name: entry.name,
+                label: sourceIdentity.appTitle,
+                dir: appDir,
+                sourceIdentity,
+            },
+        ];
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function readPackageJsonObject(packagePath) {
+    try {
+        const value = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function packageDirectlyDependsOnAgentNativeCore(pkg) {
+    return [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies].some((group) => group !== null &&
+        typeof group === "object" &&
+        !Array.isArray(group) &&
+        typeof group["@agent-native/core"] ===
+            "string");
+}
+function normalizeCommunityWorkspaceAppDependencies(appDir, sourceWorkspaceRoot, options) {
+    const appPackagePath = path.join(appDir, "package.json");
+    const pkg = readPackageJsonObject(appPackagePath);
+    if (!pkg) {
+        throw new ValidationError("Selected community workspace app has an unreadable package.json.");
+    }
+    const rootPkg = readPackageJsonObject(path.join(sourceWorkspaceRoot, "package.json"));
+    const agentNative = rootPkg?.["agent-native"] &&
+        typeof rootPkg["agent-native"] === "object" &&
+        !Array.isArray(rootPkg["agent-native"])
+        ? rootPkg["agent-native"]
+        : undefined;
+    const sourceWorkspaceCore = typeof agentNative?.workspaceCore === "string"
+        ? agentNative.workspaceCore
+        : undefined;
+    const catalog = loadCommunityWorkspaceCatalog(sourceWorkspaceRoot);
+    const supportedWorkspacePackages = new Set([
+        "@agent-native/core",
+        "@agent-native/dispatch",
+        "@agent-native/toolkit",
+    ]);
+    for (const depType of [
+        "dependencies",
+        "devDependencies",
+        "peerDependencies",
+    ]) {
+        const deps = pkg[depType];
+        if (!deps || typeof deps !== "object" || Array.isArray(deps))
+            continue;
+        for (const [key, value] of Object.entries(deps)) {
+            if (key === sourceWorkspaceCore) {
+                delete deps[key];
+                continue;
+            }
+            if (value === "catalog:") {
+                const resolved = catalog[key];
+                if (!resolved) {
+                    throw new ValidationError(`Community workspace app dependency "${key}" uses catalog:, but no value was found in the source pnpm-workspace.yaml catalog.`);
+                }
+                deps[key] = resolved;
+                continue;
+            }
+            if (typeof value === "string" && value.startsWith("catalog:")) {
+                throw new ValidationError(`Community workspace app dependency "${key}" uses unsupported named catalog reference "${value}". Use a concrete version or the default catalog.`);
+            }
+            if (typeof value === "string" &&
+                value.startsWith("workspace:") &&
+                supportedWorkspacePackages.has(key)) {
+                deps[key] =
+                    key === "@agent-native/core"
+                        ? getCoreDependencyVersion()
+                        : key === "@agent-native/dispatch"
+                            ? getDispatchDependencyVersion()
+                            : getToolkitDependencyVersion();
+                continue;
+            }
+            if (typeof value === "string" && value.startsWith("workspace:")) {
+                throw new ValidationError(`Community workspace app dependency "${key}" uses "${value}", but that source workspace package is not included when installing one app. Publish it with a concrete version or remove the dependency.`);
+            }
+        }
+    }
+    fs.writeFileSync(appPackagePath, JSON.stringify(pkg, null, 2) + "\n");
+    if (sourceWorkspaceCore) {
+        rewriteCanonicalCommunityWorkspacePlugins(appDir, sourceWorkspaceCore, options);
+    }
+    if (sourceWorkspaceCore &&
+        findSourceImportSpecifier(appDir, sourceWorkspaceCore)) {
+        throw new ValidationError(`Community workspace app imports its source shared package "${sourceWorkspaceCore}", which is not included when installing one app. Move that code into the app or publish it as a concrete dependency.`);
+    }
+}
+function rewriteCanonicalCommunityWorkspacePlugins(appDir, sourceWorkspaceCore, options) {
+    const authPath = path.join(appDir, "server", "plugins", "auth.ts");
+    const agentChatPath = path.join(appDir, "server", "plugins", "agent-chat.ts");
+    if (options.shape === "standalone") {
+        if (fs.existsSync(authPath)) {
+            const auth = fs.readFileSync(authPath, "utf-8");
+            if (containsModuleSpecifier(auth, sourceWorkspaceCore) &&
+                auth.includes("defaultAuthPlugin") &&
+                auth.includes("workspaceServer")) {
+                fs.writeFileSync(authPath, 'export { defaultAuthPlugin as default } from "@agent-native/core/server";\n');
+            }
+        }
+        if (fs.existsSync(agentChatPath)) {
+            const agentChat = fs.readFileSync(agentChatPath, "utf-8");
+            if (containsModuleSpecifier(agentChat, sourceWorkspaceCore) &&
+                agentChat.includes("createWorkspaceAgentChatPlugin") &&
+                agentChat.includes("actionsRegistry")) {
+                fs.writeFileSync(agentChatPath, [
+                    'import { createAgentChatPlugin, loadActionsFromStaticRegistry } from "@agent-native/core/server";',
+                    'import actionsRegistry from "../../.generated/actions-registry.js";',
+                    "",
+                    "export default createAgentChatPlugin({",
+                    `  appId: ${JSON.stringify(options.destinationAppName)},`,
+                    "  actions: loadActionsFromStaticRegistry(actionsRegistry),",
+                    "});",
+                    "",
+                ].join("\n"));
+            }
+        }
+        return;
+    }
+    if (options.shape === "workspace" && options.targetWorkspaceCoreName) {
+        for (const pluginPath of [authPath, agentChatPath]) {
+            if (!fs.existsSync(pluginPath))
+                continue;
+            const content = fs.readFileSync(pluginPath, "utf-8");
+            const next = replaceModuleSpecifierPrefix(content, sourceWorkspaceCore, options.targetWorkspaceCoreName);
+            if (next !== content)
+                fs.writeFileSync(pluginPath, next);
+        }
+    }
+}
+function containsModuleSpecifier(content, moduleName) {
+    return new RegExp(`(["'])${escapeRegExp(moduleName)}(?:/[^"']*)?\\1`).test(content);
+}
+function replaceModuleSpecifierPrefix(content, sourceModule, targetModule) {
+    return content.replace(new RegExp(`(["'])${escapeRegExp(sourceModule)}((?:/[^"']*)?)\\1`, "g"), (_match, quote, suffix) => `${quote}${targetModule}${suffix}${quote}`);
+}
+function findSourceImportSpecifier(dir, moduleName) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const filePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = findSourceImportSpecifier(filePath, moduleName);
+            if (nested)
+                return nested;
+            continue;
+        }
+        if (!/\.(?:[cm]?[jt]sx?)$/.test(entry.name))
+            continue;
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const escaped = escapeRegExp(moduleName);
+            if (new RegExp(`(?:from\\s*|import\\s*\\(\\s*|import\\s*|require\\s*\\(\\s*)(["'])${escaped}(?:/[^"']*)?\\1`).test(content)) {
+                return filePath;
+            }
+        }
+        catch {
+            // Ignore unreadable source files; package validation reports main issues.
+        }
+    }
+    return undefined;
+}
+function loadCommunityWorkspaceCatalog(workspaceRoot) {
+    const workspacePath = path.join(workspaceRoot, "pnpm-workspace.yaml");
+    if (!fs.existsSync(workspacePath))
+        return {};
+    const result = {};
+    let inCatalog = false;
+    for (const line of fs.readFileSync(workspacePath, "utf-8").split("\n")) {
+        if (/^catalog:\s*$/.test(line)) {
+            inCatalog = true;
+            continue;
+        }
+        if (!inCatalog)
+            continue;
+        if (/^\S/.test(line))
+            break;
+        const match = line.match(/^\s+"?([^":]+)"?\s*:\s*"?([^"]+)"?\s*$/);
+        if (match)
+            result[match[1]] = match[2];
+    }
+    return result;
+}
+function readCommunitySourceIdentity(targetDir, repo) {
+    const fallbackName = repo.split("/").pop() ?? "app";
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(targetDir, "package.json"), "utf-8"));
+        const appName = typeof pkg.name === "string" && pkg.name.trim()
+            ? pkg.name.trim()
+            : fallbackName;
+        const unscopedName = appName.split("/").pop() ?? appName;
+        const appTitle = typeof pkg.displayName === "string" && pkg.displayName.trim()
+            ? pkg.displayName.trim()
+            : titleCase(unscopedName);
+        return { appName, appTitle };
+    }
+    catch {
+        return { appName: fallbackName, appTitle: titleCase(fallbackName) };
+    }
 }
 function githubTarballUrl(repo, ref, kind) {
     return `https://codeload.github.com/${repo}/tar.gz/refs/${kind === "tag" ? "tags" : "heads"}/${encodeURIComponent(ref)}`;
@@ -1368,6 +1998,9 @@ function isChatOnRampTemplate(templateName) {
     return templateName === "chat" || templateName === "starter";
 }
 function trackingTemplateName(templateName) {
+    if (templateName && isCommunityTemplateSelection(templateName)) {
+        return undefined;
+    }
     return templateName === "starter" ? "chat" : templateName;
 }
 function defaultPackageDescriptionForScaffold(appName) {
@@ -1398,26 +2031,36 @@ function fixPackageJsonName(appDir, name, templateName, provenance) {
             (isChatOnRampTemplate(templateName) && name !== templateName)) {
             pkg.description = defaultPackageDescriptionForScaffold(name);
         }
+        else if (provenance?.sourceIdentity &&
+            typeof pkg.description === "string") {
+            pkg.description = replaceSourceIdentityText(pkg.description, provenance.sourceIdentity, name, appTitle);
+        }
         const scaffoldGuidance = scaffoldGuidanceForTemplate(templateName);
-        if (scaffoldGuidance) {
+        if (scaffoldGuidance || provenance?.communityTemplate) {
             const agentNative = pkg["agent-native"] &&
                 typeof pkg["agent-native"] === "object" &&
                 !Array.isArray(pkg["agent-native"])
                 ? pkg["agent-native"]
                 : {};
-            const coreVersion = getCorePackageVersion();
-            agentNative.scaffold = {
-                template: trackingTemplateName(templateName),
-                frameworkSkills: scaffoldGuidance,
-                ...(provenance?.templateRef
-                    ? { templateRef: provenance.templateRef }
-                    : {}),
-                ...(provenance?.templateSource
-                    ? { templateSource: provenance.templateSource }
-                    : {}),
-                ...(coreVersion ? { coreVersion } : {}),
-                ...(provenance?.shape ? { shape: provenance.shape } : {}),
-            };
+            if (scaffoldGuidance) {
+                const coreVersion = getCorePackageVersion();
+                agentNative.scaffold = {
+                    template: trackingTemplateName(templateName),
+                    frameworkSkills: scaffoldGuidance,
+                    ...(provenance?.templateRef
+                        ? { templateRef: provenance.templateRef }
+                        : {}),
+                    ...(provenance?.templateSource
+                        ? { templateSource: provenance.templateSource }
+                        : {}),
+                    ...(coreVersion ? { coreVersion } : {}),
+                    ...(provenance?.shape ? { shape: provenance.shape } : {}),
+                };
+            }
+            if (provenance?.communityTemplate) {
+                delete agentNative.scaffold;
+                agentNative.communityTemplate = provenance.communityTemplate;
+            }
             pkg["agent-native"] = agentNative;
         }
         fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
@@ -1432,9 +2075,11 @@ function scaffoldGuidanceForTemplate(templateName) {
         return "headless";
     return getTemplate(normalized) ? "default" : undefined;
 }
-function fixWebManifestName(appDir, name, templateName) {
-    if (!isChatOnRampTemplate(templateName) || name === templateName)
+function fixWebManifestName(appDir, name, templateName, sourceIdentity) {
+    if ((!isChatOnRampTemplate(templateName) || name === templateName) &&
+        !sourceIdentity) {
         return;
+    }
     const manifestPath = path.join(appDir, "public", "manifest.json");
     if (!fs.existsSync(manifestPath))
         return;
@@ -1443,7 +2088,10 @@ function fixWebManifestName(appDir, name, templateName) {
         const appTitle = titleCase(name);
         manifest.name = appTitle;
         manifest.short_name = appTitle;
-        if (typeof manifest.description !== "string" ||
+        if (sourceIdentity && typeof manifest.description === "string") {
+            manifest.description = replaceSourceIdentityText(manifest.description, sourceIdentity, name, appTitle);
+        }
+        else if (typeof manifest.description !== "string" ||
             /\b(blank app|starter|chat-first)\b/i.test(manifest.description)) {
             manifest.description = defaultPackageDescriptionForScaffold(name);
         }
@@ -1451,6 +2099,21 @@ function fixWebManifestName(appDir, name, templateName) {
     }
     catch { }
 }
+function replaceSourceIdentityText(value, sourceIdentity, appName, appTitle) {
+    const unscopedSourceName = sourceIdentity.appName.split("/").pop() ?? sourceIdentity.appName;
+    const replacements = new Map([
+        [sourceIdentity.appTitle, appTitle],
+        [sourceIdentity.appName, appName],
+        [unscopedSourceName, appName],
+    ]);
+    const sourceValues = [...replacements.keys()]
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
+    if (sourceValues.length === 0)
+        return value;
+    const pattern = new RegExp(sourceValues.map(escapeRegExp).join("|"), "g");
+    return value.replace(pattern, (match) => replacements.get(match) ?? match);
+}
 function getCoreDependencyVersion() {
     if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE === "1") {
         const localCore = findLocalPackage("core");
@@ -1719,12 +2382,25 @@ function rewriteNetlifyToml(appDir, appName, mode) {
     }
     catch { }
 }
-function rewriteAgentChatAppId(appDir, appName, templateName) {
+function applyScaffoldIdentity(appDir, appName, templateName, sourceIdentity) {
+    rewriteTrackingAppId(appDir, appName, templateName, sourceIdentity);
+    rewriteAgentChatAppId(appDir, appName, templateName, sourceIdentity);
+    rewriteAppConfigIdentity(appDir, appName, sourceIdentity);
+}
+function rewriteAgentChatAppId(appDir, appName, templateName, sourceIdentity) {
     const pluginPath = path.join(appDir, "server", "plugins", "agent-chat.ts");
     if (!fs.existsSync(pluginPath))
         return;
     try {
         const content = fs.readFileSync(pluginPath, "utf-8");
+        if (sourceIdentity) {
+            const next = content
+                .replace(/(createAgentChatPlugin\(\{[\s\S]*?\bappId:\s*)(["'])[^"']+\2/, (_match, prefix, quote) => `${prefix}${quote}${appName}${quote}`)
+                .replace(/(const\s+options\s*=\s*\{[\s\S]*?\bappId:\s*)(["'])[^"']+\2/, (_match, prefix, quote) => `${prefix}${quote}${appName}${quote}`);
+            if (next !== content)
+                fs.writeFileSync(pluginPath, next);
+            return;
+        }
         const sourceAppIds = ["chat", "starter"];
         if (templateName && templateName !== appName) {
             sourceAppIds.push(templateName);
@@ -1739,13 +2415,19 @@ function rewriteAgentChatAppId(appDir, appName, templateName) {
     }
     catch { }
 }
-function rewriteTrackingAppId(appDir, appName, templateName) {
+function rewriteTrackingAppId(appDir, appName, templateName, sourceIdentity) {
     const rootPath = path.join(appDir, "app", "root.tsx");
     if (!fs.existsSync(rootPath))
         return;
     try {
         const content = fs.readFileSync(rootPath, "utf-8");
         const trackedTemplateName = trackingTemplateName(templateName);
+        if (sourceIdentity) {
+            const next = content.replace(/(configureTracking\(\{[\s\S]*?\bapp:\s*)(["'])[^"']+\2/, (_match, prefix, quote) => `${prefix}${quote}${appName}${quote}`);
+            if (next !== content)
+                fs.writeFileSync(rootPath, next);
+            return;
+        }
         const sourceAppIds = ["agent-native-[^\"']+", "\\{\\{APP_NAME\\}\\}"];
         if (templateName && templateName !== appName) {
             sourceAppIds.push(escapeRegExp(templateName));
@@ -1768,6 +2450,23 @@ function rewriteTrackingAppId(appDir, appName, templateName) {
     }
     catch { }
 }
+function rewriteAppConfigIdentity(appDir, appName, sourceIdentity) {
+    if (!sourceIdentity)
+        return;
+    const configPath = path.join(appDir, "app", "lib", "app-config.ts");
+    if (!fs.existsSync(configPath))
+        return;
+    try {
+        const content = fs.readFileSync(configPath, "utf-8");
+        const appTitle = appTitleForScaffold(appName);
+        const next = content
+            .replace(/(const\s+rawAppName\s*=\s*)(["'])[^"']*\2/, (_match, prefix, quote) => `${prefix}${quote}${appName}${quote}`)
+            .replace(/(const\s+rawAppTitle\s*=\s*)(["'])[^"']*\2/, (_match, prefix, quote) => `${prefix}${quote}${appTitle}${quote}`);
+        if (next !== content)
+            fs.writeFileSync(configPath, next);
+    }
+    catch { }
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }