@agent-native/core 0.152.1 → 0.153.1

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

@@ -0,0 +1,123 @@
+---
+name: self-modifying-code
+description: >-
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Self-Modifying Code
+
+## Rule
+
+The agent can edit the app's own source code — components, routes, styles, scripts. This is a feature, not a bug. Design your app expecting this.
+
+## Why
+
+An agent-native app isn't just an app the agent can _use_ — it's an app the agent can _change_. The agent can fix bugs, add features, adjust styles, and restructure code. This makes the agent a true collaborator, not just an operator.
+
+## Modification Taxonomy
+
+Not all modifications are equal. Use this to decide what level of care is needed:
+
+| Tier          | What                  | Examples                                         | After modifying                   |
+| ------------- | --------------------- | ------------------------------------------------ | --------------------------------- |
+| 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
+| 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
+| 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- `pnpm patch`, `pnpm patch-commit`, or local package patch artifacts for any
+  dependency
+- Invented "dispatch/core behavior" shims meant to paper over a version skew
+  or failed upgrade
+
+This does not prohibit intentional app-owned UI customization. When public
+props and composition are insufficient, the `customizing-agent-native` skill
+uses `agent-native eject` to transfer the smallest supported unit from the
+installed package into the app. The ejected unit must keep public runtime
+contracts and must not replace Core auth, DB, actions, agent execution, or
+transport behavior. Manual copying is only the fallback described by an unknown
+third-party package's add-style blueprint.
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
+
+## Git Checkpoint Pattern
+
+Before modifying source code (Tier 2+), create a rollback point:
+
+1. Commit or stash current state
+2. Make the edit
+3. Run `pnpm typecheck && pnpm lint`
+4. If verification fails → revert with `git checkout -- <file>`
+5. If verification passes → continue
+
+This ensures the agent can experiment without breaking the app.
+
+## Designing for Agent Editability
+
+Make your app easy for the agent to understand and modify:
+
+**Expose UI state via `data-*` attributes** so the agent knows what's selected:
+
+```ts
+const el = document.documentElement;
+el.dataset.currentView = view;
+el.dataset.selectedId = selectedItem?.id || "";
+```
+
+**Expose richer context via `window.__appState`** for complex state:
+
+```ts
+(window as any).__appState = {
+  selectedId: id,
+  currentLayout: layout,
+  itemCount: items.length,
+};
+```
+
+**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, 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
+
+- Don't modify `.env` files or files containing secrets
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't confuse readable package source with app-owned code: use
+  `customizing-agent-native` and `agent-native eject` for supported ownership
+  transfer
+- Don't use `pnpm patch` / `pnpm patch-commit`, commit `patches/` artifacts, or
+  add `pnpm.patchedDependencies` to "make the app run" after a version bump
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to paper over a broken upgrade
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
+- Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
+- Don't skip the typecheck/lint step after editing source code
+- Don't make source changes without a git checkpoint to roll back to
+
+## Related Skills
+
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
+- **customizing-agent-native** — configure, compose, or eject installed features safely
+- **storing-data** — Tier 1 modifications (data files) are the safest and most common
+- **actions** — The agent can create or modify actions to add new capabilities
+- **delegate-to-agent** — Self-modification requests come through the agent chat
+- **real-time-sync** — Database writes trigger change events to update the UI
+- **internationalization** — UI copy, language catalogs, locale switching, and RTL-safe edits

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

@@ -0,0 +1,123 @@
+---
+name: shadcn-ui
+description: >-
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
+scope: dev
+source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
+metadata:
+  internal: true
+---
+
+# shadcn/ui
+
+This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
+
+## First Steps
+
+1. Work from the app root that owns `components.json`.
+2. In an Agent Native app, inspect `app/design-system.ts` and
+   `ToolkitProvider` before choosing a primitive. A registered company design
+   system takes precedence over the default shadcn adapter.
+3. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+4. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## Agent Native Adapter Rule
+
+Pages, routes, and domain components import controls through the app's local UI
+adapter layer. Never import `@agent-native/toolkit/ui/*` directly in app product
+code. Direct imports bypass `app/design-system.ts` and make Toolkit/Core
+surfaces use different controls from the app.
+
+When shadcn is the app's adapter, add or update the local primitive and keep
+product code on that local import. When a company design system is registered,
+adapt its components to the semantic contracts from
+`@agent-native/toolkit/design-system`; do not recreate a parallel shadcn
+surface. The semantic API is styling-runtime agnostic, so do not require
+Tailwind, CVA, or `className` in customer adapters.
+
+For shared Toolkit features, customize presentation through semantic
+components, a feature-level controller, and product-level render slots. Keep
+the same controller for default and custom views. Use the conformance kit for
+behavior components whose focus, portal, keyboard, dismissal, or stacking
+behavior comes from the company design system.
+
+## Adding Or Updating Components
+
+- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
+- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
+- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
+- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
+- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
+
+## 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.
+- 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`.
+- `Avatar` always needs `AvatarFallback`.
+- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
+
+## Forms And Inputs
+
+- Use the app's shadcn form primitives instead of raw div stacks.
+- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
+- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
+- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
+- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
+
+## Styling And Theming
+
+- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
+- Prefer built-in variants and sizes before custom classes.
+- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
+- Use `gap-*` instead of `space-x-*` / `space-y-*`.
+- Use `size-*` when width and height are equal.
+- Use `truncate` for single-line clipping.
+- Use `cn()` for conditional classes.
+- Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
+- Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
+
+## Transitions And Motion
+
+shadcn's built-in component animations are the right level of polish — keep them. The goal is a snappy, clean UI, not a motionless one. Match shadcn's motion vocabulary; don't strip it and don't pile on decorative custom animation.
+
+- **Never remove or override a shadcn component's default animation.** `data-[state=open]:animate-in`, `data-[state=closed]:animate-out`, `fade-in/out`, `zoom-in/out`, `slide-in-from-*`, accordion height, the `tailwindcss-animate` utilities — these ship for a reason. Leave them as-is.
+- **Custom transitions are fine when they communicate a state change and match shadcn's feel.** Reuse the same vocabulary: short durations (~120–200ms), `ease-out`, opacity/transform only, gated on `data-[state=...]`. Examples that are good and welcome:
+  - A portaled custom popover/tooltip/sheet that fades + scales/slides in on `data-[state=delayed-open]` / `data-[state=closed]`, mirroring Radix's own content animation.
+  - A list row or toast that fades/slides in on mount and out on dismiss.
+  - A chevron/caret `rotate` on expand, a subtle `opacity`/`color` hover on an icon button, skeleton shimmer, a progress/height transition on a collapsible.
+  - Continuous, product-defining motion where it _is_ the experience (e.g. a multi-stage booking flow's stage transitions) — fine, and framer-motion is acceptable there.
+- **Avoid decorative, attention-seeking, or slow motion:** hand-rolled `duration-700` hero fade-ins, parallax, bouncing/spring entrances on ordinary content, animated gradients, staggered cascades on long lists, anything that delays the user seeing or acting on content. If an animation makes the UI feel slower, cut it.
+- Rule of thumb: if the motion clarifies what just changed and is over in well under a quarter-second, it's polish; if it's there to look impressive, it's bloat.
+
+## Icons
+
+- Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.
+- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
+- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
+
+## Base-Specific APIs
+
+Check the project context before using trigger composition APIs:
+
+- Radix-based components use `asChild` for custom triggers.
+- Base UI components may use `render` and sometimes `nativeButton={false}`.
+
+Do not wrap triggers in extra divs just to place a Button or Link inside them.
+
+## Related Skills
+
+- **frontend-design** — Product UX, visual direction, responsive polish, and verification
+- **customizing-agent-native** — Registered design systems, controllers, slots, conformance, and ejection
+- **actions** — Data fetching and mutation patterns for agent-native apps
+- **security** — User data, forms, external input, and action safety

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