@agent-native/core 0.137.8 → 0.139.0

package/corpus/templates/slides/changelog/2026-08-05-decks-are-now-sorted-by-most-recently-updated.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-05
+---
+
+Decks are now sorted by most recently updated

package/corpus/templates/slides/server/handlers/assets.ts

@@ -144,7 +144,7 @@ export async function uploadImageAsset(args: {
 
   if (!result) {
     const err: Error & { statusCode?: number } = new Error(
-      "No file upload provider is configured. Connect Builder.io from the agent composer model menu, or register a custom provider via registerFileUploadProvider().",
+      "No file upload provider is configured. Connect Builder.io (free tier available) from the agent composer model menu, or register a custom provider via registerFileUploadProvider().",
     );
     err.statusCode = 503;
     throw err;

package/corpus/templates/slides/server/handlers/uploads.ts

@@ -155,7 +155,7 @@ export async function saveUploadedReferenceFile(args: {
     if (!reference) {
       throw Object.assign(
         new Error(
-          "Private file storage is not configured. Connect Builder.io or another file provider before uploading reference files in a hosted Slides deployment.",
+          "Private file storage is not configured. Connect Builder.io (free tier available) or another file provider before uploading reference files in a hosted Slides deployment.",
         ),
         { statusCode: 503 },
       );

package/corpus/templates/slides/server/lib/comment-notifications.ts

@@ -21,6 +21,7 @@ import { and, eq } from "drizzle-orm";
 import { getDeckUrl } from "../../actions/_app-url.js";
 import { SLIDES_USER_PREFS_KEY } from "../../shared/slides-user-prefs.js";
 import { getDb, schema } from "../db/index.js";
+import { SLIDES_DECK_COMMENT_EMAIL_ID } from "./emails.js";
 
 /**
  * `deck-missing` stays distinct from `no-recipients`: one means the deck could
@@ -99,6 +100,41 @@ async function threadParticipants(
   return rows.map((row) => row.authorEmail);
 }
 
+export function renderDeckCommentEmail({
+  actor,
+  title,
+  url,
+  content,
+  isReply,
+}: {
+  actor: string;
+  title: string;
+  url: string;
+  content: string;
+  isReply: boolean;
+}) {
+  return {
+    subject: isReply
+      ? `${actor} replied to a comment on "${title}"`
+      : `${actor} commented on "${title}"`,
+    ...renderEmail({
+      preheader: isReply
+        ? `${actor} replied to a comment on ${title}.`
+        : `${actor} commented on ${title}.`,
+      heading: isReply ? "New reply on your deck" : "New comment",
+      paragraphs: [
+        isReply
+          ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(title)}.`
+          : `${emailStrong(actor)} commented on ${emailStrong(title)}.`,
+        `"${excerpt(content)}"`,
+      ],
+      cta: { label: "Open deck", url },
+      footer:
+        "You received this because you own or participated in this thread. Turn these off in Slides settings.",
+    }),
+  };
+}
+
 export async function notifyDeckComment(input: {
   deckId: string;
   slideId: string;
@@ -153,29 +189,16 @@ async function deliverDeckCommentEmails(input: {
     preferenceKey: SLIDES_USER_PREFS_KEY,
     logLabel: LOG_LABEL,
     send: async (to) => {
-      const { html, text } = renderEmail({
-        preheader: input.isReply
-          ? `${actor} replied to a comment on ${deck.title}.`
-          : `${actor} commented on ${deck.title}.`,
-        heading: input.isReply ? "New reply on your deck" : "New comment",
-        paragraphs: [
-          input.isReply
-            ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(deck.title)}.`
-            : `${emailStrong(actor)} commented on ${emailStrong(deck.title)}.`,
-          `"${excerpt(input.content)}"`,
-        ],
-        cta: { label: "Open deck", url },
-        footer:
-          "You received this because you own or participated in this thread. Turn these off in Slides settings.",
-      });
-
       await sendEmail({
+        ...renderDeckCommentEmail({
+          actor,
+          title: deck.title,
+          url,
+          content: input.content,
+          isReply: input.isReply,
+        }),
         to,
-        subject: input.isReply
-          ? `${actor} replied to a comment on "${deck.title}"`
-          : `${actor} commented on "${deck.title}"`,
-        html,
-        text,
+        templateId: SLIDES_DECK_COMMENT_EMAIL_ID,
       });
     },
   });

package/corpus/templates/slides/server/lib/emails.ts

@@ -0,0 +1,40 @@
+/**
+ * Catalog entries for the transactional emails Slides sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import { renderDeckCommentEmail } from "./comment-notifications.js";
+
+export const SLIDES_DECK_COMMENT_EMAIL_ID = "slides.deck-comment";
+
+let registered = false;
+
+export function registerSlidesEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: SLIDES_DECK_COMMENT_EMAIL_ID,
+    name: "Deck comment",
+    trigger:
+      "Someone posts a comment or a thread reply on a slide. Subject and copy differ slightly for a reply; both send under this id.",
+    recipientLabel: "Deck owner and authors",
+    recipient:
+      "The deck owner, plus every prior author in the thread when the new comment is a reply. The list is re-checked against the deck's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderDeckCommentEmail({
+        actor: "Sam Rivera",
+        title: "Series A narrative",
+        url: "https://example.com/decks/deck_sample?slide=3",
+        content: "Slide 3 needs the updated revenue chart before Thursday.",
+        isReply: false,
+      }),
+  });
+}

package/corpus/templates/slides/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerSlidesEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerSlidesEmails();
+}

package/corpus/templates/tasks/.agents/skills/agent-native-docs/SKILL.md

@@ -31,6 +31,26 @@ the framework monorepo checkout.
 
 From a generated app directory:
 
+```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
+```
+
+Use `framework-search` first when a question may cross the docs and source
+boundary. It searches the version-matched framework docs, runtime-visible
+skills, readable Core or Toolkit package source, and first-party template
+corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
+narrow it, then use the existing focused readers for the page or file you need.
+
+The same tool is available in the headless `pnpm agent` loop and every built-in
+app agent. Its default substring mode is safest for ordinary questions; use
+`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
+for precise structural matches. Results are bounded, so refine the pattern or
+path instead of treating a truncated result as exhaustive.
+
+From a generated app directory, the lower-level readers remain available:
+
 ```bash
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
@@ -41,9 +61,9 @@ pnpm action source-search --path templates/chat/actions/hello.ts
 pnpm action source-search --list
 ```
 
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
+The headless `pnpm agent` loop and built-in app agent also expose read-only
+`framework-search`, `docs-search`, and `source-search` tools. Use the unified
+tool for discovery, then the focused tools for full page or file reads.
 
 If the action runner is unavailable, search the package directly:
 

package/corpus/templates/tasks/.agents/skills/agent-native-toolkit/SKILL.md

@@ -65,6 +65,22 @@ Contextual agent UI is not a reason to expose every option at once. Start with
 the domain task's primary action, reveal review or configuration only when the
 current state needs it, and let the sidebar carry conversational depth.
 
+## Visual Direction And Workspace Variety
+
+Shared workspace behavior should be consistent without forcing every app into
+the same visual skin. Keep shell and component tokens semantic, then let each
+app declare a named direction in `DESIGN.md` before styling. A new app should
+choose its palette family and composition from the product context, compare
+nearby apps, and avoid inheriting their accent by default. Use the
+`frontend-design` visual-direction reference for mode, palette, type, density,
+shape, anti-references, and the `distill` / `typeset` / `colorize` / `layout` /
+`polish` / `audit` review vocabulary.
+
+Do not make warm beige plus terracotta the workspace fallback. Preserve a
+workspace-level brand when one exists; otherwise keep shared chrome neutral and
+allow app-owned accents to distinguish products while retaining accessible
+semantic states and the shared AgentSidebar contract.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/corpus/templates/tasks/.agents/skills/frontend-design/SKILL.md

@@ -34,6 +34,22 @@ Before coding, decide:
 
 Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
 
+## Visual Direction Contract
+
+Before styling a new app or workspace surface, define its product mode,
+audience, visual world, palette family, type treatment, composition, shape
+language, and anti-references in `DESIGN.md`. Read
+`references/visual-direction.md` for the direction families and review
+vocabulary. This is the Impeccable-inspired design contract for Agent-Native
+apps: understand the product, name the mode, deal a few coherent directions,
+commit to one, and audit the result instead of averaging back to a starter.
+
+Preserve an existing brand system and component library. When no brand exists,
+choose a deliberate direction based on the domain and compare sibling apps
+before selecting its accent family. Shared behavior and semantic token names
+should stay consistent; palette, density, composition, type contrast, and
+shape language should not be identical by default.
+
 ## Minimalism And Progressive Disclosure
 
 Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
@@ -81,13 +97,13 @@ passed this requirement yet.
   operational apps, make a clear sans-serif hierarchy the default; reserve a
   serif or editorial face for a deliberate content preview or brand moment,
   not the whole application shell.
-- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes, default warm beige/terracotta, and default purple/blue gradients unless the brand demands them. New apps should choose a product-fitting accent family rather than inherit the previous app's color.
 - **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
-**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option. Commit to one named direction, pair any reference with the reason it fits, and match implementation effort to the vision. If the brief is open, consider two or three coherent visual worlds, then commit to one instead of averaging them. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
 
 ## Agent-Native UI Rules
 
@@ -164,6 +180,9 @@ as an operator would use it repeatedly:
 - For review flows, stack the source/original first and the generated or safe
   result second by default. Use side-by-side comparison only when the content
   is short enough to scan without excessive horizontal reading.
+- Compare the result with sibling apps. Shared toolkit behavior should feel
+  consistent, but a repeated palette, hero composition, type pairing, and
+  radius language without a product reason is visual drift, not consistency.
 - Check the result at the target desktop width and a narrow width. If the first
   viewport feels like documentation instead of a tool, subtract again.
 
@@ -216,6 +235,8 @@ For substantial frontend work:
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,
    `portalContainer`, and z-index stacking checks.
+6. For a new app or a visual redesign, review `DESIGN.md` against the rendered
+   surface and run the anti-slop audit in `references/visual-direction.md`.
 
 ## Related Skills
 

package/corpus/templates/tasks/.agents/skills/frontend-design/references/visual-direction.md

@@ -0,0 +1,99 @@
+# Visual Direction Reference
+
+Use this reference when a new app or workspace needs a visual point of view and
+does not already have an established brand system. It adapts the useful parts
+of Impeccable's workflow: understand the product, name the surface mode, deal
+several coherent directions, commit to one, and audit the result for defaults
+that became the design by accident.
+
+## The direction contract
+
+Before writing UI, capture these decisions in the app's `DESIGN.md`:
+
+| Decision             | What to record                                                      |
+| -------------------- | ------------------------------------------------------------------- |
+| Product mode         | `operate`, `read`, `persuade`, or `experience`                      |
+| Audience and cadence | Who uses it, how often, and under what conditions                   |
+| Visual world         | A short name and the feeling it creates                             |
+| Palette family       | The semantic accent family and neutral undertone                    |
+| Type treatment       | Sans-first, editorial contrast, or display-led emphasis             |
+| Composition          | Dense console, focused workbench, document, canvas, or guided steps |
+| Shape language       | Quiet corners, crisp geometry, or soft utility surfaces             |
+| Anti-references      | Defaults this app must not drift toward                             |
+
+`DESIGN.md` is a portable design contract, not a license to bypass the app's
+tokens or component system. If the app already has a brand system, document it
+and preserve it. If it does not, choose a direction before styling.
+
+## Palette families
+
+Use one family as an accent and keep the rest of the system semantic and quiet.
+These are starting points, not a fixed theme library:
+
+| Family           | Good fit                                    | Typical character                 |
+| ---------------- | ------------------------------------------- | --------------------------------- |
+| Ink / graphite   | Admin, security, sensitive review           | Serious, low-noise, high contrast |
+| Cobalt / sky     | Planning, collaboration, scheduling         | Clear, trustworthy, alert         |
+| Pine / teal      | Automation, systems, finance, data          | Calm, capable, grounded           |
+| Indigo / violet  | Slides, creative tools, research            | Exploratory, focused, expressive  |
+| Plum / berry     | Publishing, knowledge, editorial work       | Distinctive, thoughtful, human    |
+| Coral / rose     | Communication, people, customer workflows   | Warm, direct, social              |
+| Ochre / citron   | Lightweight planning or energetic utilities | Optimistic, sparing, directional  |
+| Paper / charcoal | Long-form reading, exports, approvals       | Tactile, restrained, legible      |
+
+Do not make warm beige plus terracotta the universal fallback. Do not rotate
+through saturated colors mechanically. Choose the family that supports the
+workflow, then verify contrast, dark mode, focus states, destructive states,
+and the sidebar boundary.
+
+## Variation without chaos
+
+Vary at least two independent axes when sibling apps share a workspace:
+
+- accent family or neutral undertone;
+- information density and page composition;
+- type contrast and display treatment;
+- radius and border language;
+- navigation emphasis and use of whitespace.
+
+Keep shared behavior, semantic token names, accessibility, and AgentSidebar
+placement consistent. The goal is a family of products, not five unrelated
+themes and not five copies of the same starter.
+
+For a batch of apps, keep a small direction ledger in the workspace
+`DESIGN.md` or the handoff. Record each app's mode, direction, and palette
+family, then choose a new family or a clearly different composition for the
+next app unless an existing brand requires reuse. Never copy a sibling's
+`global.css` palette block or treat the last app's accent as the generator
+default.
+
+## Review vocabulary
+
+Make one named intervention at a time so the agent can reason about the
+change:
+
+- `distill` - remove copy, controls, cards, and chrome that do not serve the
+  next decision;
+- `typeset` - repair hierarchy, measure, line length, and emphasis;
+- `colorize` - establish a restrained semantic palette and contrast states;
+- `layout` - repair grouping, density, alignment, and responsive composition;
+- `polish` - resolve the small visual inconsistencies after the structure is
+  right;
+- `audit` - check slop, accessibility, responsive behavior, and visual drift.
+
+Do not average several directions into a generic compromise. Deal two or three
+coherent options when the brief is open, select one, and encode the decision in
+tokens and `DESIGN.md`.
+
+## Anti-slop audit
+
+Before handoff, inspect the first viewport and ask:
+
+- Did the app inherit the neighboring app's palette or hero layout without a
+  product reason?
+- Are there equal-weight cards, status chips, helper paragraphs, or controls
+  that should be removed or disclosed?
+- Does the typography fit the product mode instead of decorating the shell?
+- Is the AgentSidebar distinct but quiet, with the domain page still primary?
+- Are focus, loading, empty, error, dark, and narrow-width states part of the
+  same design direction?

package/corpus/templates/tasks/agent-native.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "off",
+      "production": "connect-and-integrations"
+    }
+  },
+  "doctor": {
+    "failOnBuild": false
+  }
+}

package/dist/action.d.ts

@@ -52,6 +52,12 @@ export interface ActionRunContext {
      * must apply their own.
      */
     userEmail?: string;
+    /**
+     * Request headers for server-only actions that must delegate to an
+     * authenticated framework protocol, such as Better Auth password setup.
+     * Never expose this context to agent tools or return it from an action.
+     */
+    requestHeaders?: Headers;
     /** Resolved org id, or `null` when the request has no org. */
     orgId?: string | null;
     /** How this action was invoked. */

package/dist/agent/engine/builder-engine.js

@@ -343,7 +343,7 @@ async function* emitHttpError(response) {
         yield {
             type: "stop",
             reason: "error",
-            error: "Builder authentication failed. Reconnect Builder via Settings.",
+            error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
         };
         return;
@@ -353,7 +353,7 @@ async function* emitHttpError(response) {
         yield {
             type: "stop",
             reason: "error",
-            error: "Builder authentication failed. Reconnect Builder via Settings.",
+            error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
         };
         return;

package/dist/agent/engine/credential-errors.d.ts

@@ -5,7 +5,7 @@ export declare const LLM_MISSING_CREDENTIALS_ERROR_CODE = "missing_credentials";
  * recognize it without importing server-only code into the browser bundle.
  */
 export declare const CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE = "credential_store_unavailable";
-export declare const LLM_MISSING_CREDENTIALS_MESSAGE = "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io or add a provider key.";
+export declare const LLM_MISSING_CREDENTIALS_MESSAGE = "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io (free tier available) or add a provider key.";
 export declare function isLlmCredentialError(error: unknown, errorCode?: string | null): boolean;
 export declare function formatLlmCredentialErrorMessage(options?: {
     agentName?: string;

package/dist/agent/engine/credential-errors.js

@@ -6,7 +6,7 @@ export const LLM_MISSING_CREDENTIALS_ERROR_CODE = "missing_credentials";
  * recognize it without importing server-only code into the browser bundle.
  */
 export const CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE = "credential_store_unavailable";
-export const LLM_MISSING_CREDENTIALS_MESSAGE = "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io or add a provider key.";
+export const LLM_MISSING_CREDENTIALS_MESSAGE = "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io (free tier available) or add a provider key.";
 const LLM_CREDENTIAL_KEYS = new Set([
     ...PROVIDER_ENV_VARS,
     "BUILDER_PRIVATE_KEY",
@@ -40,7 +40,7 @@ export function isLlmCredentialError(error, errorCode) {
 export function formatLlmCredentialErrorMessage(options) {
     const agentName = options?.agentName?.trim();
     if (agentName) {
-        return `The ${agentName} agent could not finish this request because that app needs an LLM connection. Open ${agentName}'s Manage agent > LLM, then connect Builder.io or add a provider key.`;
+        return `The ${agentName} agent could not finish this request because that app needs an LLM connection. Open ${agentName}'s Manage agent > LLM, then connect Builder.io (free tier available) or add a provider key.`;
     }
     return LLM_MISSING_CREDENTIALS_MESSAGE;
 }

package/dist/agent/production-agent.js

@@ -2128,6 +2128,7 @@ const DEFAULT_INITIAL_TOOL_NAMES = new Set([
     // supplied by the plugin's effective starter list, while provider, MCP,
     // extension, and other uncommon schemas stay reachable through tool-search.
     "resources",
+    "framework-search",
     "docs-search",
     "get-framework-context",
     "read-attachment",
@@ -4394,11 +4395,11 @@ export async function runAgentLoop(opts) {
             // `refresh-screen` itself.
             if (!isError) {
                 try {
-                    const { actionCallIsReadOnly, notifyActionChange } = await import("../server/action-change.js");
+                    const { actionCallIsReadOnly, notifyActionChangeInBackground } = await import("../server/action-change.js");
                     if (!actionCallIsReadOnly(actionEntry, toolCall.input, false)) {
                         const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
                         const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
-                        await notifyActionChange({
+                        notifyActionChangeInBackground({
                             actionName: toolCall.name,
                             ...(owner ? { owner } : {}),
                             ...(orgId ? { orgId } : {}),

package/dist/brand-kit/fig/index.js

@@ -3,7 +3,7 @@ const LEGACY_LOCAL_COPY_MAGIC = new Uint8Array([
     0x66, 0x69, 0x67, 0x2d, 0x6b, 0x69, 0x77, 0x69,
 ]);
 function unsupportedFigImport() {
-    throw new Error("Legacy .fig helpers no longer process files locally. Connect Builder and use the design system indexing flow instead.");
+    throw new Error("Legacy .fig helpers no longer process files locally. Connect Builder (free tier available) and use the design system indexing flow instead.");
 }
 export function looksLikeFigFile(data) {
     const isZip = data[0] === 0x50 &&

package/dist/cli/agent.js

@@ -199,8 +199,8 @@ function buildHeadlessSystemPrompt(actionNames) {
     return [
         "You are the app agent for this Agent-Native project.",
         "Use the registered app actions as your source of truth for doing work.",
-        "Use docs-search before implementing or answering advanced Agent Native framework questions; it reads the version-matched docs bundled with @agent-native/core.",
-        "Use source-search when examples or implementation details matter; it reads the version-matched core and template source corpus bundled with @agent-native/core.",
+        "Use framework-search first for questions that may span the version-matched docs and source; it supports bounded substring, wildcard, SQL-like, and safe-regex matching.",
+        "Use docs-search or source-search for a focused page/file read after framework-search identifies the relevant evidence.",
         "Use connected GitHub repository tools for repo context when a repository is configured; do not assume a local clone or sandbox exists.",
         "You are running headlessly from the command line, so reply with the final useful result in plain text.",
         actionList,
@@ -224,7 +224,49 @@ function cliArgsFromToolArgs(args) {
 export async function createHeadlessBuiltinActions() {
     const docsSearch = await import("../scripts/docs/search.js");
     const sourceSearch = await import("../scripts/docs/source-search.js");
+    const frameworkSearch = await import("../scripts/docs/framework-search.js");
     return {
+        "framework-search": {
+            readOnly: true,
+            tool: {
+                description: "Search version-matched Agent Native docs and readable Core, Toolkit, and first-party template source together. Use this first when a docs answer may require implementation evidence; supports substring, glob, SQL-like, and safe regex modes.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        pattern: {
+                            type: "string",
+                            description: "Text pattern to search across docs and source.",
+                        },
+                        scope: {
+                            type: "string",
+                            description: "Search corpus: all, docs, or source (default: all).",
+                            enum: ["all", "docs", "source"],
+                        },
+                        mode: {
+                            type: "string",
+                            description: "Match mode: substring, glob, sql-like, or safe regex (default: substring).",
+                            enum: ["substring", "glob", "sql-like", "regex"],
+                        },
+                        path: {
+                            type: "string",
+                            description: "Optional glob path filter.",
+                        },
+                        limit: {
+                            type: "string",
+                            description: "Maximum matching files to return, from 1 to 50.",
+                        },
+                        list: {
+                            type: "string",
+                            description: 'Set to "true" to list searchable docs and source roots.',
+                            enum: ["true"],
+                        },
+                    },
+                },
+            },
+            run: async (args) => {
+                return captureCliOutput(() => frameworkSearch.default(cliArgsFromToolArgs(args)));
+            },
+        },
         "docs-search": {
             readOnly: true,
             tool: {
@@ -255,7 +297,7 @@ export async function createHeadlessBuiltinActions() {
         "source-search": {
             readOnly: true,
             tool: {
-                description: "Search and read the packaged Agent Native first-party template corpus under node_modules/@agent-native/core/corpus. Use --list for sections, --query to search template source, and --path to read a file.",
+                description: "Search and read readable version-matched Core, Toolkit, and first-party template source. Use framework-search for one combined docs/source search with glob, SQL-like, or regex matching; use --list, --query, or --path for focused source lookup.",
                 parameters: {
                     type: "object",
                     properties: {

package/dist/cli/code-agent-executor.js

@@ -1338,7 +1338,8 @@ Current run mode: ${mode} mode (${permissionMode}).
 # Autonomy and verification
 
 - Stay with the work until the task is handled end to end within this turn whenever feasible. Don't stop at analysis or a proposal — implement the fix, and work through blockers yourself before handing them back. The exception is Plan mode, where you propose only.
-- Done means verified, not generated. After code changes (not docs-only), run the repo's checks before reporting success: \`pnpm run prep\` (format + typecheck + test + guards), or a focused subset like \`pnpm typecheck\` or a single package's tests for a small change. Fix all errors before you call it done.
+- Done means verified, not generated. Match the check to the change: use the narrowest relevant test, typecheck, formatter, or direct invocation for a localized edit; use \`pnpm run prep\` for shared or cross-cutting changes. Do not restart a dev server or run broad checks as a generic post-edit ritual. Fix failures before you call it done, and keep any repository-required guards or doctor checks that apply.
+- In an Agent-Native app or workspace, also run \`pnpm agent-native:doctor\` (or \`pnpm doctor\`) after source changes. Treat every finding as a fix-required security issue; do not disable a guard without a reviewer-readable reason.
 - Do not claim a change works, tests pass, or a build succeeds unless you actually ran it and saw the result. If you could not verify something, say exactly what is unverified and why.
 
 # Tools beyond the basics

package/dist/cli/create.d.ts

@@ -131,6 +131,14 @@ declare function communityTemplateTrustMessage(selection: string): string | unde
  * templates need it.
  */
 declare function scaffoldRequiredPackages(templateNames: string[], workspaceRoot: string): Promise<void>;
+/**
+ * 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.
+ */
+declare function ensureGuardedScaffold(appDir: string): void;
 /**
  * Post-process a standalone scaffold: replace placeholders, strip
  * workspace:* deps, set up agent symlinks, etc.
@@ -147,7 +155,7 @@ export declare function detectWorkspace(startDir: string): {
 } | null;
 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, };
 declare function tarExtractArgs(tarPath: string, destDir: string, options?: {
     skipAgentSymlinks?: boolean;
     untrustedCommunityArchive?: boolean;