@agent-native/core 0.137.8 → 0.138.0

package/dist/cli/create.js

@@ -395,6 +395,7 @@ async function createWorkspaceInteractive(name, opts, clack) {
                 ...resolution,
                 shape: "workspace",
             });
+            ensureGuardedScaffold(appDir);
             fixWebManifestName(appDir, appName, templateName, resolution.sourceIdentity);
             rewriteNetlifyToml(appDir, appName, "workspace");
             renameGitignore(appDir);
@@ -523,6 +524,7 @@ async function scaffoldWorkspaceRoot(targetDir, name) {
     // Root-level agent instructions apply before an agent descends into an app.
     linkWorkspaceRootSkills(targetDir);
     setupAgentSymlinks(targetDir);
+    ensureGuardedScaffold(targetDir);
 }
 function linkWorkspaceRootSkills(targetDir) {
     const sharedSkillsDir = path.join(targetDir, "packages", "shared", ".agents", "skills");
@@ -650,6 +652,7 @@ async function scaffoldOneAppIntoWorkspace(workspace, appName, templateName, cla
             ...resolution,
             shape: "workspace",
         });
+        ensureGuardedScaffold(appDir);
         fixWebManifestName(appDir, appName, templateName, resolution.sourceIdentity);
         rewriteNetlifyToml(appDir, appName, "workspace");
         renameGitignore(appDir);
@@ -1266,6 +1269,95 @@ async function scaffoldRequiredPackages(templateNames, workspaceRoot) {
         }
     }
 }
+const AGENT_NATIVE_DOCTOR = "agent-native doctor";
+const AGENT_NATIVE_DOCTOR_STRICT = `${AGENT_NATIVE_DOCTOR} --strict`;
+const GUARDED_VERIFICATION_MARKER = "Guarded verification";
+const GUARDED_VERIFICATION_GUIDANCE = "- Guarded verification: run `pnpm agent-native:doctor`; fix findings before done.\n";
+/**
+ * Keep the portable guard contract attached to every app/workspace created by
+ * the CLI, including community templates whose package.json was not authored
+ * by this repository. The scanners stay versioned in @agent-native/core; a
+ * generated project only receives the small command/config/instructions
+ * surface needed to run them locally and in hosted builds.
+ */
+function ensureGuardedScaffold(appDir) {
+    const packagePath = path.join(appDir, "package.json");
+    if (!fs.existsSync(packagePath))
+        return;
+    const parsedPackage = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+    if (!parsedPackage ||
+        typeof parsedPackage !== "object" ||
+        Array.isArray(parsedPackage)) {
+        throw new Error(`${packagePath} must contain a JSON object`);
+    }
+    const packageJson = parsedPackage;
+    const existingScripts = packageJson.scripts;
+    if (existingScripts !== undefined &&
+        (!existingScripts ||
+            typeof existingScripts !== "object" ||
+            Array.isArray(existingScripts))) {
+        throw new Error(`${packagePath} has an invalid scripts object`);
+    }
+    const scripts = existingScripts ?? {};
+    // Keep an existing project-specific `doctor` script intact while providing
+    // a collision-free framework entry point that every generated project has.
+    const existingNativeDoctor = scripts["agent-native:doctor"];
+    scripts["agent-native:doctor"] =
+        typeof existingNativeDoctor === "string" &&
+            existingNativeDoctor !== AGENT_NATIVE_DOCTOR &&
+            !existingNativeDoctor.includes(AGENT_NATIVE_DOCTOR)
+            ? `${existingNativeDoctor} && ${AGENT_NATIVE_DOCTOR}`
+            : AGENT_NATIVE_DOCTOR;
+    if (typeof scripts.doctor !== "string") {
+        scripts.doctor = AGENT_NATIVE_DOCTOR;
+    }
+    // Community templates may use vite/next/another build command instead of
+    // `agent-native build`, so attach the strict check to the package lifecycle.
+    // Agent-Native builds already run doctor and get strictness from the config.
+    if (typeof scripts.build === "string" &&
+        !/\bagent-native\s+build\b/.test(scripts.build) &&
+        !String(scripts.prebuild ?? "").includes(AGENT_NATIVE_DOCTOR_STRICT)) {
+        const existingPrebuild = typeof scripts.prebuild === "string" ? scripts.prebuild.trim() : "";
+        scripts.prebuild = existingPrebuild
+            ? `${existingPrebuild} && ${AGENT_NATIVE_DOCTOR_STRICT}`
+            : AGENT_NATIVE_DOCTOR_STRICT;
+    }
+    packageJson.scripts = scripts;
+    fs.writeFileSync(packagePath, JSON.stringify(packageJson, null, 2) + "\n");
+    const manifestPath = path.join(appDir, "agent-native.json");
+    let manifest = {};
+    if (fs.existsSync(manifestPath)) {
+        const parsedManifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        if (!parsedManifest ||
+            typeof parsedManifest !== "object" ||
+            Array.isArray(parsedManifest)) {
+            throw new Error(`${manifestPath} must contain a JSON object`);
+        }
+        manifest = parsedManifest;
+    }
+    const doctor = manifest.doctor &&
+        typeof manifest.doctor === "object" &&
+        !Array.isArray(manifest.doctor)
+        ? manifest.doctor
+        : {};
+    // An explicit false remains an intentional, reviewable opt-out. Missing
+    // configuration is strict so a hosted build cannot publish a finding.
+    if (typeof doctor.failOnBuild !== "boolean")
+        doctor.failOnBuild = true;
+    manifest.doctor = doctor;
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    const agentsPath = path.join(appDir, "AGENTS.md");
+    if (fs.existsSync(agentsPath)) {
+        const agents = fs.readFileSync(agentsPath, "utf-8");
+        if (!agents.includes(GUARDED_VERIFICATION_MARKER)) {
+            fs.writeFileSync(agentsPath, `${agents.trimEnd()}\n\n${GUARDED_VERIFICATION_GUIDANCE}`);
+        }
+    }
+    else {
+        fs.writeFileSync(agentsPath, `# Agent-Native project instructions\n\n${GUARDED_VERIFICATION_GUIDANCE}`);
+        setupAgentSymlinks(appDir);
+    }
+}
 /**
  * Post-process a standalone scaffold: replace placeholders, strip
  * workspace:* deps, set up agent symlinks, etc.
@@ -1278,6 +1370,7 @@ function postProcessStandalone(name, targetDir, templateName, resolution) {
         ...resolution,
         shape: "standalone",
     });
+    ensureGuardedScaffold(targetDir);
     fixWebManifestName(targetDir, name, templateName, resolution?.sourceIdentity);
     rewriteNetlifyToml(targetDir, name, "standalone");
     for (const base of ["learnings"]) {
@@ -1562,7 +1655,7 @@ 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, 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, 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
  * ───────────────────────────────────────────────────────────────────────── */

package/dist/cli/doctor.d.ts

@@ -1,5 +1,5 @@
 import { type MigrationManifest } from "../package-lifecycle/index.js";
-export type GuardName = "no-drizzle-push" | "no-unscoped-credentials" | "no-unscoped-queries" | "no-env-credentials" | "db-tool-scoping" | "no-env-mutation" | "no-localhost-fallback" | "explicit-collab-access" | "migration-manifest";
+export type GuardName = "no-drizzle-push" | "no-empty-migrations" | "no-unscoped-credentials" | "no-unscoped-queries" | "no-env-credentials" | "db-tool-scoping" | "no-env-mutation" | "no-localhost-fallback" | "explicit-collab-access" | "migration-manifest";
 export declare const ALL_GUARD_NAMES: GuardName[];
 export interface DoctorConfig {
     disabledGuards: string[];
@@ -73,8 +73,8 @@ export declare function checkDisk(root: string, { measureReclaimable }?: {
 }): DoctorDiskReport;
 /** Pure escalation rule shared by the CLI (`--strict`) and the `build`
  * pre-step (`--strict` / `agent-native.json` `doctor.failOnBuild`). Doctor
- * findings never fail anything on their own — only `strict` or
- * `failOnBuild` turn findings into a hard failure. */
+ * findings fail builds by default; only an explicit `failOnBuild: false`
+ * opt-out can keep a build moving, while `strict` always fails. */
 export declare function shouldFailBuild(hasFindings: boolean, opts: {
     strict?: boolean;
     failOnBuild?: boolean;
@@ -104,19 +104,16 @@ export interface DoctorBuildHookOptions {
     strict?: boolean;
 }
 export interface DoctorBuildHookResult {
-    /** False only when findings are present AND (`strict` was requested OR
-     * `agent-native.json`'s `doctor.failOnBuild` is true). */
+    /** False when findings are present and the project has not explicitly
+     * opted out of the build gate. */
     ok: boolean;
     report: DoctorReport;
 }
 /**
  * `agent-native build`'s doctor pre-step. Always runs every enabled guard
- * and always prints findings (as warnings) to `io.err` — never silent.
- * Never causes the build to fail unless `strict` was passed or
- * `agent-native.json` sets `doctor.failOnBuild: true` (see report 005,
- * "Where it runs" — the v1 doctor has zero field mileage against arbitrary
- * app layouts, so shipping fail-by-default would risk breaking a first
- * deploy on a false positive).
+ * and always prints findings to `io.err` — never silent. Findings fail the
+ * build by default; only an explicit `doctor.failOnBuild: false` opt-out can
+ * keep a build moving, while `--strict` overrides that opt-out.
  */
 export declare function runDoctorBuildHook(options: DoctorBuildHookOptions, io?: DoctorIo): Promise<DoctorBuildHookResult>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.js

@@ -22,11 +22,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { scanDbToolScoping, scanDrizzlePush, scanEnvCredentials, scanEnvMutation, scanExplicitCollabAccess, scanLocalhostFallback, scanUnscopedCredentials, scanUnscopedQueries, } from "../guards/index.js";
+import { scanDbToolScoping, scanDrizzlePush, scanEmptyMigrations, scanEnvCredentials, scanEnvMutation, scanExplicitCollabAccess, scanLocalhostFallback, scanUnscopedCredentials, scanUnscopedQueries, } from "../guards/index.js";
 import { AGENT_NATIVE_UPGRADE_CODEMOD_COMMAND, scanDeprecatedImports, } from "../package-lifecycle/index.js";
 import { formatBytes, scanCleanTargets } from "./clean.js";
 export const ALL_GUARD_NAMES = [
     "no-drizzle-push",
+    "no-empty-migrations",
     "no-unscoped-credentials",
     "no-unscoped-queries",
     "no-env-credentials",
@@ -39,7 +40,7 @@ export const ALL_GUARD_NAMES = [
 const DEFAULT_DOCTOR_CONFIG = {
     disabledGuards: [],
     dbToolScopingDenylist: {},
-    failOnBuild: false,
+    failOnBuild: true,
 };
 /**
  * Reads the optional `"doctor"` key from `<root>/agent-native.json`. All
@@ -62,17 +63,21 @@ export function readDoctorConfig(root) {
             typeof doctor.dbToolScopingDenylist === "object"
             ? Object.fromEntries(Object.entries(doctor.dbToolScopingDenylist).filter((entry) => typeof entry[1] === "string"))
             : {};
-        const failOnBuild = doctor.failOnBuild === true;
+        const failOnBuild = typeof doctor.failOnBuild === "boolean"
+            ? doctor.failOnBuild
+            : DEFAULT_DOCTOR_CONFIG.failOnBuild;
         return { disabledGuards, dbToolScopingDenylist, failOnBuild };
     }
-    catch {
-        return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };
+    catch (error) {
+        throw new Error(`Could not read Doctor configuration from ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 function runGuard(name, root, config, migrationManifests) {
     switch (name) {
         case "no-drizzle-push":
             return scanDrizzlePush({ root });
+        case "no-empty-migrations":
+            return scanEmptyMigrations({ root });
         case "no-unscoped-credentials":
             return scanUnscopedCredentials({ root });
         case "no-unscoped-queries":
@@ -157,6 +162,53 @@ export function runDoctorScan(options) {
         guardsRun: names,
     };
 }
+function workspaceDoctorRoots(root) {
+    const packagePath = path.join(root, "package.json");
+    const appsDir = path.join(root, "apps");
+    if (!fs.existsSync(packagePath) || !fs.existsSync(appsDir))
+        return null;
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+        if (typeof packageJson?.["agent-native"]?.workspaceCore !== "string") {
+            return null;
+        }
+    }
+    catch (error) {
+        throw new Error(`Could not read workspace metadata from ${packagePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const appRoots = fs
+        .readdirSync(appsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(appsDir, entry.name))
+        .filter((appRoot) => fs.existsSync(path.join(appRoot, "package.json")))
+        .sort();
+    const scanRoots = [...appRoots];
+    const sharedRoot = path.join(root, "packages", "shared");
+    if (fs.existsSync(path.join(sharedRoot, "package.json"))) {
+        scanRoots.push(sharedRoot);
+    }
+    return { appRoots, scanRoots };
+}
+function prefixWorkspaceFindings(findings, root, appRoot) {
+    const prefix = path.relative(root, appRoot).replaceAll("\\", "/");
+    return findings.map((finding) => ({
+        ...finding,
+        file: `${prefix}/${finding.file}`,
+    }));
+}
+function runWorkspaceDoctorScan(root, scanRoots, only) {
+    const reports = scanRoots.map((scanRoot) => ({
+        scanRoot,
+        report: runDoctorScan({ root: scanRoot, only }),
+    }));
+    const guardsRun = Array.from(new Set(reports.flatMap(({ report }) => report.guardsRun)));
+    return {
+        ok: reports.every(({ report }) => report.ok),
+        findings: reports.flatMap(({ scanRoot, report }) => prefixWorkspaceFindings(report.findings, root, scanRoot)),
+        warnings: reports.flatMap(({ scanRoot, report }) => prefixWorkspaceFindings(report.warnings, root, scanRoot)),
+        guardsRun,
+    };
+}
 /**
  * Hosted app volumes are ~4.84 GB total, so anything under this is close
  * enough to a stalled build or a failed write to be worth naming.
@@ -216,8 +268,8 @@ function formatDiskLine(disk) {
 }
 /** Pure escalation rule shared by the CLI (`--strict`) and the `build`
  * pre-step (`--strict` / `agent-native.json` `doctor.failOnBuild`). Doctor
- * findings never fail anything on their own — only `strict` or
- * `failOnBuild` turn findings into a hard failure. */
+ * findings fail builds by default; only an explicit `failOnBuild: false`
+ * opt-out can keep a build moving, while `strict` always fails. */
 export function shouldFailBuild(hasFindings, opts) {
     return hasFindings && Boolean(opts.strict || opts.failOnBuild);
 }
@@ -225,9 +277,12 @@ const defaultIo = {
     log: (message) => console.log(message),
     err: (message) => console.error(message),
 };
-function formatDoctorHuman(report, root, disk) {
+function formatDoctorHuman(report, root, disk, workspaceApps) {
     const lines = [];
     lines.push(`agent-native doctor: ${root}`);
+    if (workspaceApps) {
+        lines.push(`Workspace apps scanned: ${workspaceApps.join(", ") || "(none)"}`);
+    }
     lines.push(`Guards run: ${report.guardsRun.join(", ") || "(none)"}`);
     lines.push(formatDiskLine(disk));
     if (report.findings.length === 0) {
@@ -293,7 +348,7 @@ export function printDoctorHelp(io = defaultIo) {
         "  agent-native doctor                        Scan app source for security-critical guard violations",
         "  agent-native doctor --json                 Machine-readable report: { ok, findings, warnings, guardsRun, disk, strict }",
         "  agent-native doctor --only <guard,guard>   Run only the named guard(s)",
-        "  agent-native doctor --strict                Escalate findings to a hard failure when used by `agent-native build --strict`",
+        "  agent-native doctor --strict                Keep the build gate explicit when invoked by `agent-native build`",
         "  agent-native doctor --cwd <dir>             Run against a project root other than the current directory",
         "  agent-native doctor --disk                  Also measure what `agent-native clean` would reclaim (scans every build cache)",
         "  agent-native doctor --fix                   Not implemented in this version",
@@ -307,9 +362,10 @@ export function printDoctorHelp(io = defaultIo) {
         "`--disk` adds how much of it `agent-native clean` could give back. Disk",
         "is advisory — it never changes the exit code.",
         "",
-        "`agent-native build` runs doctor as a warn-only pre-step by default — it",
-        "never fails the build unless `agent-native build --strict` is passed or",
-        'agent-native.json sets { "doctor": { "failOnBuild": true } }.',
+        "`agent-native build` runs doctor before the build and fails on findings",
+        'by default. Set `agent-native.json` to `{ "doctor": {',
+        '\"failOnBuild\": false } }` only with a reviewed reason; `--strict`',
+        "always keeps the gate enabled.",
         "",
         "For dependency-pin health (framework overrides/patches, stale",
         "@agent-native/* pins), run `agent-native upgrade check` instead.",
@@ -348,7 +404,10 @@ export async function runDoctor(argv, io = defaultIo) {
             return 2;
         }
     }
-    const report = runDoctorScan({ root, only: opts.only });
+    const workspaceRoots = workspaceDoctorRoots(root);
+    const report = workspaceRoots === null
+        ? runDoctorScan({ root, only: opts.only })
+        : runWorkspaceDoctorScan(root, workspaceRoots.scanRoots, opts.only);
     const disk = checkDisk(root, { measureReclaimable: Boolean(opts.disk) });
     if (opts.json) {
         // The machine-readable report always goes to stdout (io.log), whether
@@ -356,10 +415,19 @@ export async function runDoctor(argv, io = defaultIo) {
         // report.json` in CI always captures the report. Only the usage/
         // execution error payloads above (bad --cwd, unknown --only) go to
         // stderr — those are diagnostics for exit code 2, not the report.
-        io.log(JSON.stringify({ ...report, disk, strict: Boolean(opts.strict) }, null, 2));
+        io.log(JSON.stringify({
+            ...report,
+            ...(workspaceRoots === null
+                ? {}
+                : {
+                    workspaceApps: workspaceRoots.appRoots.map((appRoot) => path.relative(root, appRoot).replaceAll("\\", "/")),
+                }),
+            disk,
+            strict: Boolean(opts.strict),
+        }, null, 2));
     }
     else {
-        io.log(formatDoctorHuman(report, root, disk));
+        io.log(formatDoctorHuman(report, root, disk, workspaceRoots?.appRoots.map((appRoot) => path.relative(root, appRoot).replaceAll("\\", "/"))));
         if (!report.ok) {
             io.err("");
             io.err("agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.");
@@ -369,19 +437,19 @@ export async function runDoctor(argv, io = defaultIo) {
 }
 /**
  * `agent-native build`'s doctor pre-step. Always runs every enabled guard
- * and always prints findings (as warnings) to `io.err` — never silent.
- * Never causes the build to fail unless `strict` was passed or
- * `agent-native.json` sets `doctor.failOnBuild: true` (see report 005,
- * "Where it runs" — the v1 doctor has zero field mileage against arbitrary
- * app layouts, so shipping fail-by-default would risk breaking a first
- * deploy on a false positive).
+ * and always prints findings to `io.err` — never silent. Findings fail the
+ * build by default; only an explicit `doctor.failOnBuild: false` opt-out can
+ * keep a build moving, while `--strict` overrides that opt-out.
  */
 export async function runDoctorBuildHook(options, io = defaultIo) {
     const root = path.resolve(options.cwd);
     const config = readDoctorConfig(root);
-    const report = runDoctorScan({ root });
+    const workspaceRoots = workspaceDoctorRoots(root);
+    const report = workspaceRoots === null
+        ? runDoctorScan({ root })
+        : runWorkspaceDoctorScan(root, workspaceRoots.scanRoots);
     if (report.findings.length > 0) {
-        io.err(`\n[doctor] ${report.findings.length} finding(s) from \`agent-native doctor\` — run it directly for details. This does not fail the build unless --strict was passed or agent-native.json's doctor.failOnBuild is true.`);
+        io.err(`\n[doctor] ${report.findings.length} finding(s) from \`agent-native doctor\` — fix them before the build can continue.`);
         for (const f of report.findings) {
             io.err(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);
         }
@@ -397,7 +465,7 @@ export async function runDoctorBuildHook(options, io = defaultIo) {
         failOnBuild: config.failOnBuild,
     });
     if (fail) {
-        io.err(`\n[doctor] Failing build: ${options.strict ? "--strict was passed" : "agent-native.json's doctor.failOnBuild is true"}.`);
+        io.err(`\n[doctor] Failing build: ${options.strict ? "--strict was passed" : "the doctor.failOnBuild gate is enabled (default: true)"}.`);
     }
     return { ok: !fail, report };
 }

package/dist/cli/index.js

@@ -587,10 +587,9 @@ switch (command) {
         // continuation only runs on success.
         (async () => {
             // Doctor pre-step: scans app source for the security-critical guard
-            // invariants (see `agent-native doctor --help`). Warn-only by
-            // default — prints findings to stderr and always continues. Only
-            // fails the build when `agent-native build --strict` was passed or
-            // `agent-native.json` sets `{ "doctor": { "failOnBuild": true } }`.
+            // invariants (see `agent-native doctor --help`). Findings fail by
+            // default; only an explicit `doctor.failOnBuild: false` opt-out keeps
+            // a build moving, while `agent-native build --strict` always fails.
             try {
                 const { runDoctorBuildHook } = await import("./doctor.js");
                 const hook = await runDoctorBuildHook({
@@ -603,7 +602,8 @@ switch (command) {
                 }
             }
             catch (err) {
-                console.warn(`[doctor] pre-build scan failed to run (continuing): ${err instanceof Error ? err.message : String(err)}`);
+                console.error(`[doctor] pre-build scan failed, so the build is blocked: ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
             }
             if (isReactRouterFramework()) {
                 clearAgentNativeNitroPresetMarker();
@@ -1096,6 +1096,7 @@ Usage:
                                 Call another agent-native app over A2A
   agent-native script <name>    Run an action (deprecated alias for 'action')
   agent-native typecheck        Run TypeScript type checking
+  agent-native doctor           Scan app/workspace source for guard violations
   agent-native create [name]    Scaffold a new agent-native workspace with a
                                 multi-select template picker. Use --standalone
                                 for a single-app scaffold, or choose Community

package/dist/client/AgentAskPopover.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 export interface AgentAskPopoverProps {
     prompt: string;
     title?: string;
@@ -5,7 +6,8 @@ export interface AgentAskPopoverProps {
     placeholder?: string;
     context?: string;
     className?: string;
+    icon?: ReactNode;
 }
 /** A low-emphasis entry point for asking the agent without losing the current surface. */
-export declare function AgentAskPopover({ prompt, title, label, placeholder, context, className, }: AgentAskPopoverProps): import("react").JSX.Element;
+export declare function AgentAskPopover({ prompt, title, label, placeholder, context, className, icon, }: AgentAskPopoverProps): import("react").JSX.Element;
 //# sourceMappingURL=AgentAskPopover.d.ts.map

package/dist/client/AgentAskPopover.js

@@ -6,7 +6,7 @@ import { Popover, PopoverContent, PopoverTrigger, } from "./components/ui/popove
 import { PromptComposer } from "./composer/index.js";
 import { useT } from "./i18n.js";
 /** A low-emphasis entry point for asking the agent without losing the current surface. */
-export function AgentAskPopover({ prompt, title, label, placeholder, context, className, }) {
+export function AgentAskPopover({ prompt, title, label, placeholder, context, className, icon, }) {
     const t = useT();
     const [open, setOpen] = useState(false);
     const handleSubmit = useCallback((text) => {
@@ -21,7 +21,7 @@ export function AgentAskPopover({ prompt, title, label, placeholder, context, cl
         });
         setOpen(false);
     }, [context]);
-    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx(Button, { type: "button", variant: "outline", size: "sm", className: className ?? "cursor-pointer", children: label ?? t("agentPanel.askAgent", { defaultValue: "Ask the agent" }) }) }), _jsxs(PopoverContent, { align: "end", sideOffset: 8, collisionPadding: 12, className: "z-[260] w-[calc(100vw-32px)] max-w-[420px] p-3", children: [_jsx("p", { className: "px-1 pb-2 text-sm font-semibold text-foreground", children: title ??
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", className: className ?? "cursor-pointer", children: [icon, label ?? t("agentPanel.askAgent", { defaultValue: "Ask the agent" })] }) }), _jsxs(PopoverContent, { align: "end", sideOffset: 8, collisionPadding: 12, className: "z-[260] w-[calc(100vw-32px)] max-w-[420px] p-3", children: [_jsx("p", { className: "px-1 pb-2 text-sm font-semibold text-foreground", children: title ??
                             t("agentPanel.askAgentTitle", { defaultValue: "Ask the agent" }) }), _jsx(PromptComposer, { autoFocus: true, attachmentsEnabled: false, initialText: prompt, initialTextKey: prompt, layoutVariant: "compact", placeholder: placeholder ??
                             t("agentPanel.askAgentPlaceholder", {
                                 defaultValue: "Tell the agent what you want to do…",

package/dist/client/AgentPanel.js

@@ -54,7 +54,6 @@ import { useT } from "./i18n.js";
 import { isFirstRunOnboardingEnabled } from "./onboarding/first-run-enabled.js";
 import { useOnboardingPreviewMode } from "./onboarding/use-preview-mode.js";
 import { recoverFromStaleChunkError } from "./route-chunk-recovery.js";
-import { AgentNativeRouteWarmup } from "./route-warmup.js";
 import { withBuilderConnectTrackingParams } from "./settings/useBuilderStatus.js";
 import { useScreenRefreshKey } from "./use-db-sync.js";
 import { useDevMode } from "./use-dev-mode.js";
@@ -396,6 +395,7 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
     const onboardingPreviewMode = useOnboardingPreviewMode();
     const showFirstRunOnboarding = SHOW_FIRST_RUN_ONBOARDING || onboardingPreviewMode;
     const insideAgentSidebar = React.useContext(AgentSidebarOnboardingContext);
+    const isFirstRunOnboardingSurface = showFirstRunOnboarding && !insideAgentSidebar;
     const feedbackEnabled = resolveFeedbackUrl(undefined, mounted ? undefined : null) !== null;
     const keyPrefix = storageKey ? `:${storageKey}` : "";
     const execModeKey = `${EXEC_MODE_KEY}${keyPrefix}`;
@@ -858,7 +858,13 @@ function AgentPanelInner({ defaultMode = "chat", className, style, apiUrl, empty
         activateOnKeyDown,
         closeCliTab,
     ]);
-    return (_jsxs("div", { className: cn("agent-panel-root flex flex-1 flex-col min-h-0 h-full text-[13px] leading-[1.2] antialiased", className), style: { ...AGENT_PANEL_ROOT_STYLE, ...style }, "data-agent-fullscreen": isFullscreen ? "true" : undefined, children: [_jsx("style", { dangerouslySetInnerHTML: {
+    return (_jsxs("div", { className: cn("agent-panel-root flex flex-1 flex-col min-h-0 h-full text-[13px] leading-[1.2] antialiased", className), style: {
+            ...AGENT_PANEL_ROOT_STYLE,
+            ...style,
+            // The chat view-transition container otherwise traps fixed onboarding
+            // chrome below the app's own header instead of the viewport edge.
+            ...(isFirstRunOnboardingSurface ? { contain: "none" } : {}),
+        }, "data-agent-fullscreen": isFullscreen ? "true" : undefined, children: [_jsx("style", { dangerouslySetInnerHTML: {
                     __html: "@media (hover:hover) and (pointer:fine){" +
                         ".agent-sidebar-chat-header[data-agent-sidebar-chat-header]{opacity:0;pointer-events:none;transition:opacity 150ms ease-out;}" +
                         ".agent-panel-root:hover .agent-sidebar-chat-header[data-agent-sidebar-chat-header],.agent-panel-root:focus-within .agent-sidebar-chat-header[data-agent-sidebar-chat-header],.agent-sidebar-chat-header[data-agent-sidebar-chat-header][data-agent-sidebar-chat-header-active]{opacity:1;pointer-events:auto;}" +
@@ -1741,7 +1747,7 @@ export function AgentSidebar({ children, emptyStateText = "How can I help you?",
                         : 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), isFullscreen: effectiveFullscreen, onToggleFullscreen: isMobile ? undefined : (onFullscreenRequest ?? toggleFullscreen), 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;
-    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: [_jsx(AgentNativeRouteWarmup, {}), isMobile &&
+    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 &&
                             (mobileAnimationEnabled ? shouldRenderPanel : open) && (_jsx("div", { className: cn("agent-sidebar-backdrop fixed inset-0 bg-foreground/40", mobileAnimationEnabled && !panelOpen && "pointer-events-none"), "data-agent-sidebar-animation": mobileAnimationEnabled ? "mobile" : undefined, "data-agent-sidebar-state": panelOpen ? "open" : "closed", style: { zIndex: SIDEBAR_OVERLAY_Z_INDEX - 1 }, onClick: () => setOpenPersisted(false) })), shouldMountPanel ? _jsx(URLSync, { browserTabId: browserTabId }) : null, isLeft && !presentationMode ? sidebar : null, _jsx("div", { className: "agent-sidebar-main-surface flex flex-1 flex-col overflow-auto min-w-0", "data-agent-sidebar-main-position": position, "data-agent-sidebar-main-state": !isMobile &&
                                 !effectiveFullscreen &&