@agent-native/core 0.152.1 → 0.153.1

package/corpus/templates/design/.agents/skills/secrets/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: secrets
+description: >-
+  Declaratively register API keys and service credentials a template needs so
+  they appear in the agent sidebar settings UI and the onboarding checklist.
+  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
+  surfacing OAuth connections in the unified settings UI.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Secrets Registry
+
+## Non-negotiable rule
+
+Never hardcode credential values. Source, docs, tests, fixtures, prompts, seed
+data, and generated extension/app content may mention credential **names** such
+as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
+signing secrets, OAuth refresh tokens, or private Builder/customer data.
+
+Secret values are supplied at runtime through deployment configuration, the
+encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Examples must use obvious placeholders such as
+`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+
+## When to use
+
+Use this for any external credential your template needs: API keys, service
+tokens, webhook secrets. It gives you:
+
+- A sidebar UI entry for each credential (masked input, rotate, test, delete).
+- Automatic onboarding-checklist items for `required: true` secrets.
+- A stable server-side read API (`readAppSecret`) that decrypts values on
+  demand.
+- Validator hooks for health-checking keys before save and from a Test button.
+
+## When NOT to use
+
+- OAuth flows that need to run the full authorization code exchange — use
+  `@agent-native/core/oauth-tokens` directly to save/refresh tokens. The
+  registry can still surface the OAuth connection in the sidebar by
+  registering a secret with `kind: "oauth"` — that just delegates status
+  lookup to oauth-tokens and renders a Connect button, no `app_secrets` row
+  is written.
+- Purely process-level env vars that are never user-facing (e.g. `NODE_ENV`,
+  deployment flags). Those belong in the onboarding `form` method or the
+  `envKeys` list in `core-routes-plugin`.
+
+## Registering a secret
+
+```ts
+// server/plugins/register-secrets.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerRequiredSecret } from "@agent-native/core/secrets";
+
+export default defineNitroPlugin(() => {
+  registerRequiredSecret({
+    key: "OPENAI_API_KEY",
+    label: "OpenAI API Key",
+    description: "Used for Whisper transcription of your recordings.",
+    docsUrl: "https://platform.openai.com/api-keys",
+    scope: "user",
+    kind: "api-key",
+    required: true,
+    validator: async (value) => {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${value}` },
+      });
+      return res.ok
+        ? { ok: true }
+        : { ok: false, error: `OpenAI rejected the key (HTTP ${res.status})` };
+    },
+  });
+});
+```
+
+### OAuth in the unified UI
+
+```ts
+registerRequiredSecret({
+  key: "GOOGLE_CONNECTED",
+  label: "Google account",
+  description: "Grants access to Gmail / Calendar APIs.",
+  scope: "user",
+  kind: "oauth",
+  required: true,
+  oauthProvider: "google", // must match the provider id in oauth-tokens
+  oauthConnectUrl: "/_agent-native/google/auth-url",
+});
+```
+
+The sidebar shows a Connect button instead of a text input; no `app_secrets`
+row is written — status is derived from `hasOAuthTokens("google")`.
+
+## Registered options
+
+| Field              | Type                                    | Purpose                                                                  |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
+| `key`              | `string`                                | Env-var style name (`OPENAI_API_KEY`). Also the storage key.             |
+| `label`            | `string`                                | Human-readable title in the sidebar.                                     |
+| `description`      | `string?`                               | Subtitle under the label.                                                |
+| `docsUrl`          | `string?`                               | "Get key" link rendered on the card.                                     |
+| `scope`            | `"user" \| "workspace"`                 | Per-user or shared across the active org.                                |
+| `kind`             | `"api-key" \| "oauth"`                  | Drives UI and storage behavior.                                          |
+| `required`         | `boolean?`                              | When true, an onboarding step is auto-injected.                          |
+| `validator`        | `(v) => Promise<boolean \| {ok,error}>` | Runs on save and from the Test button. Never log `v`.                    |
+| `oauthProvider`    | `string?` (oauth-kind only)             | Provider id in `oauth-tokens` that backs this entry.                     |
+| `oauthConnectUrl`  | `string?` (oauth-kind only)             | URL the Connect button points at.                                        |
+
+## Reading a secret from an action
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+import { readAppSecret } from "@agent-native/core/secrets";
+import { getRequestUserEmail } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Transcribe an audio file with Whisper",
+  schema: z.object({ fileUrl: z.string() }),
+  run: async ({ fileUrl }) => {
+    const email = await getRequestUserEmail();
+    if (!email) throw new Error("Not signed in");
+
+    const stored = await readAppSecret({
+      key: "OPENAI_API_KEY",
+      scope: "user",
+      scopeId: email,
+    });
+    const apiKey = stored?.value;
+    if (!apiKey) {
+      throw new Error(
+        "OPENAI_API_KEY is not set. Configure it in the sidebar settings.",
+      );
+    }
+
+    // …call OpenAI. NEVER log the key or include it in error messages.
+  },
+});
+```
+
+Rules:
+
+- **Never log the value.** The read layer enforces this server-side; your
+  code must do the same.
+- **Use env vars only for deploy-level secrets.** If a credential is
+  user-scoped, org-scoped, or workspace-scoped, read the scoped vault/credential
+  store. Do not add a `process.env` fallback that makes every user inherit one
+  deployment's key.
+- **Scope matches the registration.** `scope: "user"` → pass the user email.
+  `scope: "workspace"` → pass the active `orgId` from
+  `getOrgContext(event).orgId`.
+- **One resolver per key, and every runtime path goes through it.** Before
+  reading a credential, grep the app for the key name. If a resolver already
+  exists (`resolveXConfig`, a connector, a client factory), call it — do not
+  read `process.env` for that key a second time somewhere else.
+- **Identity comes from the caller, not the module.** A shared helper under
+  `server/lib/` takes the email as a parameter; only an entrypoint (action,
+  route, cron) decides whose identity it is. A library that resolves its own
+  identity from `process.env.AGENT_USER_EMAIL` authorizes the deployment rather
+  than the caller.
+
+The failure this prevents is not a leak — it is a split brain. When the config
+check reads the vault and the feature reads `process.env`, the settings UI and
+onboarding checklist report the integration as **configured** while every actual
+call fails with "env var is required". The credential is right there in the
+vault, so the error names the wrong cause and sends everyone hunting for a sync
+or redeploy problem that does not exist. This has now shipped four times in one
+app (BigQuery, Jira, Pylon, Academy).
+
+Before finishing any change that touches a credential, run the guard from the
+app directory — it finds this whether the app lives in `templates/` or in a
+workspace repo:
+
+```bash
+npx agent-native doctor --only no-env-credentials
+```
+
+## `resolveCredential` sees exactly one organization
+
+`resolveCredential(key, { userEmail, orgId })` checks the user scope, then the
+one `orgId` you pass, then the solo workspace. That is the whole search. It is
+correct for a signed-in request, and wrong for two common cases:
+
+- **The caller has no organization.** A cron, a scheduled job, or any CLI run
+  without a real member identity resolves no `orgId`, so only the user and solo
+  scopes are ever consulted — and a shared key is in neither.
+- **The key was synced under a different organization.** `app_secrets` has no
+  scope visible to every org (`readAppSecret` is strict equality on
+  `(scope, scope_id, key)`), so a key the vault UI advertises as available to
+  every app is unreadable from any org except the one that ran the sync.
+
+Both produce the same misleading "not set" that the split brain above produces,
+which is why swapping `process.env` for `resolveCredential` can look like a fix
+and change nothing. A workspace app should read shared keys through a resolver
+that also sweeps the caller's other memberships and a designated vault org —
+see `resolveConnectorSecret` and `AGENT_VAULT_ORG_ID` in the builder-workspace
+repo for the shape, including the boot-time assertion that the deployment really
+is single-tenant before a non-membership-gated fallback is safe.
+
+**The doctor guard does not catch this second form** — it looks for
+`process.env` reads, and `resolveCredential` is not one. Grep for
+`resolveCredential` yourself and confirm each call sits somewhere a single-org
+lookup is genuinely the right question. Findings that pair it with a
+`?? process.env.KEY` fallback are the sanctioned deploy-level escape hatch; the
+bugs are calls whose value can only live in another org's vault.
+
+## HTTP routes
+
+Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
+
+- `GET /_agent-native/secrets` — list registered secrets with status (`set`
+  / `unset` / `invalid`), metadata, and — for set api-keys — the last 4
+  characters. Values are never returned.
+- `POST /_agent-native/secrets/:key` — body `{ value, scope?, scopeId? }`.
+  Runs the registered validator; returns 400 with the error on failure.
+- `DELETE /_agent-native/secrets/:key` — remove the stored value.
+- `POST /_agent-native/secrets/:key/test` — re-run the validator against the
+  currently stored value.
+
+## Storage & encryption
+
+- Values are stored in `app_secrets` (created on-demand; no migration
+  needed).
+- Values are encrypted at rest with AES-256-GCM. Generic app-local secrets
+  prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
+  `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
+  `BETTER_AUTH_SECRET`.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
+- If no configured key material exists, development uses a machine-local
+  fallback and logs a one-time warning. Production fails closed.
+
+## Ad-hoc Keys
+
+Ad-hoc keys are user-created secrets that are not declared by the template.
+Users create them through the settings UI or the agent chat to use with
+automations and the `web-request` tool. They support `${keys.NAME}`
+substitution in outbound HTTP requests.
+
+### Ad-hoc API
+
+Core routes plugin mounts these under `/_agent-native/secrets/adhoc`:
+
+- `GET /_agent-native/secrets/adhoc` — list all ad-hoc keys (name, last 4
+  chars, URL allowlist). Values are never returned.
+- `POST /_agent-native/secrets/adhoc` — body `{ name, value, urlAllowlist? }`.
+  Creates or updates an ad-hoc key.
+- `DELETE /_agent-native/secrets/adhoc/:name` — remove an ad-hoc key.
+
+### URL Allowlists
+
+Each ad-hoc key can have a URL allowlist — an array of origin URLs that
+restrict where the key's value can be sent. The check is origin-level
+(scheme + host + port). If no allowlist is configured, the key can be used
+with any URL.
+
+```ts
+// Creating a key with an allowlist
+POST /_agent-native/secrets/adhoc
+{
+  "name": "SLACK_WEBHOOK",
+  "value": "<SLACK_WEBHOOK_URL_FROM_SETTINGS>",
+  "urlAllowlist": ["https://hooks.slack.com"]
+}
+```
+
+### `${keys.NAME}` Substitution
+
+The `web-request` tool supports `${keys.NAME}` placeholders in the URL,
+headers, and body. Substitution happens server-side after the agent emits
+the tool call — the raw secret value never enters the agent's context.
+
+```ts
+import {
+  resolveKeyReferences,
+  validateUrlAllowlist,
+} from "@agent-native/core/secrets/substitution";
+
+// Resolve all ${keys.NAME} references in a string
+const { resolved, usedKeys } = await resolveKeyReferences(
+  "Bearer ${keys.API_TOKEN}",
+  "user",
+  "user@example.com",
+);
+
+// Validate a URL against a key's allowlist
+const allowed = validateUrlAllowlist(
+  "https://hooks.slack.com/services/<WORKSPACE>/<CHANNEL>/<SECRET>",
+  ["https://hooks.slack.com"],
+);
+```
+
+Key resolution falls back from user scope to workspace scope, so users can
+override shared keys without breaking automations that reference workspace
+defaults.
+
+## Dispatch Vault Access
+
+Dispatch workspaces have a vault access policy for workspace app credentials:
+
+- `all-apps` is the default. Every saved Dispatch vault key is available to
+  every workspace app; `sync-vault-to-app` pushes all vault keys to the target
+  app.
+- `manual` requires explicit per-app grants. Use
+  `create-vault-grant` / `grant-vault-secrets-to-app`, then
+  `sync-vault-to-app`.
+
+Use `get-vault-access-settings` before deciding whether to create grants, and
+use `set-vault-access-settings` only when the user asks to change the policy.
+
+### Key Files (ad-hoc)
+
+| File                                           | Purpose                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()`, `validateUrlAllowlist()` |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool consuming key references |
+
+## Related skills
+
+- `onboarding` — the setup checklist that required secrets show up in.
+- `actions` — where you'll read secrets when calling third-party APIs.
+- `authentication` — session scoping; `scope: "user"` uses the session
+  email.
+- `security` — input validation and never logging secrets.
+- `automations` — ad-hoc keys power `${keys.NAME}` in automation web requests.

package/corpus/templates/design/.agents/skills/self-modifying-code/SKILL.md

@@ -90,9 +90,9 @@ el.dataset.selectedId = selectedItem?.id || "";
 **Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
 
 **Keep localized copy in catalogs** — When editing visible UI copy, labels,
-toasts, empty states, prompts, or formatting, read `internationalization` and
-update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
-inline strings in components.
+toasts, empty states, prompts, or formatting, update the English source catalog.
+Read the optional `internationalization` skill and update additional catalogs
+only when `translations.locales` in `agent-native.config.ts` includes them.
 
 ## Don't
 

package/corpus/templates/design/.agents/skills/shadcn-ui/SKILL.md

@@ -60,7 +60,7 @@ behavior comes from the company design system.
 ## Component Composition
 
 - Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
-- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Leave `CardDescription` out: a card gets a title or a description, never both. See `frontend-design` → Default Surface Density.
 - Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
 - Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
 - `TabsTrigger` belongs inside `TabsList`.

package/corpus/templates/design/.agents/skills/sharing/SKILL.md

@@ -31,6 +31,7 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 ### Roles on a share grant
 
 - **`viewer`** — read only.
+- **`commenter`** — read + add comments, but cannot edit the resource or manage shares.
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 

package/corpus/templates/design/.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/design/.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: