@agent-native/core 0.152.1 → 0.153.0

package/corpus/templates/mail/.agents/skills/turn-into-app/SKILL.md

@@ -3,9 +3,10 @@ name: turn-into-app
 description: >-
   Turn visible project context, a proven thread, skill, or workflow into a
   runnable Agent-Native app with simple buttons, visible agent steps, preview,
-  and deployment handoff. Use when a user invokes `/turn-into-app`,
-  `/make-into-app`, or asks to make a workflow into an app, including from
-  Claude or ChatGPT on the web.
+  and deployment handoff. Use when a user invokes `/turn-into-app` or asks to
+  make a workflow into an app, including from
+  Claude or ChatGPT on the web, including when the source is a spreadsheet
+  link or upload.
 user-invocable: true
 scope: both
 metadata:
@@ -16,43 +17,59 @@ metadata:
 
 ## Host execution boundary
 
-The build location depends on the host. Treat this as a hard routing rule:
-
-- In Claude Web, ChatGPT Web, or a Claude/ChatGPT Project on the web, you are
-  the source analyst and handoff orchestrator. You must not build the app in
-  the host sandbox. Do not run `npm`, `pnpm`, `npx`, `agent-native create`, or
-  `add-app`; do not edit files, create artifacts, or start a local dev server.
-  After writing the bounded source brief, call the connected Dispatch action
+Classify the runtime before choosing a build path. The presence of a Dispatch
+or Builder connector does not make a coding host an online host:
+
+- **Local coding host** - Codex Desktop/Code, Claude Code, Cursor, or any
+  runtime with a terminal, filesystem, and target checkout. Build in that
+  checkout: scaffold, edit, run, and verify the app locally. Do not call
+  `start-workspace-app-creation`, `create_workspace_app`, or any Builder
+  handoff for this path. The local implementation steps below are required.
+- **Non-coding browser host** - Claude Web, ChatGPT Web, or a
+  Claude/ChatGPT Project in the browser when no target checkout or filesystem
+  is available. Act as the source analyst and handoff orchestrator. Do not run
+  `npm`, `pnpm`, `npx`, `agent-native create`, or `add-app`; do not edit files,
+  create artifacts, or start a local dev server. After writing the bounded
+  source brief, call the connected Dispatch action
   `start-workspace-app-creation`. Pass the brief and repeatable workflow in
   `prompt`, plus the inferred `appId`, `description`, `template`, and selected
-  `resourceIds` when available. This is the Builder handoff.
-- Do not substitute the generic `create_workspace_app` MCP tool in an online
-  host. That tool is a local workspace scaffolder, not the Builder handoff.
-- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
-  authenticated Builder Projects API to reuse or provision the workspace
-  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
-  connection is not required for this workflow.
-- If `start-workspace-app-creation` is not available or Dispatch is not
+  `resourceIds` when available. This is the Builder handoff for browser hosts
+  only.
+- If the host is ambiguous, inspect the environment. A real cwd, terminal, and
+  target workspace mean local coding host. Do not infer browser mode from the
+  availability of a Builder connector.
+- For the browser-only path, do not substitute the generic
+  `create_workspace_app` MCP tool. That tool is a local workspace scaffolder,
+  not the Builder handoff. Connect the Agent-Native Dispatch MCP connector
+  only; Dispatch uses the authenticated Builder Projects API to reuse or
+  provision the workspace project before starting the Builder Cloud Agent.
+- If the browser-only handoff action is unavailable or Dispatch is not
   authenticated, stop with the connector setup needed. Do not fall back to a
-  local build or claim that the app exists.
-- In Claude Code, Codex Code, or another local code-agent runtime with a target
-  workspace, follow the local implementation steps below. The local agent may
-  scaffold, edit, run, and verify the app there.
+  host sandbox build or claim that the app exists.
+- Never invent a Builder branch URL. If Dispatch returns only an acknowledgement
+  or a path without a URL, report the handoff as unverified rather than calling
+  it a ready or verified Builder branch.
 
 Once the source brief is sufficient to identify a repeatable workflow, the
 handoff is non-interactive. Do not ask the user for visual, product, copy,
 layout, template, integration, or implementation choices that can be resolved
 from the source. Select the source's recommended option; otherwise choose the
 most direct conventional default and record the assumption for later review.
+There is one source-integrity exception: for a spreadsheet, if candidate
+workflows or the input/output mapping remain materially ambiguous after the
+bounded review, ask one compact confirmation question before handoff. Show the
+recommended interpretation and let the user confirm, correct, or multi-select
+the candidates. Do not turn this into a generic app-builder questionnaire.
 Only stop for a genuine hard blocker such as missing authorization, a
 destructive external action, an ambiguous target workspace, or no identifiable
 workflow at all.
 
 ## Default behavior
 
-For a local code-agent runtime this is an end-to-end build skill, not a request
-for an app proposal. For an online host, the end-to-end result is a verified
-Builder handoff and the resulting workspace app, not code written in the host.
+For a local coding host this is an end-to-end local build skill, not a request
+for an app proposal. For a non-coding browser host, the end-to-end result is a
+verified Builder handoff and the resulting workspace app, not code written in
+the browser host.
 
 - With no argument, choose the source in this order: visible project context,
   then the current thread. A fresh Claude or ChatGPT Project is a valid source
@@ -66,9 +83,10 @@ Builder handoff and the resulting workspace app, not code written in the host.
 - With an attachment or path, read the supplied artifact as the source.
 - Do not ask the user to restate context that is already in the thread.
 - When invoked from an Agent-Native app, use its visible project context first,
-  then the current thread, and use the available workspace/coding-agent
-  handoff when the current runtime cannot edit files. Do not claim the app
-  exists without an actual path and verification result.
+  then the current thread. If the current runtime has a target checkout, use
+  the local implementation path; use a workspace/coding-agent handoff only
+  when the runtime cannot edit files. Do not claim the app exists without an
+  actual path and verification result.
 
 ## Source support
 
@@ -98,22 +116,62 @@ Spreadsheet attachments are valid source artifacts for this workflow:
   provider API catalog/docs/request path to read only the required sheet or
   range. If that connection is unavailable, ask for a CSV/XLSX export or the
   required connection; do not use a public export URL to bypass access.
+- First inventory the workbook before choosing an app: list every available
+  worksheet, its bounded shape, whether it is readable, and any visible
+  formulas or formatting signals. Do not assume the first tab is the product
+  or that every tab deserves its own app.
+- Treat the workbook's visual conventions as evidence, not as a silent truth:
+  yellow-filled cells are proposed inputs, blue text is proposed output, and
+  black text is static historical context. Apply those signals to cell/range
+  mappings only when the source exposes formatting metadata. The current
+  bounded Excel preview is text-only, so an upload alone cannot prove those
+  colors; ask the user to confirm or clarify instead of inferring from plain
+  text. See [the spreadsheet source guide](references/spreadsheet-source.md).
+- If the workbook contains several plausible repeatable jobs, present one
+  compact Q&A review with multi-select candidate options. Each option must
+  show its proposed name, source worksheet/range IDs, purpose, inferred inputs,
+  inferred outputs, confidence, and unresolved question. Default-select only
+  high-confidence recommendations. Mark the strongest recommendations in the
+  Q&A UI without silently selecting them. When the user selects multiple candidates,
+  implement them as separate named left-navigation destinations in one app,
+  with each destination preserving its own source tabs/ranges and I/O mapping.
+- In generated app code, render this review with
+  `askUserQuestion` from `@agent-native/core/client/agent-chat` using
+  `allowMultiple: true`, stable candidate IDs as option values, and
+  `allowFreeText: true` for corrections. It renders inline in the agent panel;
+  do not build a custom modal. Group a large workbook into 2-4 candidate jobs
+  per question instead of presenting a tab dump.
+- Before handoff or the first generated-app run, show the proposed source,
+  inputs, outputs, static historicals, refresh/snapshot choice, and truncation
+  limits as a review state. Let the user confirm or correct the mapping. Do not
+  publish, overwrite the source, or claim a complete import before confirmation.
+- Do not promote every numeric cell or model assumption into an editable app
+  input. Classify candidates as primary controllable drivers, secondary
+  controllable levers, or fixed model context. Opening balances, current-period
+  anchors, historicals, and policy or tax rates stay in fixed context unless
+  the source or user explicitly identifies them as editable.
+- Rank the primary edit surface by controllability and modeled leverage. Put the
+  smallest useful set of high-impact drivers first, keep lower-frequency levers
+  behind progressive disclosure, and keep fixed context visible for orientation
+  without presenting it as a control. Name these categories in the source brief
+  and preserve the distinction in the generated app's actions and agent context.
 - Decide whether the generated app needs a one-time snapshot or a refreshable
   source. For a snapshot, pass bounded sample context and provenance to the
-  Builder handoff. For a live source, preserve the provider/file identity,
-  worksheet or range, and refresh semantics, then implement a scoped action for
-  reads or refreshes. Never copy workbook bytes, base64 data, credentials, or a
-  full unbounded sheet into SQL, application state, or the handoff prompt.
+  local build or the browser-only Builder handoff selected by the host. For a
+  live source, preserve the provider/file identity, worksheet or range, and
+  refresh semantics, then implement a scoped action for reads or refreshes.
+  Never copy workbook bytes, base64 data, credentials, or a full unbounded
+  sheet into SQL, application state, or the handoff prompt.
 - Do not claim the app imported the whole workbook when only a preview was
   available. Keep unreadable, partial, and failed source states distinct from
   an empty sheet.
 
-For local code-agent runtimes, deliver a fresh app in a new directory,
-implement the repeatable workflow with buttons and agent handoffs, start its dev
-server, verify the main path, and continue through build/deployment handoff. Do
-not stop at a plan. For online hosts, call Dispatch first after the source brief,
-then report the returned Builder branch/path and verify the workspace app through
-Dispatch when it becomes available.
+For local coding hosts, deliver a fresh app in a new directory, implement the
+repeatable workflow with buttons and agent handoffs, start its dev server,
+verify the main path, and continue through build/deployment handoff. Do not stop
+at a plan or route the work to Builder. For non-coding browser hosts, call
+Dispatch first after the source brief, then report only the returned Builder
+branch URL/path and verification result; if the URL is absent, say so plainly.
 
 ## Fresh project context mode
 
@@ -182,6 +240,11 @@ Generated apps must follow the shared Agent-Native surface model:
   message or neutral action icon, or no icon when the button label is enough.
 - Make the left navigation describe domain destinations. Chat is a separate
   destination, not the label for every app page.
+- For a spreadsheet-derived app with multiple confirmed candidates, make each
+  candidate a separate named left-navigation destination. Keep the shared
+  source provenance visible, but show that candidate's selected worksheets,
+  ranges, inputs, outputs, historical context, and confirmation state on its
+  destination.
 - Start with one primary action and one compact state. Put setup choices,
   advanced inputs, diagnostics, and long explanations behind progressive
   disclosure or later workflow steps.
@@ -211,6 +274,14 @@ brief:
 - the buttons, review points, and retry states a user needs;
 - data, permissions, integrations, and failure boundaries.
 
+For a spreadsheet source, also include the workbook/file or spreadsheet ID,
+worksheet and range candidates, source snapshot/live semantics, formatting
+signals and their confidence, selected candidate destinations, and the exact
+confirmation or clarification still needed. A spreadsheet's inputs and
+outputs have two layers: the mapped source cells/ranges, and the generated
+app's user-facing results/actions. Name both so the Builder does not confuse
+an output cell with an app write or a historical value with an editable input.
+
 Preserve useful judgment from the source, but do not turn a one-off answer,
 private data, or an unverified result into a product contract. If the source is
 not available or does not contain a repeatable job, say what is missing rather
@@ -243,12 +314,13 @@ Do not use `create` for an existing workspace; it scaffolds a new standalone
 workspace rather than adding an app to the current one.
 
 When the source came from a fresh external Project and the target is a Builder
-workspace, the online host path is mandatory: after writing the source brief,
-call `start-workspace-app-creation` with a concise prompt, the inferred app id,
-and the brief's repeatable workflow. Pass selected workspace resource IDs when
-they are available, rather than pasting entire knowledge files. Continue from
-the returned workspace path or Builder branch handoff and report the actual
-verification result. Do not run the local scaffold commands in this host mode.
+workspace, the browser-only host path is mandatory: after writing the source
+brief, call `start-workspace-app-creation` with a concise prompt, the inferred
+app id, and the brief's repeatable workflow. Pass selected workspace resource
+IDs when they are available, rather than pasting entire knowledge files.
+Continue from the returned workspace path or Builder branch handoff and report
+the actual verification result. This rule does not override local host
+classification: Codex/Claude Code with a target checkout must build locally.
 
 Use a first-party template only when it materially fits the workflow. Keep the
 new app independent from the source thread's working tree unless the user

package/corpus/templates/mail/.agents/skills/turn-into-app/references/fresh-project.md

@@ -28,11 +28,13 @@ Write a compact brief before starting the app:
 ```text
 Source: host-provided Claude/ChatGPT Project context
 Provenance: project instructions, selected knowledge files, and visible runs
+Source artifact type: project context, thread, skill, spreadsheet link, or upload
 Project goal:
 Configuration and constraints:
 Knowledge sources:
 Repeatable workflow:
 Inputs and outputs:
+Workbook candidates and confirmation: worksheet/range options, inferred I/O, selected destinations, unresolved questions
 Judgment and review points:
 Representative runs: none, or 1-3 selected examples
 Integrations and permissions:
@@ -72,9 +74,13 @@ skill.
 The brief is an implementation authorization, not a questionnaire. After a
 repeatable workflow is identifiable, choose any source-recommended option
 automatically. For unresolved non-blocking choices, use the most direct
-conventional default, record it under assumptions, and continue. Ask only when
-there is no identifiable workflow, no authorized target workspace, or a
-destructive/credential boundary genuinely prevents the handoff.
+conventional default, record it under assumptions, and continue. A spreadsheet
+is the narrow exception when its candidate workflows or input/output mapping
+cannot be grounded from the bounded source: show the recommended candidates
+and mapping in one compact multi-select confirmation, then continue after the
+user confirms or corrects it. Ask only for that source-integrity clarification,
+no identifiable workflow, no authorized target workspace, or a
+destructive/credential boundary that genuinely prevents the handoff.
 
 In a new Project chat, say:
 

package/corpus/templates/mail/.agents/skills/turn-into-app/references/spreadsheet-source.md

@@ -0,0 +1,148 @@
+# Spreadsheet source review
+
+Use this reference after a workbook upload or Google Sheets link is supplied to
+`/turn-into-app`. It defines the bounded review contract before app creation.
+
+## 1. Establish the source boundary
+
+Record the source before interpreting it:
+
+| Field        | Record                                                                            |
+| ------------ | --------------------------------------------------------------------------------- |
+| Source kind  | `xlsx`, `xls`, `csv`, or Google Sheets URL                                        |
+| Provenance   | Original file name or spreadsheet ID and URL; never credentials or workbook bytes |
+| Access       | Upload preview, authenticated provider read, or unavailable                       |
+| Coverage     | Worksheet names, selected range(s), row/column bounds, and sample counts          |
+| Completeness | Complete within the requested bound, partial, truncated, unreadable, or empty     |
+| Refresh      | One-time snapshot or live refreshable source                                      |
+
+For an uploaded XLS/XLSX file, the framework preview contains worksheet names,
+dimensions, and representative displayed values within bounds. It does not
+currently preserve cell fills or font colors in that text preview. Treat the
+original workbook as the formatting authority only when a tool actually returns
+cell formatting metadata. Never describe a text-only upload as style-verified.
+
+For a Google Sheets URL:
+
+1. Parse the spreadsheet ID and preserve the original URL as provenance.
+2. Use the authenticated `google_drive` provider path. Inspect
+   `provider-api-catalog` first, use `provider-api-docs` if the endpoint or
+   fields are uncertain, and then call `provider-api-request`.
+3. Read spreadsheet metadata and only bounded worksheet/range data. Request
+   formatting metadata when the I/O decision depends on colors, including
+   `userEnteredFormat.backgroundColor` and
+   `userEnteredFormat.textFormat.foregroundColor` where the provider supports
+   it. Do not use a public export URL to bypass access.
+4. Preserve the spreadsheet ID, worksheet title, A1 range, account/connection
+   choice without secrets, row limits, and refresh behavior in the brief.
+
+Keep provider responses bounded. For large sheets, stage or save the response
+and reduce it with the available dataset/code tools. A failed page, truncated
+response, or unavailable connection is not an empty sheet.
+
+## 2. Infer cells and ranges, then show the evidence
+
+Classify source material into three separate buckets. Include representative
+cell addresses or ranges and the evidence behind each classification.
+
+| Bucket             | Default signal                                                                                                     | App treatment                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Inputs             | Yellow cell background, editable assumptions, user-entered constants, or labels such as `assumption` / `driver`    | Editable controls or bounded source parameters                         |
+| Outputs            | Blue text, formula-derived result cells, summary blocks, or labels such as `forecast` / `recommendation`           | Read-only results, charts, recommendations, exports, or review actions |
+| Static historicals | Black text used intentionally for prior-period/source records, raw rows, or labels such as `actual` / `historical` | Read-only context; never turn into editable inputs by default          |
+
+These are conventions, not permission to guess. A default black font with no
+explicit style metadata is not enough to label a range as historical. Resolve
+conflicts using labels, formulas, neighboring headers, repeated patterns, and
+the user's stated goal. If the evidence still conflicts, lower confidence and
+ask the user to confirm the proposed mapping.
+
+Keep source cells and app behavior distinct:
+
+- `Source inputs` are the workbook cells or ranges the user is expected to
+  change or refresh.
+- `Source outputs` are the workbook cells or ranges the source already derives
+  or presents.
+- `Static historicals` are context the app may filter, compare, or summarize,
+  but should not edit.
+- `App outputs` are the new app's visible results, saved records, exports,
+  alerts, or downstream handoffs. Do not invent these until the repeatable job
+  or user confirmation makes them clear.
+
+## 3. Offer candidate apps, not a tab dump
+
+Group related worksheets into candidate repeatable jobs. A candidate should
+have a recognizable user, trigger, inputs, transformation or judgment, and
+outputs. Utility tabs such as lookups, raw imports, instructions, pivots, and
+calculation helpers can support a candidate without becoming destinations.
+
+Present a compact Q&A review with multi-select options. In generated app code,
+use `askUserQuestion` from `@agent-native/core/client/agent-chat` with
+`allowMultiple: true`, stable candidate IDs as option values, and
+`allowFreeText: true` for corrections. It renders inline in the agent panel;
+do not build a custom modal. Each option should fit in a scannable row or
+choice card:
+
+```text
+Candidate: Pipeline forecast
+Uses: Assumptions, Historical Pipeline, Forecast
+Inputs: yellow assumptions in Assumptions!B4:B12 (high confidence)
+Outputs: blue forecast summary in Forecast!B3:H10 (medium confidence)
+Historical context: Historical Pipeline!A1:K500
+Question: Confirm that forecast assumptions should be editable?
+```
+
+Mark the strongest recommendation with `recommended: true`, but do not silently
+select it. Let the user select none, one, or several candidates, correct a
+proposed tab/range, or answer the unresolved question. Keep each question to
+2-4 grouped candidate jobs; for a larger workbook, group related tabs into
+jobs rather than showing a tab dump or asking a separate question for every
+worksheet. If there is only one high-confidence candidate, keep the review
+compact and ask for confirmation only when the I/O mapping or source access is
+unclear.
+
+When several candidates are selected, pass a stable candidate ID, display name,
+source worksheet/ranges, I/O mapping, confidence, and confirmation status for
+each. The generated app should expose them as separate named left-navigation
+destinations or tabs, not merge them into an opaque dashboard and not create a
+separate workspace app for every worksheet.
+
+## 4. Confirm before building or publishing
+
+The confirmation view is a source-integrity checkpoint, not a product-design
+questionnaire. Show:
+
+- the source file or spreadsheet ID and snapshot/live choice;
+- selected candidate destinations and their source tabs/ranges;
+- editable inputs, read-only outputs, and static historical context;
+- the evidence and confidence for each mapping;
+- truncation, unreadable, missing-connection, and refresh limitations;
+- the app outputs/actions that will be created.
+
+Use clear actions such as `Confirm and build`, `Edit mapping`, and `Use a
+different source`. If the host has a structured question or multi-select UI,
+use it. Otherwise, ask one concise assistant message that presents the same
+options and requires an explicit confirmation/correction before handoff.
+
+After confirmation, the online host may call
+`start-workspace-app-creation`; the Builder run itself remains autonomous and
+must record any remaining non-blocking assumptions. In a local generated app,
+persist the confirmation state in SQL/application state and keep the user on
+the review surface while the agent builds. Never claim a full import, live
+refresh, or output write until the corresponding source/action has succeeded.
+
+## 5. Failure and recovery states
+
+Keep these states distinct in the review and in the handoff:
+
+- `unreadable` - parser/provider could not read the source;
+- `partial` - only some worksheets, ranges, rows, or pages were read;
+- `truncated` - the bounded preview ended before full coverage;
+- `empty` - the requested readable range contains no values;
+- `not-connected` - authenticated Google access is required but unavailable;
+- `confirmed` - the user approved the candidate and I/O mapping.
+
+For unreadable or not-connected sources, request a CSV/XLSX export or the
+required connection. For partial or truncated sources, continue only with a
+clearly bounded snapshot or ask for a narrower range. Do not coerce any of
+these states into a successful empty source.

package/corpus/templates/mail/.agents/skills/workspace-conventions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: workspace-conventions
+description: >-
+  Shared conventions for a multi-app Agent Native workspace: finding
+  version-matched framework docs and source, shared vs app-owned code, file and
+  blob storage, env and secrets, agent scratch files, and Dispatch Resources.
+  Use when working across workspace apps, storing files or credentials, or
+  looking up framework APIs.
+scope: dev
+---
+
+# Workspace Conventions
+
+The long-form detail behind the workspace `AGENTS.md` core rules. Read this
+before adding shared code, storing files or secrets, creating workspace
+resources, or looking up framework APIs.
+
+## Framework Docs Lookup
+
+Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
+the focused `docs-search` / `source-search` readers, and the `rg` fallback).
+
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. Use package docs for framework APIs,
+the package corpus for reusable framework/template patterns, and this
+`AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.
+
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. Read
+`customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
+
+## Shared Conventions
+
+- All AI/LLM behavior goes through the app's agent chat. UI and server code
+  must not call model providers, AI SDK `generateText()` / `streamText()`, or
+  other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Keep actions deterministic and focused. If a workflow is framed as research,
+  analysis, generation, recommendation, or synthesis, let the agent
+  orchestrate provider/data actions in the open AgentSidebar instead of hiding
+  the work in one opaque action or a separate follow-up textbox.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
+  UI or "AI" features.
+- Put shared code in `packages/shared` only when multiple apps need it.
+- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
+- Store shared runtime configuration in the workspace root `.env`; use
+  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
+  data, or credential-looking literals in source, docs, prompts, fixtures,
+  application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Each app deploys its own `/*` page function, and that function ships whatever
+  the app's server bundle depends on — including a dependency only a background
+  job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,
+  media processing, ML), read `.agents/skills/performance/SKILL.md` §9 and keep
+  that work in a background function or job. A dependency belonging to one app
+  does not belong in `packages/shared`.
+- Prefer framework defaults until the workspace has a real custom rule,
+  component, plugin, action, or skill to share.
+- Keep the Workspace files view for user-authored or user-requested resources.
+  Agents may create hidden `agent_scratch` resources for temporary working
+  notes, scripts, task plans, or intermediate outputs, but should promote them
+  to normal workspace visibility only when the user explicitly asks to keep or
+  manage the file.
+- Runtime-editable global resources can be managed from Dispatch Resources.
+  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
+  every workspace app should inherit them. All-app resources are inherited at
+  runtime; do not copy or sync them into individual apps.
+
+## Related Skills
+
+- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.
+- **agent-native-docs** — The full docs and source-corpus lookup workflow.
+- **agent-native-toolkit** — Inventory of shared workspace and agent UI.
+- **customizing-agent-native** — The configure → compose → eject ladder.
+- **delegate-to-agent** — Routing every AI feature through the agent chat.
+- **performance** — Load cost, and (§9) cold-start artifact size per app.
+- **secrets** — Registering API keys and service credentials.
+- **storing-data** — Where structured data and large payloads belong.

package/corpus/templates/mail/actions/send-email.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
 import { emit } from "@agent-native/core/event-bus";
 import { setOAuthDisplayName } from "@agent-native/core/oauth-tokens";
 import { getRequestUserEmail } from "@agent-native/core/server";
@@ -82,6 +83,12 @@ function buildTrackingContext(
   };
 }
 
+async function signalMailRefresh(): Promise<void> {
+  await writeAppState("refresh-signal", { ts: Date.now() }).catch((error) => {
+    console.error("[send-email] refresh signal failed:", error);
+  });
+}
+
 const attachmentSchema = z.object({
   filename: z
     .string()
@@ -224,6 +231,7 @@ export default defineAction({
             { owner: ownerEmail },
           );
         } catch {}
+        await signalMailRefresh();
         return JSON.stringify(newEmail, null, 2);
       });
     }
@@ -322,6 +330,7 @@ export default defineAction({
       } catch {
         // best-effort — never block the send response
       }
+      await signalMailRefresh();
 
       return `Email sent successfully (id: ${sent.id})`;
     } catch (err: any) {

package/corpus/templates/mail/app/components/layout/AppLayout.tsx

@@ -1054,10 +1054,10 @@ function AppLayoutInner({ children }: AppLayoutProps) {
   };
   const getTopBarCount = (viewId: string) => getTabCount(viewId, "total");
   const getUnreadCount = (viewId: string) => getTabCount(viewId, "unread");
-  const inboxSidebarUnreadCount =
-    labelThreadCounts.unread["__inboxTotal"] ??
-    labelThreadCounts.unread["inbox"] ??
-    0;
+  // The rail badge represents the whole inbox. The top-bar "Other" tab can
+  // only count loaded rows when pinned filters are active, but Gmail's label
+  // count covers the mailbox beyond the current page.
+  const inboxSidebarUnreadCount = getInboxCount("unread");
   const railNavItems = [
     {
       id: "inbox",

package/corpus/templates/mail/changelog/2026-08-12-agent-sent-messages-appear-immediately.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-12
+---
+
+Agent-sent messages appear in Mail immediately after Gmail sends them.

package/corpus/templates/plan/.agents/skills/adding-a-feature/SKILL.md

@@ -101,8 +101,9 @@ placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
 If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
-states, or formatting, read `internationalization` and update the app's i18n
-catalogs in the same change.
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
 
 For app-backed skills, declare skill visibility in the app-skill manifest: