@agent-native/core 0.137.7 → 0.138.0

package/dist/vite/client.js

@@ -2,10 +2,11 @@ import { EventEmitter } from "events";
 import fs from "fs";
 import { createRequire, syncBuiltinESMExports } from "module";
 import path from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import { renderDesignSystemThemeCss, } from "@agent-native/toolkit/design-system/theme";
 import { mergePendingChangelog, parsePendingEntry, } from "../changelog/parse.js";
 import { getViteDevRecoveryScript } from "../client/vite-dev-recovery-script.js";
+import { mergeAgentNativeConfigs, normalizeAgentNativeConfig, resolveAgentNativeConfig, } from "../config.js";
 import { writeAgentNativeNitroPresetMarker } from "../deploy/nitro-preset.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { verifyEmbedSessionToken } from "../server/embed-session.js";
@@ -820,8 +821,8 @@ function getReactRouterAliases(cwd) {
 function getAssistantUiAliases(cwd) {
     try {
         const appRequire = createRequire(path.join(cwd, "package.json"));
-        const coreViteEntry = appRequire.resolve("@agent-native/core/vite");
-        const coreRequire = createRequire(coreViteEntry);
+        const assistantUiEntry = appRequire.resolve("@assistant-ui/react");
+        const assistantUiRequire = createRequire(assistantUiEntry);
         return [
             // A linked framework checkout can otherwise resolve the assistant-ui
             // imports in core's source graph from the checkout's React 19.2.7 peer
@@ -830,27 +831,27 @@ function getAssistantUiAliases(cwd) {
             // to the consuming app's installed peer graph explicitly.
             {
                 find: /^@assistant-ui\/react$/,
-                replacement: coreRequire.resolve("@assistant-ui/react"),
+                replacement: assistantUiRequire.resolve("@assistant-ui/react"),
             },
             {
                 find: /^@assistant-ui\/core$/,
-                replacement: coreRequire.resolve("@assistant-ui/core"),
+                replacement: assistantUiRequire.resolve("@assistant-ui/core"),
             },
             {
                 find: /^@assistant-ui\/store$/,
-                replacement: coreRequire.resolve("@assistant-ui/store"),
+                replacement: assistantUiRequire.resolve("@assistant-ui/store"),
             },
             {
                 find: /^@assistant-ui\/tap$/,
-                replacement: coreRequire.resolve("@assistant-ui/tap"),
+                replacement: assistantUiRequire.resolve("@assistant-ui/tap"),
             },
             {
                 find: /^assistant-stream$/,
-                replacement: coreRequire.resolve("assistant-stream"),
+                replacement: assistantUiRequire.resolve("assistant-stream"),
             },
             {
                 find: /^assistant-stream\/utils$/,
-                replacement: coreRequire.resolve("assistant-stream/utils"),
+                replacement: assistantUiRequire.resolve("assistant-stream/utils"),
             },
         ];
     }
@@ -2608,8 +2609,54 @@ function resolveAgentNativeTemplate(cwd) {
         ?.trim()
         .toLowerCase() ?? "");
 }
-function createAgentNativeConfig(options = {}, command, userConfig = {}) {
+function createAgentNativeConfigContext(command, mode) {
+    const resolvedCommand = command === "build" ? "build" : "serve";
+    return {
+        command: resolvedCommand,
+        mode,
+        isDev: resolvedCommand === "serve",
+        isBuild: resolvedCommand === "build",
+    };
+}
+function readAgentNativeJsonConfig(cwd) {
+    const configPath = path.join(cwd, "agent-native.json");
+    if (!fs.existsSync(configPath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Could not read ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return normalizeAgentNativeConfig(parsed, configPath);
+}
+async function loadAgentNativeConfigFile(cwd) {
+    const candidates = ["agent-native.config.ts", "agent-native.config.mts"];
+    const configPath = candidates
+        .map((filename) => path.join(cwd, filename))
+        .find((candidate) => fs.existsSync(candidate));
+    if (!configPath)
+        return undefined;
+    try {
+        const module = (await import(pathToFileURL(configPath).href));
+        const config = module.default ?? module.agentNativeConfig;
+        if (typeof config !== "object" && typeof config !== "function") {
+            throw new Error("the default export must be an object or function");
+        }
+        return config;
+    }
+    catch (error) {
+        throw new Error(`Could not load ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function createAgentNativeConfig(options = {}, command, userConfig = {}, mode = process.env.NODE_ENV === "production" ? "production" : "development", projectConfig) {
     const cwd = process.cwd();
+    const configContext = createAgentNativeConfigContext(command, mode);
+    const projectConfigInput = projectConfig ?? options.agentNativeConfig;
+    const appConfig = resolveAgentNativeConfig(mergeAgentNativeConfigs(readAgentNativeJsonConfig(cwd), projectConfigInput
+        ? resolveAgentNativeConfig(projectConfigInput, configContext)
+        : {}), configContext);
     const buildId = process.env.DEPLOY_ID?.trim() ||
         process.env.COMMIT_REF?.trim() ||
         process.env.VERCEL_GIT_COMMIT_SHA?.trim() ||
@@ -2688,6 +2735,7 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}) {
             ...(options.define ?? {}),
             __AGENT_NATIVE_BUILD_ID__: JSON.stringify(buildId),
             __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__: JSON.stringify(options.clientCompatibilityVersion?.trim() || ""),
+            __AGENT_NATIVE_APP_CONFIG__: JSON.stringify(appConfig),
             __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
             __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
@@ -2917,8 +2965,11 @@ export function agentNative(options = {}) {
         {
             name: "agent-native-config",
             enforce: "pre",
-            config(config, env) {
-                return createAgentNativeConfig(options, env.command, config);
+            async config(config, env) {
+                const projectConfig = options.agentNativeConfig === undefined
+                    ? await loadAgentNativeConfigFile(process.cwd())
+                    : undefined;
+                return createAgentNativeConfig(options, env.command, config, env.mode, projectConfig);
             },
         },
         ...createAgentNativePlugins(options, {

package/dist/vite/index.d.ts

@@ -1,4 +1,5 @@
 export { agentNative, defineConfig, type AgentNativeVitePluginOptions, type ClientConfigOptions, type NitroOptions, } from "./client.js";
+export { defineAgentNativeConfig, type AgentNativeConfig, type AgentNativeConfigContext, type AgentNativeConfigFactory, type AgentNativeConfigInput, type AgentNativeFirstRunOnboardingMode, type AgentNativeFirstRunOnboardingSetting, } from "../config.js";
 export type { AgentNativeRouteWarmupConfigInput, AgentNativeRouteWarmupResolvedConfig, AgentNativeRouteWarmupStrategy, } from "../shared/route-warmup-config.js";
 export { actionTypesPlugin, generateActionRegistryForProject, } from "./action-types-plugin.js";
 export { agentsBundlePlugin } from "./agents-bundle-plugin.js";

package/dist/vite/index.js

@@ -1,4 +1,5 @@
 export { agentNative, defineConfig, } from "./client.js";
+export { defineAgentNativeConfig, } from "../config.js";
 export { actionTypesPlugin, generateActionRegistryForProject, } from "./action-types-plugin.js";
 export { agentsBundlePlugin } from "./agents-bundle-plugin.js";
 export { createAgentWebVitePlugin, } from "./agent-web-plugin.js";

package/docs/AGENTS.md

@@ -21,6 +21,9 @@ version installed in the app.
 From a generated app root:
 
 ```bash
+pnpm action framework-search --pattern "defineAction"
+pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
+pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
 pnpm action docs-search --list
 pnpm action docs-search --query "actions"
 pnpm action docs-search --slug actions
@@ -30,8 +33,10 @@ pnpm action source-search --path templates/plan/AGENTS.md
 pnpm action source-search --path templates/chat/actions/hello.ts
 ```
 
-The built-in app agent also has read-only `docs-search` and `source-search`
-tools with the same options.
+The built-in app agent also has a read-only `framework-search` tool for one
+bounded search across docs and readable Core, Toolkit, and first-party
+template source. Use `docs-search` and `source-search` for focused reads after
+it identifies the relevant page or file.
 
 If the action runner is unavailable, search the package files directly:
 

package/docs/SKILL.md

@@ -14,14 +14,16 @@ examples or template patterns matter, inspect the packaged source corpus too.
 ## How
 
 1. Start from the generated app root.
-2. Search with `pnpm action docs-search --query "<feature>"`.
-3. Read a specific page with `pnpm action docs-search --slug <slug>`.
-4. Search source examples with `pnpm action source-search --query "<pattern>"`
+2. Start cross-corpus discovery with `pnpm action framework-search --pattern "<feature>"`.
+3. Use `--scope docs` or `--scope source` and `--mode glob`, `--mode sql-like`,
+   or `--mode regex` when the question needs a narrower pattern.
+4. Read a specific page with `pnpm action docs-search --slug <slug>`.
+5. Search source examples with `pnpm action source-search --query "<pattern>"`
    or read a file with `pnpm action source-search --path <path>`.
-5. If the action runner is unavailable, search
+6. If the action runner is unavailable, search
    `node_modules/@agent-native/core/docs` directly with `rg`.
    Search `node_modules/@agent-native/core/corpus` for source examples.
-6. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
+7. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
    `.agents/skills/<name>/SKILL.md`.
 
 ## Useful Slugs

package/docs/content/agent-native-config.mdx

@@ -0,0 +1,165 @@
+---
+title: "Agent-Native app configuration"
+description: "Configure public app defaults with agent-native.json or a typed agent-native.config.ts file."
+search: "agent-native.json agent-native.config.ts onboarding first-run Builder BYOK integrations configuration"
+---
+
+# Agent-Native app configuration
+
+Use app configuration for committed, non-secret defaults that should travel
+with the app. Use environment variables for deployment values, credentials,
+and local machine controls. The framework reads `agent-native.json` from the
+app root when the `agentNative()` Vite preset runs.
+
+The file is an additive app manifest. Existing feature-owned sections such as
+`doctor`, `apps`, and local-file declarations can stay in the same file; the
+onboarding reader only consumes the `version` and `onboarding` fields described
+here.
+
+## The onboarding contract
+
+The shared first-run surface has three supported modes:
+
+| Mode                       | Local or hosted result                                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `off`                      | No shared first-run surface. This is the default for ordinary apps.                                                                                          |
+| `connect`                  | Show Connect Builder or Add your own keys, then go straight to the app. The generic integrations catalog is omitted.                                         |
+| `connect-and-integrations` | Show Connect Builder or Add your own keys, followed by the generic integrations catalog. Use this for a hosted app that should expose its integration setup. |
+
+A turn-into-app result normally commits a mode map so `pnpm dev` is useful
+immediately while a production build has the hosted setup path:
+
+```json filename="agent-native.json"
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "connect",
+      "production": "connect-and-integrations"
+    }
+  }
+}
+```
+
+An ordinary app can omit `onboarding` or make the default explicit:
+
+```json filename="agent-native.json"
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": "off"
+  }
+}
+```
+
+First-party templates use `off` while running locally and
+`connect-and-integrations` for a production build. The
+`/turn-into-app` skill deliberately changes only the local value to `connect`
+so a newly generated workflow is immediately testable without putting the
+hosted integration catalog in front of the user.
+
+The environment map uses the exact Vite `mode` first, then falls back to
+`development` for `vite dev`, `production` for `vite build`, and finally
+`default` or `off`. This lets a project add a named mode such as `staging`
+without making the app depend on a new environment variable.
+
+## Typed dynamic configuration
+
+When a static JSON map is not enough, add `agent-native.config.ts`. It returns
+the same serializable shape and can use the Vite command and mode:
+
+```ts filename="agent-native.config.ts"
+import { defineAgentNativeConfig } from "@agent-native/core/config";
+
+export default defineAgentNativeConfig(({ command, mode }) => ({
+  version: 1,
+  onboarding: {
+    firstRun:
+      command === "serve" || mode === "preview"
+        ? "connect"
+        : "connect-and-integrations",
+  },
+}));
+```
+
+The preset loads `agent-native.config.ts` or `agent-native.config.mts`
+automatically on the supported Node runtime. The TypeScript file takes
+precedence over the JSON app defaults. An explicit `agentNative({
+agentNativeConfig })` option takes precedence over both when an app needs to
+compose configuration in its Vite config.
+
+The resolved config is serialized into the browser bundle. Keep it public:
+never put API keys, tokens, database URLs, auth secrets, `AUTH_DISABLED`, or
+other credentials in either config file.
+
+## Precedence and compatibility
+
+For a Vite app, the effective value is resolved in this order:
+
+1. An explicit `agentNativeConfig` passed to `agentNative()` or `defineConfig()`.
+2. The optional typed `agent-native.config.ts` or `.mts` file.
+3. `agent-native.json`.
+4. Framework defaults, which are `off` for first-run onboarding.
+5. The legacy `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING` flags can still
+   override the resolved public config for older apps, but new apps should not
+   add them. They are public browser flags and remain documented only for
+   migration.
+
+The development Connect Builder card explains the deployment-level
+`ANTHROPIC_API_KEY` and `OPENAI_API_KEY` fallback and links to the
+[environment-variable reference](/docs/environment-variables). A key in the
+deployment environment is not a substitute for user- or organization-scoped
+credentials in a hosted multi-user app. See [Onboarding & API Keys](/docs/onboarding)
+and [Security](/docs/security) for the credential boundary.
+
+## What belongs in config versus `.env`
+
+Good config candidates are public defaults that describe the product's shape:
+
+- first-run onboarding mode and other setup presentation defaults;
+- the app's default MCP catalog visibility or preset filters, once expressed
+  through the shared config contract;
+- route warmup, public design tokens, and other build-time UX choices already
+  passed to the `agentNative()` Vite preset;
+- non-secret app identity and default navigation metadata, if the framework
+  later gives those values a shared runtime consumer.
+
+Keep these in environment variables or the secret store:
+
+- API keys, OAuth secrets, signing keys, database URLs, and provider tokens;
+- `APP_URL`, `APP_BASE_PATH`, deployment preset, port, and host-specific
+  values that change between deploy targets;
+- `AUTH_DISABLED`, test switches, CI controls, and local machine paths;
+- runtime flags whose safe value depends on the hosting environment rather than
+  the app's product contract.
+
+The complete inventory is [Environment Variables](/docs/environment-variables).
+That reference is intentionally broader than the config surface and is the
+source to consult before adding a new environment variable.
+
+## Environment audit and next candidates
+
+The current config surface intentionally starts with onboarding, where a
+committed app default is more useful than a deployment flag. The next good
+public candidates are:
+
+| Candidate                                 | Why it belongs in app config                                               | Status                                                                 |
+| ----------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| MCP catalog visibility and preset filters | Describes which setup choices the app offers, not a secret or host policy. | A good next addition; currently keep using the `agentNative()` option. |
+| Route warmup strategy                     | A product-level loading preference that can be reviewed with the app.      | A good next addition; currently keep using the `agentNative()` option. |
+| Default navigation or app identity        | Makes generated apps open on the right domain route and name.              | Add only after a shared runtime consumer exists.                       |
+| Design-system theme                       | Can vary intentionally per app, but is a larger structured object.         | Keep in `vite.config.ts` or app code until the schema is stable.       |
+
+Do not move `DATABASE_URL`, `APP_URL`, `PORT`, `NITRO_PRESET`, auth switches,
+provider keys, OAuth secrets, signing keys, telemetry endpoints, or security
+flags into this file. They vary by deploy target, affect trust boundaries, or
+must remain outside the browser bundle. This split keeps config useful for
+scaffolders without turning it into a second environment-variable system.
+
+## Why there are two formats
+
+`agent-native.json` is portable, inspectable, and easy for scaffolders and
+other tools to write. `agent-native.config.ts` follows the typed-config pattern
+used by frameworks such as Next.js while keeping the browser contract
+serializable. Prefer JSON for a fixed app default and TypeScript when the
+default genuinely depends on the Vite command or mode.

package/docs/content/agent-native-toolkit.mdx

@@ -97,7 +97,7 @@ directly without adopting Toolkit or a template.
 | [Collaboration](/docs/toolkit-collaboration)             | Realtime editing, presence, live cursors, recent-edit highlights, collaborative undo.                                            |
 | [Settings](/docs/toolkit-settings)                       | Standard settings pages and tabs so app settings and agent/provider settings live in one predictable place.                      |
 | [Org & Team](/docs/toolkit-org-team)                     | Team pages, org switching, invites, org domains, roles, and app switching.                                                       |
-| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect.                                       |
+| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect (free tier available).                 |
 | [Command & Navigation](/docs/toolkit-command-navigation) | Command menu, deep links, standard app routes, sidebar and shell patterns.                                                       |
 | [Resources](/docs/toolkit-resources)                     | Resource trees, editors, file picker/search, attachments, and local file mode.                                                   |
 | [Agent UX](/docs/toolkit-agent-ux)                       | Composer, model picker, context chips, approvals, run recovery, and the runs tray.                                               |

package/docs/content/deployment.mdx

@@ -517,6 +517,11 @@ Three things to keep in mind:
 
 ## Environment Variables {#environment-variables}
 
+For the repository-wide reference, including template, provider, local, and CI
+variables, see [Environment Variables](/docs/environment-variables). The tables
+below remain the authoritative deployment guide for production values and
+hosting behavior.
+
 ### Build / Runtime {#env-runtime}
 
 | Variable                                    | Description                                                                                                                                                                                                                                                                                                                                                             |
@@ -640,11 +645,11 @@ In a standard production deployment with [production code execution](#production
 
 ### Builder.io: Visual Editing in Production {#builderio}
 
-[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io and prompt for UI changes directly — no redeploy needed.
+[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io (free tier available) and prompt for UI changes directly — no redeploy needed.
 
 **How it works:**
 
-1. Connect your agent-native repo to Builder.io
+1. Connect your agent-native repo to Builder.io (free tier available)
 2. Builder.io provides a cloud frame with the agent, visual editing, and real-time collaboration
 3. Prompt the agent to make UI changes — it edits your components, routes, and styles live
 4. Changes are committed back to your repo

package/docs/content/doctor.mdx

@@ -1,18 +1,20 @@
 ---
 title: "Doctor (Code Checks)"
-description: "agent-native doctor scans a generated app's source for the framework's security and architecture invariants — the same code-safety guards this monorepo enforces on itself, ported to run against a single app root."
+description: "agent-native doctor scans generated app and workspace source for the framework's security and architecture invariants — the portable code-safety guards shared outside the monorepo CI suite."
 ---
 
 # Doctor (Code Checks)
 
-Generated apps contain source code that can be changed through the repository's
+Generated apps and workspaces contain source code that can be changed through the repository's
 development workflow, including by an agent frame intentionally granted
 workspace and write tooling. `agent-native doctor` is the automated check for that: it
 scans app source for the framework's security-critical code-safety invariants —
 the same class of check that lives in this framework's own CI as
-`scripts/guard-*.mjs` — ported to run against a single generated app instead of
-the framework's multi-template monorepo layout. It's read-only: doctor never
-edits your code, it only reports.
+`scripts/guard-*.mjs` — ported to run against generated projects instead of
+the framework's multi-template monorepo layout. A workspace-root run scans each
+`apps/<name>` project and the workspace's `packages/shared` package when present,
+prefixing findings with the project path. It's read-only: doctor never edits
+your code, it only reports.
 
 ## Quick start {#quick-start}
 
@@ -20,12 +22,17 @@ edits your code, it only reports.
 agent-native doctor
 ```
 
-Every scaffolded app also gets a `pnpm doctor` script that runs the same command:
+Every scaffolded app and workspace gets the collision-free
+`pnpm agent-native:doctor` command. When a template does not already define its
+own `doctor` script, the CLI also adds the shorter `pnpm doctor` alias:
 
 ```bash
 pnpm doctor
 ```
 
+The full framework-repository `pnpm guards` suite remains a monorepo check;
+generated projects use this version-matched portable Doctor surface instead.
+
 A clean run:
 
 ```
@@ -83,7 +90,7 @@ installed.
 agent-native doctor                        Scan app source for security-critical guard violations
 agent-native doctor --json                 Machine-readable report: { ok, findings, guardsRun, 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 --fix                  Not implemented in this version
 agent-native doctor --help                 Show this help
@@ -97,16 +104,16 @@ Exit codes: **`0`** clean, **`1`** findings present, **`2`** usage or execution
 
 ## The build hook {#build-hook}
 
-`agent-native build` always runs doctor as a pre-step before the real build. It's **warn-only by default**: findings print to stderr prefixed `[doctor]`, and the build continues. It only turns findings into a hard failure — `process.exit(1)` before the build runs — when:
+`agent-native build` always runs doctor as a pre-step before the real build. It is a **hard gate by default**: findings print to stderr prefixed `[doctor]`, and the build exits before publishing. A project using `agent-native build` can explicitly opt out with `failOnBuild: false`, but `--strict` always keeps the gate enabled. Community templates that use another build command receive a strict `prebuild` hook instead:
 
-- `agent-native build --strict` was passed, or
-- `agent-native.json` sets `{ "doctor": { "failOnBuild": true } }`.
+- `agent-native.json` sets `{ "doctor": { "failOnBuild": false } }` only when that exception has been reviewed.
 
-If the doctor pre-step itself throws — an unreadable file, a bug in a guard — the build step catches it, logs a warning, and continues. A doctor bug never blocks a deploy on its own.
+If the doctor pre-step itself throws — for example, because a source file is unreadable or a guard crashes — the build is blocked. A partial security scan must never look like a clean result.
 
 ## Per-app configuration {#config}
 
-`agent-native.json`'s optional `"doctor"` key. Every field is optional with an empty/false default, so a fresh app runs every v1 guard with zero config:
+`agent-native.json`'s optional `"doctor"` key. A fresh app runs every v1 guard
+with zero config and fails builds on findings by default:
 
 ```json
 {
@@ -124,7 +131,7 @@ If the doctor pre-step itself throws — an unreadable file, a bug in a guard
 | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `disabledGuards`        | `string[]`              | Guard names (from the table above) to skip — excluded from the default run and from the build hook. An explicit `--only` list overrides this and runs even a disabled guard.                                                               |
 | `dbToolScopingDenylist` | `Record<table, reason>` | Bare table name (the SQL name, not template-prefixed) → reviewer-readable reason. Used only by `db-tool-scoping`. A denylist entry with no matching table in `server/db/schema.ts` itself becomes a finding — "stale … entry — remove it." |
-| `failOnBuild`           | `boolean`               | See [The build hook](#build-hook). Default `false`.                                                                                                                                                                                        |
+| `failOnBuild`           | `boolean`               | See [The build hook](#build-hook). Default `true`; set `false` only for a reviewed exception.                                                                                                                                              |
 
 ## Opt-out markers {#opt-out}
 
@@ -174,6 +181,7 @@ The actual `--json` payload also carries a `strict` field reflecting whether `--
     "explicit-collab-access",
     "migration-manifest"
   ],
+  "workspaceApps": ["apps/mail", "apps/tasks"],
   "strict": false
 }
 ```