@agent-native/core 0.152.1 → 0.153.0

package/dist/cli/create.d.ts

@@ -156,11 +156,21 @@ export declare function detectWorkspace(startDir: string): {
 } | null;
 export { parseWorkspaceScope };
 /** @internal — exported for E2E tests */
-export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, 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, };
+export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, 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, extractTarball as _extractTarball, materializeArchiveSymlinks as _materializeArchiveSymlinks, 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, };
 declare function tarExtractArgs(tarPath: string, destDir: string, options?: {
     skipAgentSymlinks?: boolean;
     untrustedCommunityArchive?: boolean;
+    additionalExcludes?: string[];
 }): string[];
+interface ArchiveSymlink {
+    archivePath: string;
+    target: string;
+}
+declare function materializeArchiveSymlinks(destDir: string, symlinks: ArchiveSymlink[]): void;
+declare function extractTarball(tarPath: string, destDir: string, options?: {
+    skipAgentSymlinks?: boolean;
+    untrustedCommunityArchive?: boolean;
+}): void;
 declare function validateCommunityArchive(tarPath: string): void;
 declare function assertSafeCommunityArchiveListing(listing: string): void;
 /** Resolves to the ref that actually succeeded so callers can record it. */
@@ -227,5 +237,6 @@ declare function renameGitignore(dir: string): void;
 declare function replacePlaceholders(dir: string, appName: string, appTitle: string, workspaceName?: string): void;
 declare function copyDir(src: string, dest: string, root?: string, opts?: {
     skipExisting?: boolean;
+    materializeSymlinks?: boolean;
 }): void;
 declare function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean;

package/dist/cli/create.js

@@ -1700,7 +1700,7 @@ export function detectWorkspace(startDir) {
 }
 export { parseWorkspaceScope };
 /** @internal — exported for E2E tests */
-export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, 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, };
+export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, 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, extractTarball as _extractTarball, materializeArchiveSymlinks as _materializeArchiveSymlinks, 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
  * ───────────────────────────────────────────────────────────────────────── */
@@ -1712,12 +1712,14 @@ function validateRepoName(repo) {
     }
 }
 function tarExtractArgs(tarPath, destDir, options = {}) {
-    const excludes = options.skipAgentSymlinks
-        ? FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES.flatMap((pattern) => [
-            "--exclude",
-            pattern,
-        ])
-        : [];
+    const excludePatterns = [
+        ...(options.skipAgentSymlinks ? FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES : []),
+        ...(options.additionalExcludes ?? []),
+    ];
+    const excludes = [...new Set(excludePatterns)].flatMap((pattern) => [
+        "--exclude",
+        pattern,
+    ]);
     const safeOwnership = options.untrustedCommunityArchive
         ? ["--no-same-owner", "--no-same-permissions"]
         : [];
@@ -1731,6 +1733,79 @@ function tarExtractArgs(tarPath, destDir, options = {}) {
         destDir,
     ];
 }
+function archiveSymlinksForExtraction(tarPath) {
+    const listing = execFileSync("tar", ["tvzf", tarPath], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return listing.split(/\r?\n/).flatMap((line) => {
+        if (!line.startsWith("l"))
+            return [];
+        const match = line.match(/\s(\S+)\s+->\s+(\S+)\s*$/);
+        return match ? [{ archivePath: match[1], target: match[2] }] : [];
+    });
+}
+function archivePathAfterStrip(archivePath) {
+    const parts = archivePath.split("/");
+    return parts.length > 1 ? parts.slice(1).join("/") : archivePath;
+}
+function isPathWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+function materializeArchiveSymlinks(destDir, symlinks) {
+    const links = new Map(symlinks.map((link) => [archivePathAfterStrip(link.archivePath), link]));
+    const active = new Set();
+    const materialize = (relativeLinkPath) => {
+        const link = links.get(relativeLinkPath);
+        if (!link)
+            return;
+        if (active.has(relativeLinkPath)) {
+            throw new Error(`Cannot materialize cyclic archive symlink "${relativeLinkPath}".`);
+        }
+        const linkPath = path.resolve(destDir, relativeLinkPath);
+        if (!isPathWithin(path.resolve(destDir), linkPath)) {
+            throw new Error(`Cannot materialize archive symlink outside the extraction directory: "${relativeLinkPath}".`);
+        }
+        if (fs.existsSync(linkPath))
+            return;
+        const resolvedTarget = path.resolve(path.dirname(linkPath), link.target);
+        if (!isPathWithin(path.resolve(destDir), resolvedTarget)) {
+            throw new Error(`Archive symlink "${relativeLinkPath}" points outside the extraction directory.`);
+        }
+        active.add(relativeLinkPath);
+        try {
+            const targetRelativePath = path.relative(path.resolve(destDir), resolvedTarget);
+            if (links.has(targetRelativePath) && !fs.existsSync(resolvedTarget)) {
+                materialize(targetRelativePath);
+            }
+            if (!fs.existsSync(resolvedTarget)) {
+                throw new Error(`Archive symlink "${relativeLinkPath}" points to a missing target.`);
+            }
+            fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+            const targetStat = fs.statSync(resolvedTarget);
+            if (targetStat.isDirectory()) {
+                copyDir(resolvedTarget, linkPath, undefined, {
+                    materializeSymlinks: true,
+                });
+            }
+            else {
+                fs.copyFileSync(resolvedTarget, linkPath);
+            }
+        }
+        finally {
+            active.delete(relativeLinkPath);
+        }
+    };
+    // Resolve deeper links first so links such as `.claude/skills` see the
+    // regularized skill directories they point at.
+    for (const relativeLinkPath of [...links.keys()].sort((a, b) => b.length - a.length)) {
+        materialize(relativeLinkPath);
+    }
+}
 function execFileBuffer(command, args, options) {
     return new Promise((resolve, reject) => {
         execFile(command, args, { ...options, encoding: "buffer" }, (error, stdout, stderr) => {
@@ -1745,6 +1820,20 @@ function execFileBuffer(command, args, options) {
         });
     });
 }
+function extractTarball(tarPath, destDir, options = {}) {
+    const symlinks = options.skipAgentSymlinks || options.untrustedCommunityArchive
+        ? archiveSymlinksForExtraction(tarPath)
+        : [];
+    execFileSync("tar", tarExtractArgs(tarPath, destDir, {
+        ...options,
+        additionalExcludes: symlinks.map((link) => link.archivePath),
+    }), {
+        stdio: "pipe",
+    });
+    if (symlinks.length > 0) {
+        materializeArchiveSymlinks(destDir, symlinks);
+    }
+}
 async function downloadAndExtract(url, destDir, options = {}) {
     fs.mkdirSync(destDir, { recursive: true });
     // --fail-with-body so curl exits non-zero on HTTP 4xx/5xx instead of writing
@@ -1767,9 +1856,7 @@ async function downloadAndExtract(url, destDir, options = {}) {
         if (options.untrustedCommunityArchive) {
             validateCommunityArchive(tarPath);
         }
-        execFileSync("tar", tarExtractArgs(tarPath, destDir, options), {
-            stdio: "pipe",
-        });
+        extractTarball(tarPath, destDir, options);
     }
     finally {
         fs.unlinkSync(tarPath);
@@ -2854,7 +2941,8 @@ function copyDir(src, dest, root, opts) {
         if (entry.isSymbolicLink()) {
             const target = fs.readlinkSync(srcPath);
             const resolvedTarget = path.resolve(path.dirname(srcPath), target);
-            if (resolvedTarget.startsWith(resolvedRoot)) {
+            if (!opts?.materializeSymlinks &&
+                isPathWithin(resolvedRoot, resolvedTarget)) {
                 fs.symlinkSync(target, destPath);
             }
             else {

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "url";
 import * as Sentry from "@sentry/node";
 import { clearAgentNativeNitroPresetMarker, resolveAgentNativeNitroPreset, } from "../deploy/nitro-preset.js";
 import { resolveDeployPostBuildInvocation } from "./deploy-build.js";
+import { cliSpawnOptions } from "./process.js";
 import { shouldTrackCliRun } from "./telemetry-routing.js";
 import { createCliTelemetry } from "./telemetry.js";
 // Resolve version once at module scope — used by both --version and --help
@@ -381,11 +382,7 @@ function extractNodeInspectFlag(args) {
     return { inspectFlag, rest };
 }
 function run(cmd, cmdArgs, opts) {
-    const child = spawn(cmd, cmdArgs, {
-        stdio: opts?.stdio ?? "inherit",
-        shell: process.platform === "win32",
-        env: opts?.env ?? process.env,
-    });
+    const child = spawn(cmd, cmdArgs, cliSpawnOptions(opts));
     child.on("exit", (code) => process.exit(code ?? 0));
     // Forward signals to child so Cmd+C doesn't leave zombie processes holding ports
     for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
@@ -564,7 +561,10 @@ switch (command) {
             NITRO_DEV_RUNNER: process.env.NITRO_DEV_RUNNER ?? "node-process",
         };
         console.log(`[agent-native] API server debugger listening on ${target}`);
-        run(process.execPath, ["--import", preload, viteJsEntry, ...rest], { env });
+        run(process.execPath, ["--import", preload, viteJsEntry, ...rest], {
+            env,
+            shell: false,
+        });
         break;
     }
     case "workspace-dev": {

package/dist/cli/process.d.ts

@@ -0,0 +1,7 @@
+import type { SpawnOptions } from "node:child_process";
+/**
+ * Keep Windows command-name launches compatible with `.cmd` shims while
+ * allowing callers that already have a real executable path to opt out of the
+ * shell. The latter is important for paths such as `C:\\Program Files\\nodejs\\node.exe`.
+ */
+export declare function cliSpawnOptions(options?: Pick<SpawnOptions, "env" | "shell" | "stdio">, platform?: NodeJS.Platform): Pick<SpawnOptions, "env" | "shell" | "stdio">;

package/dist/cli/process.js

@@ -0,0 +1,12 @@
+/**
+ * Keep Windows command-name launches compatible with `.cmd` shims while
+ * allowing callers that already have a real executable path to opt out of the
+ * shell. The latter is important for paths such as `C:\\Program Files\\nodejs\\node.exe`.
+ */
+export function cliSpawnOptions(options = {}, platform = process.platform) {
+    return {
+        stdio: options.stdio ?? "inherit",
+        shell: options.shell ?? platform === "win32",
+        env: options.env ?? process.env,
+    };
+}

package/dist/cli/workspace-skill-policy.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Skills every generated workspace app can use without an app-local copy.
+ *
+ * Keep this list deliberately small. Skills outside this list remain available
+ * in the framework source and can be opted into by adding them to the
+ * workspace core or to the app that actually needs them.
+ */
+export declare const DEFAULT_WORKSPACE_SKILLS: readonly ["actions", "adding-a-feature", "agent-native-docs", "agent-native-toolkit", "context-awareness", "customizing-agent-native", "delegate-to-agent", "frontend-design", "turn-into-app", "turn-into-skill", "real-time-sync", "secrets", "security", "self-modifying-code", "shadcn-ui", "sharing", "storing-data", "portability", "workspace-conventions"];
+/**
+ * Framework skills that templates may carry before they are transformed into
+ * workspace apps. Workspacify removes these copies because the workspace core
+ * owns the inherited skill surface. App-specific skill names are intentionally
+ * not listed here and remain local.
+ */
+export declare const FRAMEWORK_TEMPLATE_SHARED_SKILLS: readonly ["actions", "agent-native-docs", "agent-native-toolkit", "adding-a-feature", "capture-learnings", "client-methods", "create-skill", "customizing-agent-native", "delegate-to-agent", "frontend-design", "feature-flags", "integration-webhooks", "internationalization", "onboarding", "performance", "real-time-collab", "real-time-sync", "security", "self-modifying-code", "shadcn-ui", "secrets", "storing-data", "sharing", "turn-into-app", "turn-into-skill", "upgrade-agent-native"];

package/dist/cli/workspace-skill-policy.js

@@ -0,0 +1,62 @@
+/**
+ * Skills every generated workspace app can use without an app-local copy.
+ *
+ * Keep this list deliberately small. Skills outside this list remain available
+ * in the framework source and can be opted into by adding them to the
+ * workspace core or to the app that actually needs them.
+ */
+export const DEFAULT_WORKSPACE_SKILLS = [
+    "actions",
+    "adding-a-feature",
+    "agent-native-docs",
+    "agent-native-toolkit",
+    "context-awareness",
+    "customizing-agent-native",
+    "delegate-to-agent",
+    "frontend-design",
+    "turn-into-app",
+    "turn-into-skill",
+    "real-time-sync",
+    "secrets",
+    "security",
+    "self-modifying-code",
+    "shadcn-ui",
+    "sharing",
+    "storing-data",
+    "portability",
+    "workspace-conventions",
+];
+/**
+ * Framework skills that templates may carry before they are transformed into
+ * workspace apps. Workspacify removes these copies because the workspace core
+ * owns the inherited skill surface. App-specific skill names are intentionally
+ * not listed here and remain local.
+ */
+export const FRAMEWORK_TEMPLATE_SHARED_SKILLS = [
+    "actions",
+    "agent-native-docs",
+    "agent-native-toolkit",
+    "adding-a-feature",
+    "capture-learnings",
+    "client-methods",
+    "create-skill",
+    "customizing-agent-native",
+    "delegate-to-agent",
+    "frontend-design",
+    "feature-flags",
+    "integration-webhooks",
+    "internationalization",
+    "onboarding",
+    "performance",
+    "real-time-collab",
+    "real-time-sync",
+    "security",
+    "self-modifying-code",
+    "shadcn-ui",
+    "secrets",
+    "storing-data",
+    "sharing",
+    "turn-into-app",
+    "turn-into-skill",
+    "upgrade-agent-native",
+];

package/dist/cli/workspacify.js

@@ -22,6 +22,7 @@
  */
 import fs from "fs";
 import path from "path";
+import { DEFAULT_WORKSPACE_SKILLS, FRAMEWORK_TEMPLATE_SHARED_SKILLS, } from "./workspace-skill-policy.js";
 const POSTGRES_DEPENDENCY_VERSION = "^3.4.9";
 const REACT_ROUTER_BUILD_DEPENDENCIES = [
     "@react-router/dev",
@@ -113,6 +114,11 @@ export function workspacifyApp(opts) {
             // Non-fatal: leave the file in place.
         }
     }
+    // Workspace-core owns framework skills. Keep only app-specific skill
+    // directories here, and expose the small inherited default set as symlinks
+    // so coding agents launched from this app see the same workspace guidance
+    // without another hard copy. Runtime agents inherit workspace-core directly.
+    linkInheritedWorkspaceSkills(opts);
     // 3) Templates document action commands from the framework repo layout.
     //    Workspace apps live under apps/<name>, so point every agent at the
     //    generated app directory instead.
@@ -137,6 +143,36 @@ export function workspacifyApp(opts) {
         writeInheritedChatAgentChatPlugin(appDir, workspaceCoreName, opts.appName);
     }
 }
+function linkInheritedWorkspaceSkills(opts) {
+    const appSkillsDir = path.join(opts.appDir, ".agents", "skills");
+    const workspaceSkillsDir = path.join(opts.workspaceRoot, ".agents", "skills");
+    if (!fs.existsSync(workspaceSkillsDir))
+        return;
+    fs.mkdirSync(appSkillsDir, { recursive: true });
+    for (const skill of FRAMEWORK_TEMPLATE_SHARED_SKILLS) {
+        const localPath = path.join(appSkillsDir, skill);
+        if (fs.existsSync(localPath) ||
+            fs.lstatSync(localPath, { throwIfNoEntry: false })) {
+            fs.rmSync(localPath, { recursive: true, force: true });
+        }
+    }
+    for (const skill of DEFAULT_WORKSPACE_SKILLS) {
+        const inheritedPath = path.join(workspaceSkillsDir, skill);
+        if (!fs.existsSync(inheritedPath))
+            continue;
+        const linkPath = path.join(appSkillsDir, skill);
+        if (fs.existsSync(linkPath) ||
+            fs.lstatSync(linkPath, { throwIfNoEntry: false })) {
+            fs.rmSync(linkPath, { recursive: true, force: true });
+        }
+        try {
+            fs.symlinkSync(path.relative(appSkillsDir, inheritedPath), linkPath, "dir");
+        }
+        catch (error) {
+            throw new Error(`Could not link inherited workspace skill ${skill} into ${appSkillsDir}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+}
 /**
  * The version an existing workspace already pins for a framework package.
  *

package/dist/client/AgentPanel.d.ts

@@ -26,6 +26,9 @@ import type { AssistantChatProps } from "./AssistantChat.js";
 import type { MultiTabAssistantChatHeaderProps, MultiTabAssistantChatProps } from "./MultiTabAssistantChat.js";
 type PanelMode = "chat" | "cli" | "resources" | "settings";
 export declare function normalizeAgentPanelModeForSurface(mode: PanelMode, allowSettingsMode: boolean, chatOnly?: boolean): PanelMode;
+export declare function deferAgentPanelOverlayOpen(event: {
+    preventDefault: () => void;
+}, closeMenu: () => void, openOverlay: () => void): void;
 export declare function getAgentPanelChatTabGroups(tabs: MultiTabAssistantChatHeaderProps["tabs"], activeTabId: string): {
     activeTab: import("./MultiTabAssistantChat.js").ChatTab | undefined;
     childTabs: import("./MultiTabAssistantChat.js").ChatTab[];
@@ -39,6 +42,13 @@ export declare function shouldShowAgentPanelPageNewChatButton(tabs: MultiTabAssi
 export declare function shouldShowAgentPanelCliTabBar(cliTabs: string[]): boolean;
 export declare function shouldShowAgentPanelModeButtons(isSidebar: boolean): boolean;
 export declare function shouldShowAgentPanelFullViewAction(agentPageHref: string | undefined, mode: PanelMode, isSidebar?: boolean, currentPath?: string): boolean;
+export declare function resolveAgentPanelFullViewAction(agentPageHref: string | undefined, onFullViewRequest: (() => void) | undefined, mode: PanelMode, isSidebar?: boolean, currentPath?: string): {
+    readonly kind: "callback";
+    readonly href?: undefined;
+} | {
+    readonly kind: "link";
+    readonly href: string;
+} | null;
 export declare function getAgentPanelShortcutHints(isMac: boolean): {
     closeTab: string;
     closeAllTabs: string;
@@ -76,6 +86,8 @@ export interface AgentPanelProps extends Omit<AssistantChatProps, "onSwitchToCli
     isFullscreen?: boolean;
     /** @deprecated Fullscreen sidebar controls are no longer rendered. */
     onToggleFullscreen?: () => void;
+    /** Called when the user selects the full-view action from a sidebar chat. */
+    onFullViewRequest?: () => void;
     /** Called when the user asks the sidebar to use the wide chat width preset. */
     onSnapTo75Percent?: () => void;
     /** Whether the sidebar is currently using the wide fixed drawer presentation. */
@@ -186,7 +198,7 @@ export interface AgentSidebarProps {
     storageKey?: string;
     /** Open the sidebar when a chat run is active or reconnects. */
     openOnChatRunning?: boolean;
-    /** @deprecated Fullscreen sidebar actions are no longer rendered. */
+    /** Called when the user selects the full-view action from the chat sidebar. */
     onFullscreenRequest?: () => void;
     /** Ambient resource context rendered as a composer chip. */
     scope?: import("./use-chat-threads.js").ChatThreadScope | null;
@@ -205,7 +217,7 @@ export interface AgentSidebarProps {
  * Wraps app content with a toggleable agent sidebar.
  * Use AgentToggleButton in your header to open/close it.
  */
-export declare function AgentSidebar({ children, emptyStateText, suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position, defaultOpen, animateMobile, animateDesktop, chatViewTransition, chatViewTransitionHandoff, storageKey, openOnChatRunning, scope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding, }: AgentSidebarProps): React.JSX.Element;
+export declare function AgentSidebar({ children, emptyStateText, suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position, defaultOpen, animateMobile, animateDesktop, chatViewTransition, chatViewTransitionHandoff, storageKey, openOnChatRunning, onFullscreenRequest, scope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding, }: AgentSidebarProps): React.JSX.Element;
 /**
  * Focus the agent chat composer input.
  * Opens the sidebar if closed, then focuses the text input.

package/dist/client/AgentPanel.js

@@ -53,6 +53,7 @@ import { RealtimeVoiceModeProvider } from "./composer/index.js";
 import { getFramePostMessageTargetOrigin, isTrustedFrameMessage, } from "./frame.js";
 import { useT } from "./i18n.js";
 import { isFirstRunOnboardingEnabled } from "./onboarding/first-run-enabled.js";
+import { useFirstRunOnboardingGateOwnsSurface } from "./onboarding/first-run-startup-gate.js";
 import { useOnboardingPreviewMode } from "./onboarding/use-preview-mode.js";
 import { recoverFromStaleChunkError } from "./route-chunk-recovery.js";
 import { withBuilderConnectTrackingParams } from "./settings/useBuilderStatus.js";
@@ -145,6 +146,17 @@ const AGENT_PANEL_CONTROL_STYLE = {
     lineHeight: 1,
 };
 const ACTIVATE_KEYS = new Set(["Enter", " "]);
+export function deferAgentPanelOverlayOpen(event, closeMenu, openOverlay) {
+    event.preventDefault();
+    closeMenu();
+    if (typeof window !== "undefined" &&
+        typeof window.requestAnimationFrame === "function") {
+        window.requestAnimationFrame(() => openOverlay());
+    }
+    else {
+        setTimeout(openOverlay, 0);
+    }
+}
 function useAvailableClis() {
     const [clis, setClis] = useState([]);
     useEffect(() => {
@@ -246,6 +258,15 @@ export function shouldShowAgentPanelFullViewAction(agentPageHref, mode, isSideba
         currentPath !== agentPageHref &&
         (isSidebar || mode === "resources" || mode === "settings"));
 }
+export function resolveAgentPanelFullViewAction(agentPageHref, onFullViewRequest, mode, isSidebar = false, currentPath) {
+    if (!agentPageHref ||
+        !shouldShowAgentPanelFullViewAction(agentPageHref, mode, isSidebar, currentPath)) {
+        return null;
+    }
+    return onFullViewRequest
+        ? { kind: "callback" }
+        : { kind: "link", href: agentPageHref };
+}
 export function getAgentPanelShortcutHints(isMac) {
     return {
         closeTab: isMac ? "⌃W" : "⌥W",
@@ -398,13 +419,15 @@ function CodeAccessUnavailablePanel({ title, description, ctaLabel, ctaHref, sec
                             });
                         }, className: "inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent", children: secondaryCtaLabel })] })] }));
 }
-function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, emptyStateText, emptyStateAddon, suggestions, dynamicSuggestions, showHeader = true, onCollapse, isFullscreen, onToggleFullscreen, onSnapTo75Percent, isWideDrawer, onExitWideDrawer, devAppUrl, storageKey, restoreActiveThread = true, scope, showScopeBadge, browserTabId, threadUrlSync, chatNotice, showTabBar = true, showPageNewChatButton = false, allowSettingsMode = true, chatOnly = false, agentPageHref, codeAccess, ...assistantChatProps }) {
+function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, emptyStateText, emptyStateAddon, suggestions, dynamicSuggestions, showHeader = true, onCollapse, isFullscreen, onToggleFullscreen, onFullViewRequest, onSnapTo75Percent, isWideDrawer, onExitWideDrawer, devAppUrl, storageKey, restoreActiveThread = true, scope, showScopeBadge, browserTabId, threadUrlSync, chatNotice, showTabBar = true, showPageNewChatButton = false, allowSettingsMode = true, chatOnly = false, agentPageHref, codeAccess, ...assistantChatProps }) {
     const t = useT();
     const navigate = useNavigate();
     const location = useLocation();
     const mounted = useClientOnly();
     const onboardingPreviewMode = useOnboardingPreviewMode();
-    const showFirstRunOnboarding = SHOW_FIRST_RUN_ONBOARDING || onboardingPreviewMode;
+    const firstRunOnboardingGateOwnsSurface = useFirstRunOnboardingGateOwnsSurface();
+    const showFirstRunOnboarding = !firstRunOnboardingGateOwnsSurface &&
+        (SHOW_FIRST_RUN_ONBOARDING || onboardingPreviewMode);
     const insideAgentSidebar = React.useContext(AgentSidebarOnboardingContext);
     const isFirstRunOnboardingSurface = showFirstRunOnboarding && !insideAgentSidebar;
     const feedbackEnabled = resolveFeedbackUrl(undefined, mounted ? undefined : null) !== null;
@@ -657,8 +680,7 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
     }, [threadUrlSync]);
     const wideDrawerAction = isWideDrawer ? onExitWideDrawer : onSnapTo75Percent;
     const wideDrawerLabel = t(isWideDrawer ? "agentPanel.returnChatToLayout" : "agentPanel.widenChat");
-    const showFullViewAction = Boolean(agentPageHref &&
-        shouldShowAgentPanelFullViewAction(agentPageHref, mode, chatOnly, location.pathname));
+    const fullViewAction = resolveAgentPanelFullViewAction(agentPageHref, onFullViewRequest, mode, chatOnly, location.pathname);
     useEffect(() => {
         const handleKeyDown = (event) => {
             if (!(event.metaKey || event.ctrlKey) ||
@@ -687,10 +709,10 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
                         (activeTabMessageCount <= 0 && activeTab.status === "idle")) {
                         return null;
                     }
-                    return (_jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "icon", triggerClassName: "h-7 w-7" }));
+                    return (_jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, allowedRoles: ["viewer", "editor", "admin"], resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "icon", triggerClassName: "h-7 w-7" }));
                 })(), feedbackEnabled ? (_jsx(FeedbackButton, { variant: "icon", side: "bottom", align: "end", chatSessionId: activeChatSessionId, chatStorageKey: storageKey, open: feedbackOpen, onOpenChange: setFeedbackOpen, trigger: _jsx("button", { type: "button", tabIndex: -1, "aria-hidden": "true", className: "pointer-events-none absolute end-0 top-full h-px w-px opacity-0" }) })) : null, mode === "chat" && (_jsx(IconTooltip, { content: t("agentPanel.newChat"), children: _jsx("button", { onClick: addTab, "aria-label": t("agentPanel.newChat"), className: "flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:text-foreground hover:bg-accent/50", children: _jsx(IconPlus, { size: 14 }) }) })), !onCollapse && mode === "cli" && canUseCodeTools && (_jsx(IconTooltip, { content: t("agentPanel.newTerminal"), children: _jsx("button", { onClick: addCliTab, "aria-label": t("agentPanel.newTerminal"), className: "flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:text-foreground hover:bg-accent/50", children: _jsx(IconPlus, { size: 14 }) }) })), _jsxs(DropdownMenu, { open: headerMenuOpen, onOpenChange: setHeaderMenuOpen, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx("button", { className: cn("flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:text-foreground hover:bg-accent/50", (headerMenuOpen || mode === "settings") &&
-                                "bg-accent text-foreground"), "aria-label": t("agentPanel.panelOptions"), children: _jsx(IconDotsVertical, { size: 14 }) }) }), _jsxs(DropdownMenuContent, { align: "end", sideOffset: 6, className: "w-48", children: [onCollapse && (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: onCollapse, children: [_jsx(IconLayoutSidebarRightCollapse, { size: 14, className: "shrink-0" }), t("agentPanel.collapseSidebar"), _jsx(DropdownMenuShortcut, { children: toggleSidebarHint })] }), _jsx(DropdownMenuSeparator, {})] })), onCollapse && mode === "chat" && wideDrawerAction ? (_jsxs(DropdownMenuItem, { onSelect: wideDrawerAction, children: [_jsx(IconArrowsHorizontal, { size: 14, className: "shrink-0" }), wideDrawerLabel, _jsx(DropdownMenuShortcut, { children: widenChatHint })] })) : null, showFullViewAction && agentPageHref ? (_jsx(DropdownMenuItem, { asChild: true, children: _jsxs(Link, { to: agentPageHref, "aria-label": t("agentPanel.openFullView"), children: [_jsx(IconArrowsMaximize, { size: 14, className: "shrink-0" }), t("agentPanel.openFullView")] }) })) : null, (onCollapse && mode === "chat" && wideDrawerAction) ||
-                                showFullViewAction ? (_jsx(DropdownMenuSeparator, {})) : null, onCollapse && mode === "chat" && (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: addTab, children: [_jsx(IconPlus, { size: 14, className: "shrink-0" }), t("agentPanel.newChat")] }), (() => {
+                                "bg-accent text-foreground"), "aria-label": t("agentPanel.panelOptions"), children: _jsx(IconDotsVertical, { size: 14 }) }) }), _jsxs(DropdownMenuContent, { align: "end", sideOffset: 6, className: "w-48", children: [onCollapse && (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: onCollapse, children: [_jsx(IconLayoutSidebarRightCollapse, { size: 14, className: "shrink-0" }), t("agentPanel.collapseSidebar"), _jsx(DropdownMenuShortcut, { children: toggleSidebarHint })] }), _jsx(DropdownMenuSeparator, {})] })), onCollapse && mode === "chat" && wideDrawerAction ? (_jsxs(DropdownMenuItem, { onSelect: wideDrawerAction, children: [_jsx(IconArrowsHorizontal, { size: 14, className: "shrink-0" }), wideDrawerLabel, _jsx(DropdownMenuShortcut, { children: widenChatHint })] })) : null, fullViewAction?.kind === "callback" && onFullViewRequest ? (_jsxs(DropdownMenuItem, { onSelect: onFullViewRequest, "aria-label": t("agentPanel.openFullView"), children: [_jsx(IconArrowsMaximize, { size: 14, className: "shrink-0" }), t("agentPanel.openFullView")] })) : fullViewAction?.kind === "link" ? (_jsx(DropdownMenuItem, { asChild: true, children: _jsxs(Link, { to: fullViewAction.href, "aria-label": t("agentPanel.openFullView"), children: [_jsx(IconArrowsMaximize, { size: 14, className: "shrink-0" }), t("agentPanel.openFullView")] }) })) : null, (onCollapse && mode === "chat" && wideDrawerAction) ||
+                                fullViewAction ? (_jsx(DropdownMenuSeparator, {})) : null, onCollapse && mode === "chat" && (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: addTab, children: [_jsx(IconPlus, { size: 14, className: "shrink-0" }), t("agentPanel.newChat")] }), (() => {
                                         const activeTab = activeChatSessionId
                                             ? tabs.find((tab) => tab.id === activeChatSessionId)
                                             : undefined;
@@ -698,21 +720,12 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
                                             (activeTabMessageCount <= 0 && activeTab.status === "idle")) {
                                             return null;
                                         }
-                                        return (_jsx("div", { className: "p-1", children: _jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "label-icon", triggerClassName: "w-full justify-start" }) }));
-                                    })()] })), mode === "chat" && toggleHistory && (_jsxs(DropdownMenuItem, { onSelect: () => {
-                                    // Let the menu finish restoring focus before mounting the
-                                    // history popover; otherwise Radix dismisses the new overlay.
-                                    setTimeout(() => toggleHistory(), 0);
-                                }, children: [_jsx(IconHistory, { size: 14, className: "shrink-0" }), showHistory
+                                        return (_jsx("div", { className: "p-1", children: _jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, allowedRoles: ["viewer", "editor", "admin"], resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "label-icon", triggerClassName: "w-full justify-start" }) }));
+                                    })()] })), mode === "chat" && toggleHistory && (_jsxs(DropdownMenuItem, { onSelect: (event) => deferAgentPanelOverlayOpen(event, () => setHeaderMenuOpen(false), toggleHistory), children: [_jsx(IconHistory, { size: 14, className: "shrink-0" }), showHistory
                                         ? t("agentPanel.hideChats")
                                         : t("agentPanel.allChats")] })), mode === "chat" && (_jsx(RunsTrayMenuItem, { pollMs: 0, limit: 12, showRecent: true, onOpenThread: openRunThread })), mode === "chat" && _jsx(DropdownMenuSeparator, {}), mode === "cli" && availableClis.length > 0 && (_jsxs(_Fragment, { children: [availableClis.map((cli) => (_jsxs(DropdownMenuItem, { onSelect: () => selectCli(cli.command), className: cn(cli.command === selectedCli
                                             ? "font-medium"
-                                            : "text-muted-foreground"), children: [cli.command === selectedCli ? (_jsx(IconCheck, { size: 12, className: "shrink-0" })) : (_jsx("span", { className: "w-3" })), cli.label] }, cli.command))), _jsx(DropdownMenuSeparator, {})] })), allowSettingsMode && (_jsxs(DropdownMenuItem, { onSelect: () => switchMode("settings"), className: cn(mode === "settings" ? "font-medium" : "text-muted-foreground"), children: [_jsx(IconSettings, { size: 14, className: "shrink-0" }), t("agentPanel.settings")] })), feedbackEnabled ? (_jsxs(DropdownMenuItem, { onSelect: () => {
-                                    // Defer past the closing DropdownMenu's focus-restore/dismiss-layer
-                                    // teardown, otherwise it can immediately dismiss the Popover we're
-                                    // opening in the same tick (Radix nested-overlay race).
-                                    setTimeout(() => setFeedbackOpen(true), 0);
-                                }, children: [_jsx(IconMessageDots, { size: 14, className: "shrink-0" }), t("agentPanel.feedback")] })) : null, ((mode === "chat" && activeTabId) ||
+                                            : "text-muted-foreground"), children: [cli.command === selectedCli ? (_jsx(IconCheck, { size: 12, className: "shrink-0" })) : (_jsx("span", { className: "w-3" })), cli.label] }, cli.command))), _jsx(DropdownMenuSeparator, {})] })), allowSettingsMode && (_jsxs(DropdownMenuItem, { onSelect: () => switchMode("settings"), className: cn(mode === "settings" ? "font-medium" : "text-muted-foreground"), children: [_jsx(IconSettings, { size: 14, className: "shrink-0" }), t("agentPanel.settings")] })), feedbackEnabled ? (_jsxs(DropdownMenuItem, { onSelect: (event) => deferAgentPanelOverlayOpen(event, () => setHeaderMenuOpen(false), () => setFeedbackOpen(true)), children: [_jsx(IconMessageDots, { size: 14, className: "shrink-0" }), t("agentPanel.feedback")] })) : null, ((mode === "chat" && activeTabId) ||
                                 (mode === "cli" && canUseCodeTools && activeCliTab)) && (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), mode === "chat" ? (shouldShowAgentPanelChatTabBar(tabs, activeTabId) ? (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: () => closeTab(activeTabId), children: [_jsx(IconX, { size: 14, className: "shrink-0" }), t("agentPanel.closeTab"), _jsx(DropdownMenuShortcut, { children: closeTabHint })] }), _jsx(DropdownMenuItem, { onSelect: () => closeOtherTabs(activeTabId), children: t("agentPanel.closeOtherTabs") }), _jsxs(DropdownMenuItem, { onSelect: () => closeAllTabs(), children: [t("agentPanel.closeAllTabs"), _jsx(DropdownMenuShortcut, { children: closeAllTabsHint })] })] })) : (_jsxs(DropdownMenuItem, { onSelect: clearActiveTab, children: [_jsx(IconX, { size: 14, className: "shrink-0" }), t("agentPanel.clearChat")] }))) : (_jsxs(_Fragment, { children: [_jsxs(DropdownMenuItem, { onSelect: () => closeCliTab(activeCliTab), children: [_jsx(IconX, { size: 14, className: "shrink-0" }), t("agentPanel.closeTab"), _jsx(DropdownMenuShortcut, { children: closeTabHint })] }), _jsx(DropdownMenuItem, { onSelect: () => closeOtherCliTabs(activeCliTab), children: t("agentPanel.closeOtherTabs") }), _jsxs(DropdownMenuItem, { onSelect: () => closeAllCliTabs(), children: [t("agentPanel.closeAllTabs"), _jsx(DropdownMenuShortcut, { children: closeAllTabsHint })] })] }))] }))] })] }), onCollapse && (_jsx(IconTooltip, { content: t("agentPanel.collapseSidebar"), children: _jsx("button", { type: "button", onClick: onCollapse, "aria-label": t("agentPanel.collapseSidebar"), className: "flex h-6 w-6 items-center justify-center rounded text-muted-foreground hover:text-foreground hover:bg-accent/50", children: _jsx(IconX, { size: 14 }) }) }))] })), [
         activeCliTab,
         addCliTab,
@@ -731,7 +744,9 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
         isWideDrawer,
         mode,
         agentPageHref,
+        fullViewAction,
         onCollapse,
+        onFullViewRequest,
         onExitWideDrawer,
         onSnapTo75Percent,
         openRunThread,
@@ -743,7 +758,6 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
         wideDrawerAction,
         wideDrawerLabel,
         widenChatHint,
-        showFullViewAction,
     ]);
     const renderPageChatOverlay = useCallback(({ activeTabId, activeTabMessageCount, addTab, tabs, }) => {
         if (!shouldShowAgentPanelPageNewChatButton(tabs, activeTabId, activeTabMessageCount)) {
@@ -753,7 +767,7 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
             ? tabs.find((tab) => tab.id === activeTabId)
             : undefined;
         const canShareActiveTab = activeTab && (activeTabMessageCount > 0 || activeTab.status !== "idle");
-        return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", "data-agent-page-chat-fade": "", className: "pointer-events-none absolute inset-x-0 top-0 z-50 h-16 bg-gradient-to-b from-background via-background/90 to-transparent opacity-0 transition-opacity duration-150" }), _jsx("div", { className: "pointer-events-none absolute inset-x-0 top-3 z-[60] flex justify-end px-3 sm:top-4 sm:px-4", children: _jsxs("div", { className: "pointer-events-auto flex items-center gap-1", children: [canShareActiveTab ? (_jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "icon", triggerClassName: "h-8 w-8 border border-border bg-background/95 shadow-sm backdrop-blur hover:bg-accent" })) : null, _jsxs("button", { type: "button", "data-agent-page-new-chat": "", "aria-label": t("agentPanel.newChat"), onClick: () => {
+        return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", "data-agent-page-chat-fade": "", className: "pointer-events-none absolute inset-x-0 top-0 z-50 h-16 bg-gradient-to-b from-background via-background/90 to-transparent opacity-0 transition-opacity duration-150" }), _jsx("div", { className: "pointer-events-none absolute inset-x-0 top-3 z-[60] flex justify-end px-3 sm:top-4 sm:px-4", children: _jsxs("div", { className: "pointer-events-auto flex items-center gap-1", children: [canShareActiveTab ? (_jsx(ShareButton, { resourceType: "chat_thread", resourceId: activeTab.id, allowedRoles: ["viewer", "editor", "admin"], resourceTitle: activeTab.label || "Chat", shareUrl: getChatThreadShareUrl(activeTab.id), trigger: "icon", triggerClassName: "h-8 w-8 border border-border bg-background/95 shadow-sm backdrop-blur hover:bg-accent" })) : null, _jsxs("button", { type: "button", "data-agent-page-new-chat": "", "aria-label": t("agentPanel.newChat"), onClick: () => {
                                     addTab();
                                 }, className: "inline-flex h-8 items-center gap-1.5 rounded-md border border-border bg-background/95 px-2.5 text-xs font-medium text-foreground shadow-sm backdrop-blur transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(IconPlus, { size: 14 }), _jsx("span", { children: t("agentPanel.newChat") })] })] }) })] }));
     }, [getChatThreadShareUrl, t]);
@@ -1373,9 +1387,11 @@ export function AgentChatSurface({ mode = "panel", className, defaultMode = "cha
  * Wraps app content with a toggleable agent sidebar.
  * Use AgentToggleButton in your header to open/close it.
  */
-export function AgentSidebar({ children, emptyStateText = "How can I help you?", suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position = "right", defaultOpen = false, animateMobile = true, animateDesktop = true, chatViewTransition = false, chatViewTransitionHandoff = false, storageKey, openOnChatRunning = false, scope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding = false, }) {
+export function AgentSidebar({ children, emptyStateText = "How can I help you?", suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position = "right", defaultOpen = false, animateMobile = true, animateDesktop = true, chatViewTransition = false, chatViewTransitionHandoff = false, storageKey, openOnChatRunning = false, onFullscreenRequest, scope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding = false, }) {
     const onboardingPreviewMode = useOnboardingPreviewMode();
-    const showFirstRunOnboarding = !suppressFirstRunOnboarding &&
+    const firstRunOnboardingGateOwnsSurface = useFirstRunOnboardingGateOwnsSurface();
+    const showFirstRunOnboarding = !firstRunOnboardingGateOwnsSurface &&
+        !suppressFirstRunOnboarding &&
         (SHOW_FIRST_RUN_ONBOARDING || onboardingPreviewMode);
     const initialWidth = defaultSidebarWidth ?? sidebarWidth ?? 380;
     const [open, setOpen] = useState(() => openOnChatRunning || getInitialAgentSidebarOpen(defaultOpen, storageKey));
@@ -1888,7 +1904,7 @@ export function AgentSidebar({ children, emptyStateText = "How can I help you?",
                             ? "desktop"
                             : undefined, "data-agent-sidebar-layout": panelLayout, "data-agent-sidebar-position": position, "data-agent-sidebar-state": panelOpen ? "open" : "closed", "data-agent-sidebar-resizing": isResizing ? "true" : undefined, "data-agent-sidebar-chat-handoff": chatViewTransitionHandoff ? "true" : undefined, style: chatViewTransition
                     ? getAgentChatViewTransitionStyle(panelStyle)
-                    : panelStyle, inert: sidebarAnimationEnabled && !panelOpen ? true : undefined, "aria-hidden": sidebarAnimationEnabled && !panelOpen ? true : undefined, children: _jsx("div", { className: "agent-sidebar-panel-inner flex min-h-0 flex-1 flex-col", children: _jsx(AgentPanel, { emptyStateText: emptyStateText, suggestions: suggestions, dynamicSuggestions: dynamicSuggestions, composerToolbarSlot: composerToolbarSlot, composerSlot: composerSlot, onComposerTextChange: onComposerTextChange, imageModelMenu: imageModelMenu, threadFooterSlot: threadFooterSlot, missingApiKeySetupLayout: "sidebar", onCollapse: () => setOpenPersisted(false), onSnapTo75Percent: isMobile ? undefined : snapTo75Percent, isWideDrawer: isMobile ? false : isWideDrawer, onExitWideDrawer: isMobile ? undefined : exitWideDrawer, storageKey: storageKey, scope: scope, showScopeBadge: showScopeBadge, browserTabId: browserTabId, threadUrlSync: threadUrlSync, agentPageHref: agentPageHref, allowSettingsMode: false, chatOnly: true }) }) }), showResizeHandle && isLeft && (_jsx(ResizeHandle, { position: position, onDrag: handleDrag, onResizeStart: handleResizeStart, onResizeEnd: handleResizeEnd }))] })) : null;
+                    : panelStyle, inert: sidebarAnimationEnabled && !panelOpen ? true : undefined, "aria-hidden": sidebarAnimationEnabled && !panelOpen ? true : undefined, children: _jsx("div", { className: "agent-sidebar-panel-inner flex min-h-0 flex-1 flex-col", children: _jsx(AgentPanel, { emptyStateText: emptyStateText, suggestions: suggestions, dynamicSuggestions: dynamicSuggestions, composerToolbarSlot: composerToolbarSlot, composerSlot: composerSlot, onComposerTextChange: onComposerTextChange, imageModelMenu: imageModelMenu, threadFooterSlot: threadFooterSlot, missingApiKeySetupLayout: "sidebar", onCollapse: () => setOpenPersisted(false), onSnapTo75Percent: isMobile ? undefined : snapTo75Percent, isWideDrawer: isMobile ? false : isWideDrawer, onExitWideDrawer: isMobile ? undefined : exitWideDrawer, onFullViewRequest: onFullscreenRequest, storageKey: storageKey, scope: scope, showScopeBadge: showScopeBadge, browserTabId: browserTabId, threadUrlSync: threadUrlSync, agentPageHref: agentPageHref, allowSettingsMode: false, chatOnly: true }) }) }), showResizeHandle && isLeft && (_jsx(ResizeHandle, { position: position, onDrag: handleDrag, onResizeStart: handleResizeStart, onResizeEnd: handleResizeEnd }))] })) : null;
     const drawerPlaceholder = wideDrawerEnabled && !presentationMode && panelOpen ? (_jsx("div", { "aria-hidden": "true", className: "agent-sidebar-drawer-placeholder shrink-0", "data-agent-sidebar-placeholder": "true", style: { width: drawerPlaceholderWidth + 1 } })) : null;
     return (_jsx(AgentSidebarOnboardingContext.Provider, { value: true, children: _jsxs(RealtimeVoiceModeProvider, { browserTabId: browserTabId, children: [showFirstRunOnboarding && (_jsx(Suspense, { fallback: null, children: _jsx(FirstRunOnboarding, {}) })), _jsxs("div", { className: "agent-sidebar-shell flex min-w-0 flex-1 h-screen overflow-hidden", "data-agent-sidebar-position": position, "data-agent-sidebar-resizing": isResizing ? "true" : undefined, children: [isMobile &&
                             !presentationMode &&