@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/dist/cli/create.js

@@ -1,50 +1,308 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
 import { setupAgentSymlinks } from "./setup-agents.js";
+import { workspacifyApp, parseWorkspaceScope } from "./workspacify.js";
+import { visibleTemplates, allTemplateNames, } from "@agent-native/shared-app-config";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const REPO = "BuilderIO/agent-native";
+const TEMPLATES_DIR = "templates";
+/** Blank scaffold option appended to every picker. */
+const BLANK_OPTION = {
+    name: "blank",
+    label: "Blank",
+    hint: "Empty starter — build from scratch",
+};
 /**
- * Scaffold a new agent-native app from the default template.
+ * Main entry for `agent-native create [name]`.
+ *
+ * Default behavior: scaffold a workspace at <name>/ with a multi-select
+ * template picker. Use --standalone for the single-app standalone flow.
+ *
+ * If run *inside* an existing workspace, falls through to the add-app
+ * flow that scaffolds one new app under apps/<name>/.
  */
-export function createApp(name) {
-    if (!name) {
-        console.error("Usage: agent-native create <app-name>");
-        process.exit(1);
+export async function createApp(name, opts) {
+    const clack = await import("@clack/prompts");
+    // If we're already inside a workspace, the meaning of `create <name>` is
+    // "add a new app to this workspace". Delegate to add-app.
+    const workspace = detectWorkspace(process.cwd());
+    if (workspace) {
+        await addAppToWorkspace(name, opts);
+        return;
     }
-    // Validate name
-    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-        console.error(`Invalid app name "${name}". Use lowercase letters, numbers, and hyphens.`);
-        process.exit(1);
+    // Standalone escape hatch — behaves like the old single-app flow.
+    if (opts?.standalone) {
+        await createStandaloneApp(name, opts, clack);
+        return;
+    }
+    // When exactly one template is specified explicitly, treat it as a
+    // standalone scaffold (script-friendly, matches historic behavior).
+    // Use `--template a,b` or pass no --template to opt into the workspace
+    // flow with the multi-select picker.
+    const parsed = parseTemplateList(opts?.template);
+    if (parsed.length === 1) {
+        await createStandaloneApp(name, opts, clack);
+        return;
+    }
+    // Default: create a workspace.
+    await createWorkspaceInteractive(name, opts, clack);
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Workspace creation (new default)
+ * ───────────────────────────────────────────────────────────────────────── */
+async function createWorkspaceInteractive(name, opts, clack) {
+    clack.intro("Create a new agent-native workspace");
+    name = await promptNameIfMissing(name, clack, "workspace", "my-platform");
+    // Multi-select picker for apps to include.
+    const preselected = parseTemplateList(opts?.template);
+    const templates = await promptTemplatePicker(preselected, clack);
+    if (templates.length === 0) {
+        clack.cancel("No apps selected. Cancelled.");
+        process.exit(0);
     }
     const targetDir = path.resolve(process.cwd(), name);
     if (fs.existsSync(targetDir)) {
-        console.error(`Directory "${name}" already exists.`);
+        clack.cancel(`Directory "${name}" already exists.`);
         process.exit(1);
     }
-    // Locate the template directory
-    // In dist: dist/cli/create.js -> ../../src/templates/default
-    // Resolve relative to the package root
+    const s = clack.spinner();
+    s.start(`Scaffolding workspace with ${templates.length} app(s)...`);
+    try {
+        await scaffoldWorkspaceRoot(targetDir, name);
+        const workspaceCoreName = `@${name}/core-module`;
+        for (const t of templates) {
+            const appDir = path.join(targetDir, "apps", t);
+            await scaffoldAppTemplate(appDir, t);
+            workspacifyApp({
+                appDir,
+                appName: t,
+                workspaceRoot: targetDir,
+                workspaceCoreName,
+            });
+            fixPackageJsonName(appDir, t);
+            renameGitignore(appDir);
+            // Each app owns its own .claude / .agents symlinks.
+            setupAgentSymlinks(appDir);
+        }
+        s.stop("Workspace scaffolded.");
+    }
+    catch (err) {
+        s.stop("Failed to scaffold workspace.");
+        throw err;
+    }
+    const firstApp = templates[0];
+    clack.outro([
+        `Done! Next steps:`,
+        ``,
+        `  cd ${name}`,
+        `  cp .env.example .env     # ANTHROPIC_API_KEY, DATABASE_URL, BETTER_AUTH_SECRET`,
+        `  pnpm install`,
+        `  pnpm --filter ${firstApp} dev`,
+        ``,
+        `Add another app later:  agent-native add-app`,
+        `Deploy the whole workspace:  agent-native deploy`,
+    ].join("\n"));
+}
+async function scaffoldWorkspaceRoot(targetDir, name) {
     const packageRoot = path.resolve(__dirname, "../..");
-    const templateDir = path.join(packageRoot, "src/templates/default");
-    if (!fs.existsSync(templateDir)) {
-        console.error(`Template directory not found at ${templateDir}. Is the package installed correctly?`);
+    const rootTemplate = path.join(packageRoot, "src/templates/workspace-root");
+    const coreTemplate = path.join(packageRoot, "src/templates/workspace-core");
+    copyDir(rootTemplate, targetDir);
+    replacePlaceholders(targetDir, name, titleCase(name));
+    renameGitignore(targetDir);
+    const corePackageDir = path.join(targetDir, "packages", "core-module");
+    fs.mkdirSync(path.join(targetDir, "packages"), { recursive: true });
+    copyDir(coreTemplate, corePackageDir);
+    replacePlaceholders(corePackageDir, name, titleCase(name));
+    // Ensure apps/ exists (even if empty).
+    fs.mkdirSync(path.join(targetDir, "apps"), { recursive: true });
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Adding an app into an existing workspace
+ * ───────────────────────────────────────────────────────────────────────── */
+/**
+ * Entry for `agent-native add-app [name]`. Called from inside a workspace.
+ * Shows the multi-select picker (excluding already-installed apps) and
+ * scaffolds each selected template under apps/<name>/.
+ *
+ * When `name` is provided with `--template foo`, scaffolds exactly one app
+ * named <name> using template foo (non-interactive).
+ */
+export async function addAppToWorkspace(name, opts) {
+    const clack = await import("@clack/prompts");
+    const workspace = detectWorkspace(process.cwd());
+    if (!workspace) {
+        clack.cancel("Not inside a workspace. Run `agent-native create` to make one first, or use `--standalone`.");
         process.exit(1);
     }
-    console.log(`Creating ${name}...`);
-    // Copy template
-    copyDir(templateDir, targetDir);
-    // Replace {{APP_NAME}} and {{APP_TITLE}} placeholders in all text files.
-    // Previously this was done per-file (package.json, index.html, AGENTS.md),
-    // but index.html no longer exists in the React Router framework template and
-    // route files like app/routes/_index.tsx also contain {{APP_TITLE}}.
-    // A single recursive pass is simpler and future-proof.
-    const appTitle = name
-        .split("-")
-        .map((w) => w[0].toUpperCase() + w.slice(1))
-        .join(" ");
+    clack.intro("Add an app to your workspace");
+    const installed = listInstalledApps(workspace.workspaceRoot);
+    // Non-interactive path: name + single --template
+    const preselected = parseTemplateList(opts?.template);
+    if (name && preselected.length === 1) {
+        const tpl = preselected[0];
+        await scaffoldOneAppIntoWorkspace(workspace, name, tpl, clack);
+        return;
+    }
+    const templates = await promptTemplatePicker(preselected, clack, {
+        excludeNames: installed,
+        message: "Which apps do you want to add?",
+    });
+    if (templates.length === 0) {
+        clack.cancel("No apps selected. Cancelled.");
+        process.exit(0);
+    }
+    for (const t of templates) {
+        await scaffoldOneAppIntoWorkspace(workspace, t, t, clack);
+    }
+}
+async function scaffoldOneAppIntoWorkspace(workspace, appName, templateName, clack) {
+    const appsDir = path.join(workspace.workspaceRoot, "apps");
+    fs.mkdirSync(appsDir, { recursive: true });
+    const appDir = path.join(appsDir, appName);
+    if (fs.existsSync(appDir)) {
+        clack.cancel(`Directory "apps/${appName}" already exists.`);
+        process.exit(1);
+    }
+    const s = clack.spinner();
+    s.start(`Scaffolding apps/${appName} from ${templateName}...`);
+    try {
+        await scaffoldAppTemplate(appDir, templateName);
+        workspacifyApp({
+            appDir,
+            appName,
+            workspaceRoot: workspace.workspaceRoot,
+            workspaceCoreName: workspace.workspaceCoreName,
+        });
+        fixPackageJsonName(appDir, appName);
+        renameGitignore(appDir);
+        setupAgentSymlinks(appDir);
+        s.stop(`Scaffolded apps/${appName}.`);
+    }
+    catch (err) {
+        s.stop(`Failed to scaffold apps/${appName}.`);
+        throw err;
+    }
+    clack.outro(`Done!\n\n  pnpm install\n  pnpm --filter ${appName} dev`);
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Standalone creation (escape hatch)
+ * ───────────────────────────────────────────────────────────────────────── */
+async function createStandaloneApp(name, opts, clack) {
+    clack.intro("Create a new standalone agent-native app");
+    name = await promptNameIfMissing(name, clack, "app", "my-app");
+    const targetDir = path.resolve(process.cwd(), name);
+    if (fs.existsSync(targetDir)) {
+        clack.cancel(`Directory "${name}" already exists.`);
+        process.exit(1);
+    }
+    // Standalone is single-select — pick one template.
+    let template = opts?.template && !opts.template.includes(",") ? opts.template : undefined;
+    if (!template) {
+        const picked = await clack.select({
+            message: "Which template would you like to use?",
+            options: [
+                ...visibleTemplates().map((t) => ({
+                    value: t.name,
+                    label: t.label,
+                    hint: t.hint,
+                })),
+                {
+                    value: BLANK_OPTION.name,
+                    label: BLANK_OPTION.label,
+                    hint: BLANK_OPTION.hint,
+                },
+            ],
+        });
+        if (clack.isCancel(picked)) {
+            clack.cancel("Cancelled.");
+            process.exit(0);
+        }
+        template = picked;
+    }
+    const s = clack.spinner();
+    s.start("Scaffolding your app...");
+    try {
+        await scaffoldAppTemplate(targetDir, template);
+        postProcessStandalone(name, targetDir);
+        s.stop("App created!");
+    }
+    catch (err) {
+        s.stop("Failed to create app.");
+        throw err;
+    }
+    clack.outro(`Done! Next steps:\n\n  cd ${name}\n  pnpm install\n  pnpm dev`);
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Shared scaffolding helpers
+ * ───────────────────────────────────────────────────────────────────────── */
+/**
+ * Scaffold a single app template into `targetDir`. Resolves:
+ *   - "blank" → bundled default template
+ *   - "github:user/repo" → download the whole repo
+ *   - first-party template name → download that subdir from BuilderIO/agent-native
+ */
+async function scaffoldAppTemplate(targetDir, template) {
+    fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+    if (template === "blank") {
+        const packageRoot = path.resolve(__dirname, "../..");
+        const defaultDir = path.join(packageRoot, "src/templates/default");
+        if (!fs.existsSync(defaultDir)) {
+            throw new Error(`Default template not found at ${defaultDir}. Is the package installed correctly?`);
+        }
+        copyDir(defaultDir, targetDir);
+        return;
+    }
+    // Normalize legacy alias
+    let resolved = template === "video" ? "videos" : template;
+    if (resolved.startsWith("github:")) {
+        const repo = resolved.slice("github:".length);
+        await downloadGitHubRepo(repo, targetDir);
+        return;
+    }
+    if (!allTemplateNames().includes(resolved)) {
+        throw new Error(`Unknown template "${template}". Known: ${allTemplateNames().join(", ")} — or use github:user/repo for community templates.`);
+    }
+    // If running from the framework monorepo with a local templates/ dir, use
+    // that. Otherwise download from GitHub. This keeps `agent-native create`
+    // fast during framework development.
+    const localTemplate = findLocalTemplate(resolved);
+    if (localTemplate) {
+        copyDir(localTemplate, targetDir);
+    }
+    else {
+        await downloadGitHubSubdir(REPO, `${TEMPLATES_DIR}/${resolved}`, targetDir);
+    }
+}
+/**
+ * When developing the framework itself, prefer the sibling templates/<name>
+ * directory. Returns undefined when running as a published package.
+ */
+function findLocalTemplate(name) {
+    let dir = path.resolve(__dirname);
+    for (let i = 0; i < 10; i++) {
+        const candidate = path.join(dir, "templates", name);
+        if (fs.existsSync(path.join(candidate, "package.json"))) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Post-process a standalone scaffold: replace placeholders, strip
+ * workspace:* deps, set up agent symlinks, etc.
+ */
+function postProcessStandalone(name, targetDir) {
+    const appTitle = titleCase(name);
     replacePlaceholders(targetDir, name, appTitle);
-    // Copy defaults files (gitignored files that get seeded from .defaults on first create)
+    fixPackageJsonName(targetDir, name);
     for (const base of ["learnings"]) {
         const defaultsFile = path.join(targetDir, `${base}.defaults.md`);
         const targetFile = path.join(targetDir, `${base}.md`);
@@ -52,37 +310,224 @@ export function createApp(name) {
             fs.copyFileSync(defaultsFile, targetFile);
         }
     }
-    // Rename gitignore (npm strips .gitignore from packages)
-    const gitignoreSrc = path.join(targetDir, "_gitignore");
-    const gitignoreDst = path.join(targetDir, ".gitignore");
-    if (fs.existsSync(gitignoreSrc)) {
-        fs.renameSync(gitignoreSrc, gitignoreDst);
+    renameGitignore(targetDir);
+    // Drop monorepo-only files that standalone apps shouldn't ship.
+    for (const f of ["DEVELOPING.md"]) {
+        const p = path.join(targetDir, f);
+        if (fs.existsSync(p))
+            fs.unlinkSync(p);
+    }
+    // Resolve workspace:* deps to `latest` for standalone.
+    const pkgPath = path.join(targetDir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            for (const depType of [
+                "dependencies",
+                "devDependencies",
+                "peerDependencies",
+            ]) {
+                const deps = pkg[depType];
+                if (!deps)
+                    continue;
+                for (const [key, val] of Object.entries(deps)) {
+                    if (typeof val === "string" && val.startsWith("workspace:")) {
+                        deps[key] = "latest";
+                    }
+                }
+            }
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+        }
+        catch { }
     }
-    // Create symlinks for all agent tools (Claude, Cursor, Windsurf, etc.)
     setupAgentSymlinks(targetDir);
-    console.log(`\nDone! Created ${name} at ${targetDir}\n`);
-    console.log(`Next steps:`);
-    console.log(`  cd ${name}`);
-    console.log(`  pnpm install`);
-    console.log(`  pnpm dev          # Start dev server at http://localhost:8080`);
-    console.log(`  pnpm build        # Build for production`);
-    console.log(`  pnpm start        # Start production server`);
-    console.log(``);
-    console.log(`Your app includes agent skills in .agents/skills/.`);
-    console.log(`These teach the AI agent how to work within the framework's architecture.`);
-    console.log(``);
-    console.log(`Need multi-user collaboration? See: https://agent-native.com/docs/file-sync`);
 }
+/* ─────────────────────────────────────────────────────────────────────────
+ * Prompting helpers
+ * ───────────────────────────────────────────────────────────────────────── */
+async function promptNameIfMissing(name, clack, kind, placeholder) {
+    if (name) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            clack.cancel(`Invalid ${kind} name "${name}". Use lowercase letters, numbers, and hyphens.`);
+            process.exit(1);
+        }
+        return name;
+    }
+    const result = await clack.text({
+        message: `What is your ${kind} name?`,
+        placeholder,
+        validate(value) {
+            if (!value)
+                return `${kind[0].toUpperCase() + kind.slice(1)} name is required`;
+            if (!/^[a-z][a-z0-9-]*$/.test(value)) {
+                return "Use lowercase letters, numbers, and hyphens (must start with a letter)";
+            }
+            if (fs.existsSync(path.resolve(process.cwd(), value))) {
+                return `Directory "${value}" already exists`;
+            }
+        },
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        process.exit(0);
+    }
+    return result;
+}
+async function promptTemplatePicker(preselected, clack, opts) {
+    const excluded = new Set(opts?.excludeNames ?? []);
+    const options = visibleTemplates()
+        .filter((t) => !excluded.has(t.name))
+        .map((t) => ({
+        value: t.name,
+        label: t.label,
+        hint: t.hint,
+    }));
+    // If there's nothing left to pick, the caller gets an empty selection —
+    // they decide how to handle it.
+    if (options.length === 0)
+        return [];
+    // Default pre-selection: what the user passed via --template, falling
+    // back to "starter" when that's available and nothing else is pre-picked.
+    const defaults = preselected.length > 0
+        ? preselected.filter((p) => options.some((o) => o.value === p))
+        : options.some((o) => o.value === "starter")
+            ? ["starter"]
+            : [];
+    const result = await clack.multiselect({
+        message: opts?.message ?? "Which apps would you like to include?",
+        options,
+        initialValues: defaults,
+        required: false,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        process.exit(0);
+    }
+    return result;
+}
+function parseTemplateList(input) {
+    if (!input)
+        return [];
+    return input
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function listInstalledApps(workspaceRoot) {
+    const appsDir = path.join(workspaceRoot, "apps");
+    if (!fs.existsSync(appsDir))
+        return [];
+    return fs
+        .readdirSync(appsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Workspace detection
+ * ───────────────────────────────────────────────────────────────────────── */
 /**
- * Recursively replace {{APP_NAME}} and {{APP_TITLE}} placeholders in all
- * text files under `dir`. Binary files are skipped silently.
+ * Walk up from startDir looking for a package.json with
+ * `agent-native.workspaceCore` set. Returns the workspace root and core
+ * package name, or null if not inside a workspace.
  */
-function replacePlaceholders(dir, appName, appTitle) {
+export function detectWorkspace(startDir) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 20; i++) {
+        const pkgPath = path.join(dir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                const wsCore = pkg?.["agent-native"]?.workspaceCore;
+                if (typeof wsCore === "string" && wsCore.length > 0) {
+                    return { workspaceRoot: dir, workspaceCoreName: wsCore };
+                }
+            }
+            catch { }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export { parseWorkspaceScope };
+/* ─────────────────────────────────────────────────────────────────────────
+ * Download / copy helpers
+ * ───────────────────────────────────────────────────────────────────────── */
+function validateRepoName(repo) {
+    if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) {
+        throw new Error(`Invalid repository name "${repo}". Expected format: user/repo`);
+    }
+}
+function downloadAndExtract(url, destDir) {
+    fs.mkdirSync(destDir, { recursive: true });
+    const tarball = execFileSync("curl", ["-sL", url], {
+        maxBuffer: 100 * 1024 * 1024,
+    });
+    const tarPath = path.join(destDir, ".download.tar.gz");
+    fs.writeFileSync(tarPath, tarball);
+    try {
+        execFileSync("tar", ["xzf", tarPath, "--strip-components=1", "-C", destDir], { stdio: "pipe" });
+    }
+    finally {
+        fs.unlinkSync(tarPath);
+    }
+}
+async function downloadGitHubSubdir(repo, subdir, targetDir) {
+    validateRepoName(repo);
+    const tarUrl = `https://api.github.com/repos/${repo}/tarball/main`;
+    const tmpDir = path.join(targetDir, "..", `.agent-native-tmp-${Date.now()}`);
+    try {
+        downloadAndExtract(tarUrl, tmpDir);
+        const srcDir = path.join(tmpDir, subdir);
+        if (!fs.existsSync(srcDir)) {
+            throw new Error(`Template directory "${subdir}" not found in ${repo}.`);
+        }
+        copyDir(srcDir, targetDir);
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+async function downloadGitHubRepo(repo, targetDir) {
+    validateRepoName(repo);
+    const tarUrl = `https://api.github.com/repos/${repo}/tarball/main`;
+    downloadAndExtract(tarUrl, targetDir);
+}
+/* ─────────────────────────────────────────────────────────────────────────
+ * Text / filesystem helpers
+ * ───────────────────────────────────────────────────────────────────────── */
+function titleCase(name) {
+    return name
+        .split("-")
+        .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+        .join(" ");
+}
+function fixPackageJsonName(appDir, name) {
+    const pkgPath = path.join(appDir, "package.json");
+    if (!fs.existsSync(pkgPath))
+        return;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        pkg.name = name;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    }
+    catch { }
+}
+function renameGitignore(dir) {
+    const src = path.join(dir, "_gitignore");
+    const dst = path.join(dir, ".gitignore");
+    if (fs.existsSync(src))
+        fs.renameSync(src, dst);
+}
+function replacePlaceholders(dir, appName, appTitle, workspaceName) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const p = path.join(dir, entry.name);
-        if (entry.isSymbolicLink() || entry.isDirectory()) {
-            if (!entry.isSymbolicLink())
-                replacePlaceholders(p, appName, appTitle);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            replacePlaceholders(p, appName, appTitle, workspaceName);
             continue;
         }
         let content;
@@ -90,15 +535,22 @@ function replacePlaceholders(dir, appName, appTitle) {
             content = fs.readFileSync(p, "utf-8");
         }
         catch {
-            continue; // skip unreadable / binary files
+            continue;
         }
+        const hasWs = workspaceName !== undefined && content.includes("{{WORKSPACE_NAME}}");
         if (!content.includes("{{APP_NAME}}") &&
-            !content.includes("{{APP_TITLE}}")) {
+            !content.includes("{{APP_TITLE}}") &&
+            !hasWs) {
             continue;
         }
-        fs.writeFileSync(p, content
+        let next = content;
+        if (workspaceName !== undefined) {
+            next = next.replace(/\{\{WORKSPACE_NAME\}\}/g, workspaceName);
+        }
+        next = next
             .replace(/\{\{APP_NAME\}\}/g, appName)
-            .replace(/\{\{APP_TITLE\}\}/g, appTitle));
+            .replace(/\{\{APP_TITLE\}\}/g, appTitle);
+        fs.writeFileSync(p, next);
     }
 }
 function copyDir(src, dest, root) {
@@ -109,15 +561,11 @@ function copyDir(src, dest, root) {
         const destPath = path.join(dest, entry.name);
         if (entry.isSymbolicLink()) {
             const target = fs.readlinkSync(srcPath);
-            // Resolve one level (path math only, no disk follow) to check
-            // whether the symlink stays inside the template tree.
             const resolvedTarget = path.resolve(path.dirname(srcPath), target);
             if (resolvedTarget.startsWith(resolvedRoot)) {
-                // Internal symlink (e.g. .claude/skills -> ../.agents/skills) — preserve it
                 fs.symlinkSync(target, destPath);
             }
             else if (fs.statSync(srcPath).isDirectory()) {
-                // External symlink to directory — dereference and copy contents
                 copyDir(srcPath, destPath, resolvedRoot);
             }
             else {