@agent-native/core 0.210.0-nightly-20261019153056 → 0.210.0

package/dist/mcp/direct-action-call.js

@@ -1,5 +1,6 @@
 import { actionCallReadOnly, actionChangeResource, } from "../action-call-classification.js";
 import { ActionOutputContractError, failedCallEmitsChange, isActionOutputContractError, invocationEffect, ranCallEmitsChange, } from "../action.js";
+import { agentErrorDetails } from "../agent/action-error-details.js";
 import { extractAgentImagesFromActionResult } from "../agent/tool-result-images.js";
 import { writeActionChangeMarker } from "../server/action-change-marker-write.js";
 import { captureError } from "../server/capture-error.js";
@@ -35,6 +36,13 @@ export function createDirectActionCall(scope) {
     return async (call, fail) => {
         const { name, args, request, ctx } = call;
         const callableActions = fullCatalogRequested ? actions : advertisedActions;
+        // A directory profile may project results arbitrarily, so the derived
+        // contract is advertised and enforced on app catalogs only. It compiles
+        // before the action runs. A host may hold an error result to the same
+        // schema, so a contracted tool's errors carry no structuredContent.
+        const outputContract = directoryCatalog
+            ? undefined
+            : callableActions[name]?.mcpOutputContract;
         const errorText = (err) => {
             const projectedError = directoryCatalog && config.directoryProfile?.projectResult
                 ? config.directoryProfile.projectResult(name, err.message)
@@ -55,10 +63,37 @@ export function createDirectActionCall(scope) {
             try {
                 const errorCode = mcpActionErrorCode(err);
                 const { errorType, errorMessage } = describeMcpError(err);
-                return toolCallError({
-                    errorType: redactEmbedText(errorType),
-                    errorMessage: redactEmbedText(errorMessage),
-                }, `${redactEmbedText(errorText(err))}${errorCode !== undefined ? ` (errorCode: ${redactEmbedText(errorCode)})` : ""}`);
+                const message = redactEmbedText(errorText(err));
+                // A directory profile decides what its catalog shows, and it
+                // projects only the message.
+                const details = directoryCatalog ? undefined : agentErrorDetails(err);
+                const detailsLine = details && redactEmbedText(details.line);
+                return {
+                    ...toolCallError({
+                        errorType: redactEmbedText(errorType),
+                        errorMessage: redactEmbedText(errorMessage),
+                    }, `${message}${errorCode !== undefined ? ` (errorCode: ${redactEmbedText(errorCode)})` : ""}${detailsLine ? `\n${detailsLine}` : ""}`),
+                    // Some clients hand the model structuredContent in place of the
+                    // text, so it repeats the message rather than carrying details
+                    // alone. Details the embed check hid in the text stay out of it.
+                    ...(details && detailsLine === details.line && !outputContract
+                        ? {
+                            structuredContent: {
+                                error: {
+                                    message,
+                                    errorCode: err.errorCode,
+                                    details: details.details,
+                                    ...(details.omittedKeys
+                                        ? {
+                                            omittedKeys: details.omittedKeys,
+                                            omittedKeyCount: details.omittedKeyCount,
+                                        }
+                                        : {}),
+                                },
+                            },
+                        }
+                        : {}),
+                };
             }
             catch {
                 return toolCallError({
@@ -67,12 +102,6 @@ export function createDirectActionCall(scope) {
                 });
             }
         };
-        // A directory profile may project results arbitrarily, so the derived
-        // contract is advertised and enforced on app catalogs only. It compiles
-        // before the action runs.
-        const outputContract = directoryCatalog
-            ? undefined
-            : callableActions[name]?.mcpOutputContract;
         let checkOutput;
         try {
             checkOutput = outputContract

package/dist/notifications/routes.d.ts

@@ -1,12 +1,12 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -14,8 +14,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -33,22 +33,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
 } | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
 } | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;
     traceMissing: true;
     id: string;
 } | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
     message?: undefined;
     summary?: undefined;
     spans?: undefined;

package/dist/onboarding/workspace-services.js

@@ -103,7 +103,7 @@ export const WEB_SEARCH_CAPABILITY = {
     required: false,
     suggested: true,
     builderIncluded: true,
-    keySummary: "Builder-managed web search",
+    keySummary: "Web search",
     labelKey: "agentChat.onboarding.capability.webSearch.label",
     keySummaryKey: "agentChat.onboarding.capability.webSearch.keySummary",
     whyKey: "agentChat.onboarding.capability.webSearch.why",

package/dist/progress/routes.d.ts

@@ -2,6 +2,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,6 +75,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
+    message?: undefined;
     deleted?: undefined;
     found?: undefined;
     id?: undefined;
@@ -91,8 +92,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     provider?: undefined;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     deleted?: undefined;
     id?: undefined;
     providers?: undefined;
@@ -101,8 +102,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -111,8 +112,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     found?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -121,7 +122,6 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     deleted?: undefined;
     found?: undefined;

package/dist/secrets/routes.d.ts

@@ -65,31 +65,31 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
+    error?: undefined;
     errorCode?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     ok?: undefined;
     error: string;
     note?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -117,11 +117,11 @@ export declare function createAdHocSecretHandler(): import("h3").EventHandlerWit
 } | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -66,8 +66,8 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     error: any;
     code: any;
 } | {
-    errorCode?: undefined;
     error?: undefined;
+    errorCode?: undefined;
     code?: undefined;
     ok: boolean;
     key: string;

package/dist/server/agent-engine-default-model-route.d.ts

@@ -8,8 +8,8 @@ export declare const AGENT_ENGINE_API_KEY_ACTION_NAME = "agent-engine-api-key";
  * resolveEngine's credential detection.
  */
 export declare function createAgentEngineDisconnectHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
     scope?: undefined;
 } | {
     ok: boolean;

package/dist/server/agent-engine-ollama-models-route.d.ts

@@ -1,9 +1,9 @@
 export declare function createAgentEngineOllamaModelsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    models?: undefined;
     ok?: undefined;
+    models?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     models: string[];
-    error?: undefined;
 }>>;

package/dist/templates/chat/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/chat/netlify.toml

@@ -12,7 +12,6 @@ NPM_CONFIG_PRODUCTION = "false"
 
 [context.production.environment]
 AGENT_NATIVE_HOSTED_HARNESS = "true"
-AGENT_NATIVE_ENABLE_KEEP_WARM = "1"
 AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND = "1"
 BETTER_AUTH_TRUSTED_ORIGINS = "https://starter.agent-native.com,https://chat.agent-native.com"
 # Production release migrations own schema setup; request functions must skip

package/dist/templates/default/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/factory/.agents/skills/review-prs/SKILL.md

@@ -3,8 +3,9 @@ name: review-prs
 description: >-
   Review recent BuilderIO/agent-native human pull requests, approve eligible
   internal PRs, and merge changes that are ready by Steve's bar. Use for
-  scheduled or manual PR sweeps; flag external non-bug work and unresolved major
-  product or UX decisions to Steve.
+  scheduled or manual PR sweeps; flag external work needing a major product
+  call or new framework API, and unresolved major product or UX decisions, to
+  Steve.
 user-invocable: true
 scope: dev
 metadata:
@@ -20,10 +21,12 @@ approve an external or unverified author.
 
 Approval and merge readiness are separate. A **Ready to merge by Steve's bar**
 result means merge the PR under the guarded merge procedure below. For a
-confirmed external author, only a clear bug fix enters evidence review and the
-possible merge flow; external authors are never eligible for an approval
-review. Surface other external work for Steve's explicit approval before a full
-review or merge; a scheduled or manual sweep is not that approval.
+confirmed external author, a clear bug fix or a bounded improvement that
+follows existing patterns enters evidence review and the possible merge flow;
+external authors are never eligible for an approval review. Surface external
+work that needs a major product call or a new framework API for Steve's explicit
+approval before a full review or merge; a scheduled or manual sweep is not that
+approval.
 
 ## Selection and evidence
 
@@ -53,6 +56,11 @@ author and draft state:
    summary to determine whether the PR already has a current, non-dismissed
    `APPROVED` review.
 
+ - Before the scope gate, check a confirmed nonmember's PR from a fork for
+   assignees. If any assignee is a verified current BuilderIO member, ignore
+   the PR completely, like a draft: that person owns it under `community-prs`.
+   Take no review, reply, or merge action, and leave it out of the recap.
+
  - Reuse that review as the code assessment only after verifying the reviewer
    is a different, current BuilderIO member and is eligible under the PR's
    author- and scope-specific rules, including any independent-review
@@ -99,17 +107,28 @@ the patch looks safe or the issue is obviously valid.
 
 ## External-contribution scope gate
 
+Builder devs decide bounded outside contributions; Steve keeps major product
+calls and new framework APIs.
+
 For an author the membership API confirms is not a current BuilderIO member,
-continue into the normal evidence sweep only for a clear bug fix: a change that
-corrects a specific reported or reproducible defect by restoring intended
-behavior. A feature, improvement, refactor, new or changed product behavior, or
-mixed bug-fix-and-enhancement scope is not a clear bug fix. If the title, issue,
-and initial diff do not establish a clear bug fix, treat it as non-bug work.
-
-For external non-bug work, stop before the full code review, approval or review
-action, merge-readiness disposition, author-facing draft, or merge. Report it to
-Steve as **Needs Steve's approval for scope**, with the PR link, author, stated
-scope, and why it is not a clear bug fix. Wait for Steve's explicit go-ahead on
+continue into the normal evidence sweep for a clear bug fix or a bounded
+improvement. A clear bug fix corrects a specific reported or reproducible
+defect by restoring intended behavior. A bounded improvement stays within one
+established workflow, app, or framework area and follows the patterns already
+there.
+
+External work needs Steve when it makes a major product call (as defined under
+Product and UX decisions) or adds a new framework API: a new public export,
+configuration option, action, plugin or hook contract, or CLI surface in a
+published package under `packages/`. A fix or bounded improvement to an existing
+API stays with devs when it keeps that API's contract. If the title, issue, and
+initial diff do not establish a clear bug fix or a bounded improvement, treat it
+as needing Steve.
+
+For external work that needs Steve, stop before the full code review, approval
+or review action, merge-readiness disposition, author-facing draft, or merge.
+Report it to Steve as **Needs Steve's approval for scope**, with the PR link,
+author, stated scope, and which call it needs. Wait for Steve's explicit go-ahead on
 that PR before continuing. Invoking or scheduling `review-prs`, approving a
 different PR, or prior approval of another external contribution does not
 authorize it. If membership is unknown, use the existing unknown-membership
@@ -118,6 +137,8 @@ solely because membership could not be verified. Keep the no-approval outcome,
 report the missing membership check, and assess merge readiness under the
 existing unknown-membership policy.
 
+Builder devs own outside PRs end to end with `community-prs`.
+
 ## Liamdebeasi approval policy
 
 For a PR authored by the exact GitHub login `liamdebeasi` and immutable user
@@ -296,9 +317,10 @@ merge scope and must remain completely untouched.
 For a PR that fails an approval gate, do not submit an approval. Flag the exact
 concern and the evidence needed to resolve it. External or unverified authors
 never receive an approval review, but their PRs can still be merged when they
-meet the readiness gate below. Confirmed external bug fixes must also pass the
-external-contribution scope gate; confirmed external non-bug work remains
-stopped at Steve's approval gate. For unknown membership, do not apply the
+meet the readiness gate below. Confirmed external PRs must also pass the
+external-contribution scope gate; external work that needs a major product call
+or a new framework API remains stopped at Steve's approval gate. For unknown
+membership, do not apply the
 external scope gate solely because verification failed; preserve the
 no-approval outcome, assess readiness under the existing unknown-membership
 policy, and name the missing check.
@@ -504,7 +526,8 @@ non-auto-approved external PR that needs an update or screenshot, include its
 draft reply in a separate section, or mark it waiting on the contributor with
 a link to Steve's outstanding request. For internal PRs, report the needed
 update or screenshot without drafting an author-facing reply. Do not add rows
-for bots, `steve8708`, or drafts; those are ignored completely.
+for bots, `steve8708`, drafts, or external PRs assigned to a BuilderIO member;
+those are ignored completely.
 
 Use this shape:
 
@@ -525,4 +548,4 @@ blocker when the PR is ready and the guarded admin merge is available.
 
 ## Related skills
 
-`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`
+`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`, `community-prs`

package/dist/templates/headless/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/docs/content/actions-defining.mdx

@@ -324,7 +324,7 @@ What you throw decides how much of the message survives. `fail()` raises an `Act
 - **message**: the text the caller reads. Write it for a person, not for a log.
 - **options.errorCode**: a stable machine-readable code. Defaults to `"action_failed"`.
 - **options.statusCode**: the HTTP status for the action route. Defaults to `400`.
-- **options.details**: safe structured context for the caller. Never put secrets or raw driver output here.
+- **options.details**: safe structured context for the caller, such as the id a retry needs. The browser and agents both receive it. Never put secrets or raw driver output here.
 
 The simplest call needs only a message:
 
@@ -402,7 +402,7 @@ A network drop, a proxy's HTML error page, and a bare status line author no mess
 
 So the status is not cosmetic. A refusal sent as `404` costs one round trip. The same refusal sent as a `500`, or thrown bare, costs four round trips and four duplicate error reports.
 
-Agent callers never see the status. The agent runs `run()` in process, so it receives the message directly whatever the type, as `Error running <action>: <message>`. An `errorCode` other than the default `action_failed` is appended as `(errorCode: not_found)` so the model can branch on it without parsing prose. External agents over MCP get the same text. Secrets in the message are redacted first, and the agent's own repeated-error breakers bound how many times it tries again.
+Agent callers never see the status. The agent runs `run()` in process, so it receives the message directly whatever the type, as `Error running <action>: <message>`. An `errorCode` other than the default `action_failed` is appended as `(errorCode: not_found)` so the model can branch on it without parsing prose. `details` follow on their own line as compact JSON, such as `Error details: {"importId":"imp_1"}`, so an id the model needs for its next call doesn't have to be written into the message. External agents over MCP get the same text, and the same details in `structuredContent.error`. A tool that advertises an output schema (`mcpOutputSchema: true`) returns the text only, since a client may check an error result against that schema too. Details are capped at 2,000 characters: past that, small top-level entries are kept and the rest are listed as omitted. Secrets in the message and details are redacted first, and the agent's own repeated-error breakers bound how many times it tries again.
 
 ## Keep the action surface small {#small-surface}
 

package/docs/content/template-chat-agent.mdx

@@ -0,0 +1,88 @@
+---
+title: "Chat: Talk to the Agent"
+description: "What the agent knows about where you are in Chat, and prompts organized by task."
+---
+
+# Talk to the Agent
+
+In Chat, the conversation is the main way you use the app. The agent can run the app's actions, look things up, remember what you tell it, and take you to other pages. This page covers what the agent knows about your screen, useful prompts by task, and where it goes beyond the built-in actions. See [Chat](/docs/template-chat) for the overview.
+
+## How the agent sees your screen
+
+The agent always knows which page you're on and which conversation is open. That's why "take me back to Home" or "what page am I on?" works without any explanation. The app tells the agent about every page change as it happens, so the agent never has to guess.
+
+Chat has no business data to point at, such as a selected event or an open document. Everything else the agent knows comes from what you say in the conversation.
+
+## Useful prompts by task
+
+Every prompt below runs against the real app. Here's one worked example:
+
+<Comparison>
+
+### :blue: You ask
+
+"Call the hello action for Alex."
+
+### :green: What happens
+
+The agent runs the example **hello** action with the name Alex. The action
+returns "Hello, Alex!" and the agent shows it in the chat. Nothing else in the
+app changes.
+
+</Comparison>
+
+<Cards columns={2}>
+
+### Learn what the app can do
+
+- **"What can this app do?"** The agent lists the actions it has and what each
+  one does.
+- **"Show me the available actions."** Same idea, as a plain list of names.
+- **"Help me get started."** The agent suggests a first thing to try.
+
+### Get around
+
+- **"Take me to Settings."** The app opens the page for you.
+- **"Open the Database page."** The agent opens `/database`, which isn't linked
+  from the sidebar.
+- **"Go back to Home."** The Get started page opens.
+
+### Teach the agent
+
+- **"Remember that I prefer short answers."** The agent saves it to its
+  memory, and uses it in later chats.
+- **"From now on, always explain your reasoning before answering."** The agent
+  can save this as a standing instruction.
+- **"What do you remember about me?"** The agent reads its memory back to you.
+
+### Look at your data
+
+- **"What tables are in this app's database?"** The agent reads the database
+  structure and lists the tables.
+- **"How many chats do I have?"** The agent runs a read-only question against
+  the database and answers in the chat.
+
+### Learn the framework
+
+- **"How do I add a new action to this app?"** The agent searches the Agent-Native
+  docs and explains the steps.
+- **"What's the difference between an action and a skill?"** Same, answered
+  from the docs.
+
+</Cards>
+
+<Callout tone="info">
+
+The agent reads the database but doesn't change it directly. To save new
+information, it uses an action. That keeps every change on the same path the
+app's own screens use. A developer can change this in the app's setup.
+
+</Callout>
+
+## What's next
+
+- [**Chat**](/docs/template-chat) — the overview
+- [**Features**](/docs/template-chat-features) — conversations, the example action, teams, and admin pages
+- [**Chat in a Multi-App Workspace**](/docs/template-chat-integrations) — connecting Chat to Dispatch and other apps
+- [**Developer Guide**](/docs/template-chat-developers) — quick start, actions, the chat route, and adding your first feature
+- [**Context Awareness**](/docs/context-awareness) — how the agent knows what's on your screen