shared/native-interactions.md

# Data onboarding interactions

Use Visualize for workflow buttons and shared [task intake](task-intake.md) for best-effort delivery, async questions, and the narrow blocking scenarios. Native `form_elicitation_v2_request` blocks; optional fields do not change that. Keep installation and sign-in in native Plugin Management. Shared Answers Platform GenUI remains a workflow-button fallback only on capable hosts. Choose by the interaction’s purpose:

| Interaction                                          | Component or supported entry point  | Result                                                                                                                             |
| ---------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Choose a first workflow or next task                 | Visualize                           | Offers buttons that send a complete follow-up prompt through the host's confirmation flow.                                         |
| Ask a useful clarification | Shared task-intake route | Prefers async input while work continues; uses a blocking form only for the explicit shared scenarios. |
| Choose a template when requested | Rich resource picker | Uses `resource`/`resources`, not async or plain-choice questions; follows [context gathering](context-gathering.md#templates-and-prior-work). |
| Choose plugins to install or connect                 | Plugin Management `suggest_plugins` | Presents eligible providers together in the native multi-plugin connection UI; the host owns selection, installation, and sign-in. |

Use the active Visualize skill and its supported output surface; do not infer support from this template's presence in Data. For GenUI, runtime widget-directory results or explicit host capability instructions establish support; bundled helper skills alone do not. If the host exposes GenUI discovery and support is unknown, make a bounded lookup for the needed component and follow the returned contract. Do not emit unsupported widget references or describe Visualize or question tools as GenUI. The app name alone does not establish either capability.

## Workflow suggestions

For open-ended onboarding, follow the onboarding skill's short overview and sample dashboard/report links, then render **Connect my data**, **Understand what changed**, and **Build a dashboard or report** with Visualize. After a completed connection, show only the latter two choices. Open native connection cards after the user chooses the connection route or requests a source needed by a selected workflow; the welcome samples need no connection. Invite a custom question and do not add a Skip button.

If Visualize is unavailable, use supported `follow_up_pill_group` buttons. Otherwise offer the prompts in chat and end the turn. Keep question tools for the follow-up intake below. A submitted option or free-text question selects the workflow; an explicit typed skip ends setup, while dismissal leaves the choice unresolved.

Do not start a workflow because an option is preselected, a timer expires, or an optional question returns no answer. A missing answer leaves the task unselected; invite a typed choice without repeating the picker. An explicit **Skip set up** response follows the onboarding skill's skip behavior. Once a workflow is selected, continue it rather than asking the same choice again.

The `codex-followup` directive is not the opening workflow selector. Some desktop builds advertise its syntax while a separate renderer experiment displays the labels as plain text; when enabled, its artifact links prefill a draft rather than submit a selected workflow. Neither formatting instructions nor a directive's presence in plugin files establish interactive support.

### Visualize option selector

Read the active Visualize skill (`visualize:visualize` or the system `visualize` skill) in full before creating or updating a selector, then read the [Figma design references](../skills/onboarding/references/visualize-design.md). Copy the bundled [workflow selector](../skills/onboarding/assets/workflow-selector.html) into an explicitly writable, durable task-owned visualization location. Preserve its design-specific scaffold and scoped styles; the workflow selector is a vertical stack of icon pills, not generic horizontal chips. Personalize the visible labels, accessible names, typed fallback, and complete prompts for the current conversation. Use a distinct root ID for each selector. Follow the active skill's fragment and delivery contract; emit the actual `visualize` content reference in the final response, then end the turn. A code fence, downloadable HTML link, or promise of buttons does not deliver the selector.

Each workflow button calls `await window.openai.sendFollowUpMessage({ prompt, title })`. The prompt must name the chosen workflow and include useful known task context in a concise user-facing request. Do not put internal onboarding or tool-routing instructions in the message. The host owns confirmation. Do not bypass it, infer submission from promise resolution, or show a selection as accepted before the resulting user message arrives. Keep the controls usable after cancellation or failure, and prevent duplicate calls while confirmation is pending. A missing bridge must leave a clear typed-response fallback.

Never start a workflow on render, restore, timeout, preselection, or `setWidgetState`. Widget state is optional presentation state, not a submitted answer or authorization. Keep all information needed to continue in the follow-up prompt; state delivery to the model is best-effort. Canceling confirmation leaves setup unresolved. Honor typed requests to stop or skip setup. The selector does not install plugins, authenticate, open a file picker, query sources, publish, or schedule work.

For one optional next task, retain one workflow-style pill and remove the opening workflow controls. Do not redisplay the opening menu. Use the shared task-intake route for unresolved details or explicitly requested choices.

### Shared follow-up component

When Visualize is unavailable and `follow_up_pill_group` is explicitly supported, read the bundled [Answers follow-up skill](../skills/answers-follow-up/SKILL.md) and render it inline in the final response. Each group contains one to three actions with unique `id`, visible `label`, and a complete `query` sent as the next user message. Preserve the same opening connection action and two workflows, or the two workflows after connection. The same component can suggest a next step after a completed workflow; it is not onboarding-specific.

The inline invocation has this shape; replace the example with the actual suggestions and emit it without a code fence:

```text
genui{"follow_up_pill_group":{"actions":[{"id":"connect_data","label":"Connect my data","query":"Help me connect my data sources to Data."},{"id":"investigate_change","label":"Understand what changed","query":"Help me investigate a metric change. Reuse any metric, comparison, and source I have already provided."},{"id":"create_artifact","label":"Build a dashboard or report","query":"Help me create a report or dashboard. Reuse the context I have provided and ask only for essential information you cannot recover."}]}}
```

Omit optional icon and source fields unless the active widget instructions supply appropriate values. Rendering a suggestion does not select it, start the analysis, grant source access, or authorize an external action. Wait for the resulting user message before doing work dependent on that choice. A custom typed question is equally valid.

Prefer the active host contract when it differs from these examples. These buttons use `inline_run`: emit the complete invocation directly in the final response, without an extra rendering tool call or a fabricated widget UUID. Rendering ends the turn; wait for the resulting user request.

## Structured intake

**Connect my data** goes directly to [App connections](#app-connections), including when no provider is named. After an analytical workflow is selected, use [task intake](task-intake.md) for input tools and the best-effort/async/blocking policy; a workflow choice does not require a setup form.

Read the [native form guide](../mcp/forms/README.md) only when that route requires a form. Keep Visualize for workflow suggestions; do not recreate the native intake controls in it. Source-file selections return identities, not uploaded bytes, so a remote task may need the host's attachment path.

## App connections

Read [source setup and access recovery](source-setup.md) for discovery, eligibility, and connection state. Once the user chooses **Connect my data**, make a bounded discovery pass and present the eligible options directly through native Plugin Management `suggest_plugins`. Provider selection belongs in this multi-plugin connection UI, even when the desired provider is unknown; do not put a `request_user_input` or other provider questionnaire in front of it. Workflow intake can still ask which dataset, file, or existing source an analysis should use.

Collect exact eligible IDs or supported marketplace references first, then call `suggest_plugins` once with the selected set in one `plugin_ids` array. For open-ended onboarding, aim for **ten relevant providers**, discovering and ordering suitable **Data Warehouse** integrations before other categories. Fill remaining slots with relevant BI, product analytics, business systems, or file sources. Follow the [onboarding discovery and ranking policy](../skills/onboarding/SKILL.md#connect-my-data), including using popularity metadata only when supplied and preferring production connectors to demo/test integrations. Use this onboarding-specific count instead of the shared general-workflow limit; do not make one call per provider. Honor the live tool's limits, including any smaller enforced batch size, exclude installed and pending plugins, and reuse existing useful connections. Offer fewer only when relevance, the user's explicit source scope, eligibility, or the service limit warrants it; do not add irrelevant options to reach ten. If none are eligible, preserve pending setup or explain the available connections or discovery limitation rather than rendering an empty offer or falling back to a provider questionnaire. Use the shared [older-client fallback](source-setup.md#older-clients-and-unresolved-access) if the suggestion tool is unavailable.

Present the list as starting suggestions. Always tell the user they can browse all available connectors in the **Plugins tab** or request a specific connector in chat, including when the offer contains fewer than ten providers or none. Discover a named connector through focused search and use the same native connection flow without restarting onboarding or discarding the selected workflow.

The host renders multiple suggestions as grouped connection cards with an installation or connection action for each provider. This is the supported plugin connection UI, not a blocking question form or a model-authored GenUI reference; do not recreate it in Visualize or use workflow prompts to impersonate **Connect** actions. Suggestions are non-blocking: a tool return does not mean the user selected or connected a provider. Continue independent work, or yield for setup when nothing else can proceed; do not immediately follow the connection UI with workflow intake while its connection choice remains unresolved.

The platform's `onboarding_plugin_suggestions` and `onboarding_starter_tasks` widgets are server-authored flow components, not model-callable substitutes for these entry points. They require trusted onboarding state supplied by their owning flow. Do not fabricate flow identifiers, experiment arms, connection states, or widget invocations to make them appear available. Plugin installation and sign-in belong to the host's supported controls.

Only claim organization-specific ranking when returned metadata establishes it. The host owns installation, connection controls, and their displayed states. Pending suggestions, completed installation, and verified access are distinct. After connection, refresh relevant tool discovery and let the first necessary read verify the operation needed by the selected task; continue that task without restarting onboarding.

## After the first result

Use Visualize for one concrete next step supported by the completed answer or artifact, following the same support check and confirmed follow-up contract as the opening selector. If unavailable, use supported `follow_up_pill_group` or describe the optional next step in prose. A `codex-followup` artifact link is a draft suggestion, not a submitted task. Carry the artifact's identity and relevant context into the prompt. Do not offer work already completed, imply unverified findings, or create a scheduled job merely by displaying its suggestion.

For an eligible onboarding report/dashboard, briefly explain that automatic refresh uses a cloud task. Use a contextual label such as **Keep this dashboard up to date** and a prompt asking to create a cloud task for recurring refresh of that exact artifact. Include a cadence only if the user already supplied it. Route the resulting user request to `$schedule-refresh-jobs`, which collects missing schedule details and verifies creation. Prefilling a draft does not submit that request. Other repeatable analyses use the index's **Suggest Automations** contract, including its supported launcher and eligibility rules, rather than a second generic follow-up.