create-yss-spec 3.4.7 → 3.4.9

package/template/.codex/skills/data-analytics/skills/user-context/SKILL.md

@@ -11,12 +11,12 @@ This skill is the Data Analytics plugin's source-routing, semantic-layer registr
 
 - For ordinary Data Analytics preflight, use `scripts/data_analytics_preflight.py` as the default state-read path when local shell access is available.
 - Apply the same gate on behalf of other Data Analytics skills that call `data-analytics:user-context` as part of their own mandatory preflight before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output.
-- When running the preflight script through a command tool, set the tool's `max_output_tokens` to at least `25000` so the complete payload remains visible as the registry grows. If the tool output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not use the payload until the complete output is visible.
-- Treat the script payload as satisfying the read requirement only when it reports read status for `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md` and renders the compact context it will use in `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, and `control`.
+- When running the preflight script through a command tool, choose an output budget that renders the compact payload completely; there is no fixed minimum token allocation. If the tool output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not use the payload until the complete output is visible.
+- Treat the script payload as satisfying the read requirement only when it reports read status for `$CODEX_HOME/state/plugins/data-analytics/user-context.md` and renders the compact context it will use in `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, and `control`.
 - Do not treat listing files, checking that files exist, or saying they should be read as sufficient; source-routing preferences, semantic-layer pointers, source category mapping, and onboarding obligations must be loaded and applied.
 - If the script fails, cannot render the compact Data Analytics context the workflow will use, local shell access is unavailable, or the request is direct context maintenance, actually read the relevant state files manually before answering or writing.
 - If the user-context file is absent or unavailable, follow `references/onboarding.md` for first-run behavior.
-- Read `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json` only when onboarding state, semantic-layer refresh setup, hero prompt progress, or progressive nudges are relevant.
+- Read `$CODEX_HOME/state/plugins/data-analytics/onboarding-state.json` only when onboarding state, semantic-layer refresh setup, hero prompt progress, or progressive nudges are relevant.
 
 ## Skill Configuration
 
@@ -41,7 +41,7 @@ Use this skill as the fast preflight for every substantive Data Analytics workfl
 `SKILL.md` owns the normal preflight, direct read, narrow write, onboarding handoff, and first-run setup path. Load references selectively:
 
 - Use `scripts/data_analytics_preflight.py` as the normal read-only preflight implementation when local shell access is available. Its JSON payload owns Data Analytics state-file read status, compact user-context normalization, source-routing preferences, source category configuration, connector confirmation and setup summary, semantic-layer registry, hero prompt candidates, file provenance, onboarding progress, and final response obligations for ordinary workflows.
-- Keep first-run state creation automated through `scripts/init_user_context_state.py`; it copies the bundled templates into the user's Data Analytics state directory. Do not run it before the first direct onboarding orientation when no state exists. Run it after the user approves the first setup step, or when an explicit future source-routing choice or semantic-layer registry pointer needs persistence. When running through a sandboxed local shell, request elevated execution by default because the initializer writes under `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}`, outside the project workspace. After initialization, write only the narrow supported `user-context.md` fields and related JSON state files.
+- Keep first-run state creation automated through `scripts/init_user_context_state.py`; it copies the bundled templates into the user's Data Analytics state directory. Do not run it before the first direct onboarding orientation when no state exists. Run it after the user approves the first setup step, or when an explicit future source-routing choice or semantic-layer registry pointer needs persistence. Use the permissions actually provided by the host; request additional access only if the authorized narrow write is blocked. Do not assume elevation is required or available. After initialization, write only the narrow supported `user-context.md` fields and related JSON state files.
 - Use `scripts/reset_user_context_state.py` for explicit debugging reset requests that clear local Data Analytics user-context and onboarding state. The helper backs up known state files before removing them from the active state directory.
 - Use `references/onboarding.md` when first-run orientation, core source setup confirmation, semantic-layer setup, semantic-layer refresh setup, semantic-layer weekly source polling setup, hero prompt sequencing, onboarding completion, onboarding status, Data Analytics TODOs, walkthroughs, environment conflict audit, or onboarding-state updates are active.
 - Use `references/semantic-layer/setup.md` when onboarding, direct setup, or maintenance work needs to create, refresh, inspect, or repair a semantic layer. Use `references/semantic-layer/source-intake.md` for seed-source intake and source inventory shaping, `references/semantic-layer/connector-playbook.md` for semantic-layer source-lane connector behavior, and `references/semantic-layer/skill-template.md` for the generated semantic-layer skill shape.
@@ -69,18 +69,20 @@ When `data_analytics_preflight.py` reports hero prompt candidates and onboarding
 
 ## State Files
 
+Resolve the state directory exactly as the script does: explicit `--state-dir`, otherwise resolved `CODEX_HOME` (fallback `~/.codex`) plus `state/plugins/data-analytics`. Invoke scripts from the resolved skill directory or use its absolute path. This is a path clarification, not an instruction to migrate, reset or clean existing state.
+
 Ordinary workflow preflight should read these files through `scripts/data_analytics_preflight.py`; direct context maintenance and fallback paths may read them manually when the script is unavailable or insufficient.
 
 The configured user-context file is:
 
 ```text
-$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md
+$CODEX_HOME/state/plugins/data-analytics/user-context.md
 ```
 
 The configured onboarding-state file is JSON:
 
 ```text
-$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json
+$CODEX_HOME/state/plugins/data-analytics/onboarding-state.json
 ```
 
 ## Read
@@ -91,7 +93,7 @@ Treat `user-context.md` as the local Data Analytics plugin-scoped source of trut
 
 Use preflight mode when another Data Analytics skill asks for Data Analytics setup context before ordinary plugin work. Optimize this path for speed:
 
-- When local shell access is available, run `python3 plugins/data-analytics/skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill>` from the repository root, or `python3 skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill>` from the Data Analytics plugin root. When using a command tool, set `max_output_tokens` to at least `25000`; if the returned output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not treat preflight as complete until the full output is visible. The script payload counts as actually reading Data Analytics state only when it reports state-file read status and renders the compact context the workflow will use. Use the payload as the single source of truth for `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, hard `control.final_obligations`, `control.conditional_guidance`, and `control.onboarding_progress.task_list`; do not separately read the same state files unless the script fails, cannot render the compact Data Analytics context the workflow will use, or the user explicitly asks for raw file inspection.
+- When local shell access is available, run `python3 .codex/skills/data-analytics/skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill>` from the repository root, or `python3 skills/user-context/scripts/data_analytics_preflight.py --workflow <calling-skill>` from the Data Analytics plugin root. When using a command tool, size the output budget to the compact payload; if the returned output is truncated, warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass, then rerun with a higher cap and do not treat preflight as complete until the full output is visible. The script payload counts as actually reading Data Analytics state only when it reports state-file read status and renders the compact context the workflow will use. Use the payload as the single source of truth for `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, applicable `control.final_obligations` (respect each `only_when` condition), `control.conditional_guidance`, and `control.onboarding_progress.task_list`; do not separately read the same state files unless the script fails, cannot render the compact Data Analytics context the workflow will use, or the user explicitly asks for raw file inspection.
 - Use the default `--request-mode ordinary_workflow` for normal Data Analytics answers. Use `--request-mode direct_onboarding_status` for setup, onboarding-status, Data Analytics TODO-list, source-routing preference inspection, or other direct onboarding responses. Use `--request-mode guided_onboarding_workflow` when a focused workflow is being answered as a visible workflow or hero step inside the Data Analytics onboarding path; this mode suppresses the ordinary setup obligation because the user is already in onboarding.
 - Use `context.source_preferences` as source-selection hints. Do not proactively check connector readiness during ordinary preflight. When onboarding or a focused workflow needs a source, it should try the relevant connector then and handle auth, connection, skip, defer, or manual fallback in that context.
 - Use `context.semantic_layers` as the semantic-layer registry. If the request names or implies a product area, metric, table, dashboard, SQL query, source choice, join, caveat, or recurring business question and a matching semantic layer exists, load that semantic-layer skill before choosing tables, writing SQL, reconciling dashboards, or giving metric definitions.
@@ -100,14 +102,14 @@ Use preflight mode when another Data Analytics skill asks for Data Analytics set
 - If `onboarding-state.json` exists, parse only the relevant fields for whether onboarding is active, quiet, complete, whether core onboarding is complete, and any concrete next actions. Do not echo raw onboarding-state content into ordinary preflight output; use file provenance plus the normalized onboarding, source, semantic-layer, and hero-prompt fields the script returns. During ordinary preflight, return at most one concrete guided next step that the calling skill may append after answering the immediate request. If core onboarding is still incomplete, the next step should direct the user back to the next unresolved core setup item: source setup confirmation or semantic-layer setup. During direct onboarding, setup-status answers, or user requests for the Data Analytics TODO list, use `references/onboarding.md` to render the single visible compact `**Next Step**` block and mirror the compact high-level roadmap into the built-in thread task list when available.
 - Treat `context.connector_setup_summary.unresolved_core_ids` and `context.connector_setup_summary.next_action` as authoritative during onboarding. Do not advance into semantic-layer setup because a core source entry merely says `deferred`, `skipped`, `declined`, `unavailable`, or `not_applicable`; preflight reopens that source as `needs_confirmation` unless onboarding state records the user's explicit known-gap resolution.
 - Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source category configuration, connector setup summary, semantic-layer registry, primary hero prompt, extra hero prompt candidates, onboarding progress, final obligations, and conditional guidance. Treat saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources.
-- If `user-context.md` is missing, read `references/onboarding.md`, return that no durable Data Analytics source-routing preferences or semantic-layer registry are available, use the script-driven payload or documented manual fallback to provide conditional setup guidance, and let the caller continue. Do not run the initializer or scaffold state merely because the file is missing. Do not interrupt ordinary plugin work with setup or stop at a setup request. For a high-intent first-run workflow request, tell the caller to answer the user's concrete query first using bundled instructions, user-provided material, and available connectors or sources; if the requested artifact cannot be completed or is meaningfully weaker because a source or semantic layer is missing, give the best truthful answer from the attempted sources and name the practical gap using `references/onboarding.md#context-gap-note`. Append the ordinary-workflow setup obligation only when preflight returns it because onboarding has not started; do not offer to start onboarding when `onboarding-state.json` already says onboarding is active.
+- If `user-context.md` is missing, read `references/onboarding.md`, return that no durable Data Analytics source-routing preferences or semantic-layer registry are available, use the script-driven payload or documented manual fallback to provide conditional setup guidance, and let the caller continue. Do not run the initializer or scaffold state merely because the file is missing. Do not interrupt ordinary plugin work with setup or stop at a setup request. For a high-intent first-run workflow request, tell the caller to answer the user's concrete query first using bundled instructions, user-provided material, and available connectors or sources; if the requested artifact cannot be completed or is meaningfully weaker because a source or semantic layer is missing, give the best truthful answer from the attempted sources and name the practical gap using `references/onboarding.md#context-gap-note`. Append a returned setup suggestion only when its `only_when` condition is met because missing setup materially affects this requested output; do not offer to start onboarding when `onboarding-state.json` already says onboarding is active.
 - If a referenced source is inaccessible, stale, ambiguous, or missing, say that directly only when the missing source affects the current task, then continue with the available context.
 
 ### Script-Driven Preflight Payload
 
-Preflight mode must use `scripts/data_analytics_preflight.py` as the authoritative payload before ordinary work continues. The script output owns `request_mode`, `current_skill_experience`, `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, `control.response_mode`, hard `control.final_obligations`, `control.conditional_guidance`, and `control.onboarding_progress.task_list`. Do not hand-author, recreate, or mentally reconstruct the payload when the script is available; use the JSON fields the script returned.
+Preflight mode must use `scripts/data_analytics_preflight.py` as the authoritative payload before ordinary work continues. The script output owns `request_mode`, `current_skill_experience`, `context.user_context`, `context.source_preferences`, `context.source_category_config`, `context.connector_confirmation`, `context.connector_setup_summary`, `context.semantic_layers`, `context.hero_prompt_candidates`, `context.primary_hero_prompt`, `context.extra_hero_prompt_candidates`, `control.response_mode`, applicable `control.final_obligations` (respect each `only_when` condition), `control.conditional_guidance`, and `control.onboarding_progress.task_list`. Do not hand-author, recreate, or mentally reconstruct the payload when the script is available; use the JSON fields the script returned.
 
-For ordinary Data Analytics workflow requests, honor `control.final_obligations` exactly as returned by the script. The calling skill must answer the immediate request first, then satisfy any returned setup CTA or core-onboarding reminder. When the focused skill does not otherwise own a final continuation, append the returned template intact. When the focused skill has its own final continuation, fold the setup reminder or move-on path into that same final natural continuation so the response has one final visible CTA, not a standalone setup reminder plus a second skill CTA. Do not downgrade a hard obligation into a passive setup aside or a context-gap explanation. Do not use that hard obligation for direct onboarding/setup/status responses, focused workflows launched from the visible onboarding path, or responses where the immediate workflow must ask a required clarification; those callers should use `direct_onboarding_status` or `guided_onboarding_workflow` request mode when appropriate, and clarification-only responses should end with the clarification as the sole final natural continuation.
+For ordinary workflows, apply each `control.final_obligations` item only when its `only_when` condition holds. Answer the immediate request first. Missing saved setup alone never forces a setup CTA after a complete inline/local answer. If missing setup materially blocks this task, name the practical gap and at most one relevant next step. Explicit onboarding/status requests use their own request mode and may show setup steps. Never initialize, migrate, reset or write durable state during ordinary read-only preflight.
 
 When the script fails, cannot render the compact Data Analytics context the workflow will use, or local shell access is unavailable, fall back to the manual file-read path described above: actually read the relevant state files, use only fields known from those files or the missing-file condition, apply `references/onboarding.md` for direct onboarding/status behavior, and state any missing source or semantic-layer gap only when it materially affects the current answer. Restore script-driven validation as soon as local shell access is available.
 
@@ -136,7 +138,7 @@ Default Data Analytics outputs should be useful launchpads, not dead ends. In al
 
 Avoid asking for setup context merely to fill onboarding state. Ask only high-uncertainty, high-impact questions whose answers would significantly improve future outputs, semantic-layer quality, connector setup, or the active workflow. If onboarding is active, the current step card in `references/onboarding.md` governs the next step; otherwise use the ordinary action-oriented continuation rules here.
 
-Show at most one direct CTA during ordinary workflow output unless the user explicitly asks for options, onboarding, setup, or the Data Analytics TODO list. When onboarding has not started in an ordinary workflow, that CTA must be the `## Data Analytics Setup Required` template from preflight, even if the immediate artifact is otherwise complete, unless the immediate workflow is blocked on a required clarification. Clarifications always become the final natural continuation and suppress onboarding CTAs for that response. When onboarding is already active and core onboarding is incomplete, direct the user to finish the next core setup item before continuing non-urgent Data Analytics workflows. When onboarding is active and core onboarding is complete, preserve the workflow-owned final natural continuation and mention resuming guided onboarding only as a short non-competing note when useful. For direct onboarding and setup-status flows, follow `references/onboarding.md` instead: render the single visible compact `**Next Step**` block, mirror the compact high-level roadmap into the built-in thread task list when available, and check tasks off as the user completes, approves, declines, or makes them unnecessary. Skip the CTA only when the user asks for quiet behavior, the request is sensitive or high-pressure enough that a follow-up would be distracting, onboarding is complete and the workflow has no reasonable next action, or the focused workflow already owns a better clarification.
+Show at most one contextually useful next step. Respect inline-only and quiet requests. During explicit setup, follow `references/onboarding.md`; ordinary workflows do not become onboarding sessions merely because saved state is missing.
 
 ## Write
 
@@ -147,11 +149,11 @@ Write only two kinds of durable Data Analytics user context to `user-context.md`
 
 Do not store general memory, arbitrary "remember this" content, analytical priorities, copied source-of-truth links, saved dashboards, saved tables, saved docs, source inventories, output preferences, accepted-output preferences, quiet-ending preferences, automatic connector readiness, operational onboarding status, connector-audit bookkeeping, hero prompt progress, or semantic-layer refresh metadata in `user-context.md`. Area-specific metric, dashboard, table, source-of-truth, caveat, and definition anchors belong inside the semantic layer itself.
 
-First-run state creation remains automated when persistence is needed: run `python3 plugins/data-analytics/skills/user-context/scripts/init_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/init_user_context_state.py` from the Data Analytics plugin root, to copy `plugin-author-config/user-context-config.md` and seed `onboarding-state.json` from `references/onboarding-state-template.json`. Do not run this command just to show the first direct onboarding orientation. In sandboxed local-shell environments, request elevated execution on the first attempt because the target state directory is under `$CODEX_HOME`, not the project workspace. After initialization, modify `user-context.md` directly. For multi-entry approvals, read the current state once, update every touched source category in one coherent edit, update `onboarding-state.json` once when onboarding bookkeeping changes, then run `scripts/data_analytics_preflight.py --workflow user-context` or the relevant workflow preflight to confirm the supported context reads back cleanly. Keep `onboarding-state.json` compact: do not persist raw `list_available_plugins_to_install` results, full connector inventories, connector descriptions, copied source inventories, source URLs, prompts beyond the compact current onboarding choice, artifact text, source-gap notes, or analysis output. Store resolved route metadata, counts, ids, statuses, timestamps, and durable pointers instead. Never run parallel writes against the same Data Analytics state files.
+First-run state creation remains automated when persistence is needed: run `python3 .codex/skills/data-analytics/skills/user-context/scripts/init_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/init_user_context_state.py` from the Data Analytics plugin root, to copy `plugin-author-config/user-context-config.md` and seed `onboarding-state.json` from `references/onboarding-state-template.json`. Do not run this command just to show the first direct onboarding orientation. In sandboxed local-shell environments, request elevated execution on the first attempt because the target state directory is under `$CODEX_HOME`, not the project workspace. After initialization, modify `user-context.md` directly. For multi-entry approvals, read the current state once, update every touched source category in one coherent edit, update `onboarding-state.json` once when onboarding bookkeeping changes, then run `scripts/data_analytics_preflight.py --workflow user-context` or the relevant workflow preflight to confirm the supported context reads back cleanly. Keep `onboarding-state.json` compact: do not persist raw `list_available_plugins_to_install` results, full connector inventories, connector descriptions, copied source inventories, source URLs, prompts beyond the compact current onboarding choice, artifact text, source-gap notes, or analysis output. Store resolved route metadata, counts, ids, statuses, timestamps, and durable pointers instead. Never run parallel writes against the same Data Analytics state files.
 
 For semantic-layer setup, refresh, inspection, or repair, read `references/semantic-layer/setup.md`. Write durable layer pointers into the `# Semantic Layers` section of `user-context.md` and update operational setup or refresh metadata in `onboarding-state.json`. Do not keep semantic-layer discoverability only in onboarding state.
 
-For explicit debugging reset requests only, run `python3 plugins/data-analytics/skills/user-context/scripts/reset_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/reset_user_context_state.py` from the Data Analytics plugin root. The helper backs up active Data Analytics state files, then leaves the plugin ready for fresh onboarding. Never perform this reset for ordinary onboarding, source-routing preference edits, setup retries, source refresh work, or vague troubleshooting.
+For explicit debugging reset requests only, run `python3 .codex/skills/data-analytics/skills/user-context/scripts/reset_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/reset_user_context_state.py` from the Data Analytics plugin root. The helper backs up active Data Analytics state files, then leaves the plugin ready for fresh onboarding. Never perform this reset for ordinary onboarding, source-routing preference edits, setup retries, source refresh work, or vague troubleshooting.
 
 Use this source-routing structure:
 
@@ -186,7 +188,7 @@ For first-run setup after the first orientation, use `scripts/init_user_context_
 
 After the user approves the next setup step, supplies an explicit future source-routing choice, or semantic-layer setup needs a durable registry pointer:
 
-1. Run `python3 plugins/data-analytics/skills/user-context/scripts/init_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/init_user_context_state.py` from the Data Analytics plugin root, when local shell access is available. In sandboxed local-shell environments, request elevated execution on the first attempt because it writes to `$CODEX_HOME/state/plugins/data-analytics`. If the script is unavailable, create `$CODEX_HOME/state/plugins/data-analytics`, copy the content below `## Default User Context` from `plugin-author-config/user-context-config.md` into `user-context.md` with the required top note, and create `onboarding-state.json` from `references/onboarding-state-template.json`.
+1. Run `python3 .codex/skills/data-analytics/skills/user-context/scripts/init_user_context_state.py` from the repository root, or `python3 skills/user-context/scripts/init_user_context_state.py` from the Data Analytics plugin root, when local shell access is available. In sandboxed local-shell environments, request elevated execution on the first attempt because it writes to `$CODEX_HOME/state/plugins/data-analytics`. If the script is unavailable, create `$CODEX_HOME/state/plugins/data-analytics`, copy the content below `## Default User Context` from `plugin-author-config/user-context-config.md` into `user-context.md` with the required top note, and create `onboarding-state.json` from `references/onboarding-state-template.json`.
 2. Read the resulting `user-context.md`, preserving every source category's `Prefer` and `Avoid` rows plus the `# Semantic Layers` registry section.
 3. Update only the approved source-routing choice or semantic-layer pointer. Do not append disconnected general memory.
 4. Read the resulting `onboarding-state.json`, then update onboarding state with operational onboarding progress, connector confirmation labels, semantic-layer setup or refresh metadata, hero prompt progress, and skill experience progress.

package/template/.codex/skills/data-analytics/skills/user-context/plugin-author-config/automation-config.md

@@ -16,7 +16,7 @@ Every automation entry must use this shape:
 - Instructions: thin launcher instructions for the scheduled run.
 ```
 
-Do not add model, reasoning effort, heartbeat kind, RRULEs, tool names, user-specific target thread ids, canonical automation ids, install status, readback evidence, cleanup state, onboarding notification copy, or per-user preferred times here. Those belong in `../references/automation.md` or `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json`.
+Do not add model, reasoning effort, heartbeat kind, RRULEs, tool names, user-specific target thread ids, canonical automation ids, install status, readback evidence, cleanup state, onboarding notification copy, or per-user preferred times here. Those belong in `../references/automation.md` or `$CODEX_HOME/state/plugins/data-analytics/onboarding-state.json`.
 
 ## Default Automations
 

package/template/.codex/skills/data-analytics/skills/user-context/references/onboarding-examples.md

@@ -65,7 +65,7 @@ User says:
 continue
 ```
 
-Context: Data Analytics found Google Drive and Notion for company docs, but no active data warehouse or team communication route. `functions.list_available_plugins_to_install` returned Databricks, BigQuery, Snowflake, Slack, and Teams.
+Context: Data Analytics found Google Drive and Notion for company docs, but no active data warehouse or team communication route. `host_available_plugin_catalog` returned Databricks, BigQuery, Snowflake, Slack, and Teams.
 
 Expected behavior:
 

package/template/.codex/skills/data-analytics/skills/user-context/references/onboarding.md

@@ -1,12 +1,12 @@
 # Data Analytics Onboarding Flow
 
-Use this reference when `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md` is missing or unreadable, when the user asks what Data Analytics can do, when the user asks to set up or customize Data Analytics, or when `onboarding-state.json` says onboarding is active and a nudge is due.
+Use this reference when `$CODEX_HOME/state/plugins/data-analytics/user-context.md` is missing or unreadable, when the user asks what Data Analytics can do, when the user asks to set up or customize Data Analytics, or when `onboarding-state.json` says onboarding is active and a nudge is due.
 
 Onboarding is a mostly linear, nested step-card playbook. It is not a formal graph. Each step owns setup copy, output contract, action close, completion behavior, skip or defer behavior, and any loop or optional branch. Every onboarding message should handle one major user-visible step at most, mirror the overall progress list when the UI is available, and end with one clear action or question.
 
-Store durable source-routing preferences explicitly selected for future use plus semantic-layer pointers in `user-context.md`. Store only operational onboarding progress, including connector-confirmation labels, skill experience progress, semantic-layer setup and refresh state, automation setup, and quiet or complete state, in `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/onboarding-state.json`. Keep onboarding state compact: do not put raw `list_available_plugins_to_install` results, full connector inventories, connector descriptions, copied source inventories, source URLs, source data, polling results, research result bodies, artifact text, source-gap notes, or analysis output in onboarding state; keep that content in `user-context.md`, the generated semantic-layer skill, the pinned polling thread, the current workflow artifact, or the source system. Record compact route metadata, counts, ids, statuses, timestamps, and durable pointers instead. Do not create, read, or update durable connector-readiness proof as part of onboarding. Data Analytics workflows use plugins, apps, or connectors when the workflow needs the source.
+Store durable source-routing preferences explicitly selected for future use plus semantic-layer pointers in `user-context.md`. Store only operational onboarding progress, including connector-confirmation labels, skill experience progress, semantic-layer setup and refresh state, automation setup, and quiet or complete state, in `$CODEX_HOME/state/plugins/data-analytics/onboarding-state.json`. Keep onboarding state compact: do not put raw `list_available_plugins_to_install` results, full connector inventories, connector descriptions, copied source inventories, source URLs, source data, polling results, research result bodies, artifact text, source-gap notes, or analysis output in onboarding state; keep that content in `user-context.md`, the generated semantic-layer skill, the pinned polling thread, the current workflow artifact, or the source system. Record compact route metadata, counts, ids, statuses, timestamps, and durable pointers instead. Do not create, read, or update durable connector-readiness proof as part of onboarding. Data Analytics workflows use plugins, apps, or connectors when the workflow needs the source.
 
-The first direct onboarding response is a response-first fast path. When the user asks to onboard, set up, or learn what Data Analytics can do and no Data Analytics state files exist yet, render Step 1 immediately. Do not run `../scripts/init_user_context_state.py`, write scaffold files, inspect connectors, audit conflicts, create semantic layers, create threads, install automations, start source discovery, or run workflows before that first message. After the user approves the next visible setup step, or whenever the user supplies context that should be saved, use `../scripts/init_user_context_state.py` when local shell access is available. In sandboxed local-shell environments, request elevated execution by default because it writes to `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}`.
+The first direct onboarding response is a response-first fast path. When the user asks to onboard, set up, or learn what Data Analytics can do and no Data Analytics state files exist yet, render Step 1 immediately. Do not run `../scripts/init_user_context_state.py`, write scaffold files, inspect connectors, audit conflicts, create semantic layers, create threads, install automations, start source discovery, or run workflows before that first message. After the user approves the next visible setup step, or whenever the user supplies context that should be saved, use `../scripts/init_user_context_state.py` when local shell access is available. In sandboxed local-shell environments, request elevated execution by default because it writes to `$CODEX_HOME/state/plugins/data-analytics`.
 
 Related sources of truth:
 
@@ -107,7 +107,7 @@ Mirror this user-visible roadmap into the built-in thread task list when availab
 
 Before every onboarding response, refresh the checklist from current onboarding state after applying actions from that turn. If the response completed, skipped, or deferred a step, mark that step accordingly and mark the next unresolved visible step as `in_progress`.
 
-Treat core onboarding as complete after source setup confirmation is resolved and the data semantic layer step is either set up from user-provided inputs, explicitly skipped, deferred, unavailable, or blocked with one concrete path. Source setup confirmation is not complete while `structured_data`, `team_communication`, or `company_docs` has an installable or otherwise actionable route question that the user has not explicitly resolved. If no stable semantic-layer target exists because the user skipped, deferred, or is blocked, do not require the refresh substep. Ordinary Data Analytics work should still answer best effort while onboarding is missing or active, then append the single preflight-provided setup obligation unless the response is blocked on a required clarification or the user asked for quiet behavior.
+Treat core onboarding as complete after source setup confirmation is resolved and the data semantic layer step is either set up from user-provided inputs, explicitly skipped, deferred, unavailable, or blocked with one concrete path. Source setup confirmation is not complete while `structured_data`, `team_communication`, or `company_docs` has an installable or otherwise actionable route question that the user has not explicitly resolved. If no stable semantic-layer target exists because the user skipped, deferred, or is blocked, do not require the refresh substep. Ordinary Data Analytics work should still answer best effort while onboarding is missing or active, append at most one preflight-provided setup suggestion only when its `only_when` condition is met and a missing source meaningfully affects the current task. Inline-only and quiet requests do not acquire onboarding CTAs.
 
 Treat a plain `yes`, `okay`, `continue`, `ready`, or similar reply after a next-step CTA as approval to perform the current visible next step unless the user names a different action. Treat `skip`, `skip for now`, `not now`, or similar as approval to mark the current visible step skipped or deferred when that step allows it, then continue.
 
@@ -167,7 +167,7 @@ Reply `continue` and I'll check which analytics sources Codex can use, only aski
 - Exit when: Every core source category is recorded as `active` or has a user-explicit `declined`, `deferred`, `skipped`, `unavailable`, or `not_applicable` fallback, any offered optional category is recorded as `active`, `missing`, `declined`, `deferred`, `skipped`, `unavailable`, or `not_applicable`, or the user explicitly chooses to continue with recorded known gaps.
 - Completion: Store onboarding confirmation labels and resolved source routes in `onboarding-state.json`; do not write connector readiness to `user-context.md`.
 - Next: Step 2A, `resolve_source_questions`, when any source category needs user input; otherwise Step 3A, `introduce_semantic_layer_setup`.
-- Output contract: Return a concise standalone active/missing source result with one setup-ready heading line, bold bullets for available sources, one sentence naming remaining source gaps, and one clear setup question. Active connector or app sources are informational fallback routes, not winners, when a related plugin is installed or installable. This setup step, not preflight, inspects the environment, calls `functions.list_available_plugins_to_install` once for the setup pass, and writes resolved routes for each source category. Ask only when there are multiple mutually exclusive installed source tools, an installable related plugin needs approval, no source was found, or the category needs IT or admin help. Do not ask for a docs preference merely because both Google Drive and Notion are available; record both routes and let workflows use both. For missing sources and connector-covered sources, prefer plugin setup, then direct app or connector setup, then manual exports or pasted context. Core categories are not optional setup extras: if `structured_data`, `team_communication`, or `company_docs` lacks an active or manual route, make it part of the Step 2 question, keep installable core candidates as `needs_confirmation`, and do not introduce semantic-layer setup until the user installs a route or explicitly says to defer, skip, decline, mark unavailable, mark not applicable, or continue with a recorded known gap. Do not introduce semantic-layer setup in the same response when source questions remain. When core source questions remain and company docs are already covered, use this style:
+- Output contract: Return a concise standalone active/missing source result with one setup-ready heading line, bold bullets for available sources, one sentence naming remaining source gaps, and one clear setup question. Active connector or app sources are informational fallback routes, not winners, when a related plugin is installed or installable. This setup step, not preflight, inspects the environment, inspects the host-provided installable-plugin catalog once for the setup pass, and writes resolved routes for each source category. Ask only when there are multiple mutually exclusive installed source tools, an installable related plugin needs approval, no source was found, or the category needs IT or admin help. Do not ask for a docs preference merely because both Google Drive and Notion are available; record both routes and let workflows use both. For missing sources and connector-covered sources, prefer plugin setup, then direct app or connector setup, then manual exports or pasted context. Core categories are not optional setup extras: if `structured_data`, `team_communication`, or `company_docs` lacks an active or manual route, make it part of the Step 2 question, keep installable core candidates as `needs_confirmation`, and do not introduce semantic-layer setup until the user installs a route or explicitly says to defer, skip, decline, mark unavailable, mark not applicable, or continue with a recorded known gap. Do not introduce semantic-layer setup in the same response when source questions remain. When core source questions remain and company docs are already covered, use this style:
 
 ```md
 After some searching, it looks like you're already set up with Google Drive, Notion, and Spreadsheets.
@@ -197,7 +197,7 @@ Reply with the sources you want to connect now, or say `defer for now` to contin
 ```
 
 Do not render separate `Active sources`, `Sources I need your help with`, or `Missing sources and practical impact` headings unless the source result is too unusual for the concise shape.
-- Reference copy: Active and appropriate sources are FYI only. Do not preflight-read installed or active sources just to prove they work. For each category, compare `saved_source_preferences` and `preferred` from preflight, configured `preferred_plugins` from `source-category-config.json`, legacy `preferred_apps` only when present, `.app.json` ids for configured preferred providers, the session `Available plugins` and `Available skills` blocks, and the single `functions.list_available_plugins_to_install` result for the setup pass. If one or more related plugins are installed with visible skill or tool surfaces, write them to `connector_confirmation` as active routes under `routes[]` with `source_kind: plugin`, `skill_surface`, plugin details, and evidence fields. Related means the plugin or provider itself matches the configured preferred plugin route, or its declared connector id matches a configured preferred provider id from `.app.json`; cross-source search surfaces are not active source routes for another category. Do not classify Notion, Google Drive, or a broad internal search tool as active team communication solely because it indexes Slack or Teams. If no related plugin is active but a related plugin is installable, highlight it as the recommended setup action even when an app or connector route is already active; explain that Data Analytics should prefer the plugin because it can add dedicated Data Analytics workflow support, and keep the existing app or connector route as fallback if the user defers or install visibility is pending. Rank plugin candidates by saved preferences first, then configured `preferred_plugins`, then legacy `preferred_apps` when present, then `.app.json` connector-id intersections. If no related plugin is installed or installable and exactly one plausible app or connector is installed or available, write it as active with `source_kind`, `skill_surface`, and route details when available, then let the workflow's first real read handle auth, query, or schema issues. If multiple plausible source tools are complementary rather than mutually exclusive, such as Drive and Notion for docs, write multiple active routes instead of asking the user to pick a winner. If multiple plausible source tools are mutually exclusive for the same category, ask the user which one to prefer and write the selected route only after resolving its plugin, app, connector, or manual route. Missing sources should explain practical workflow impact and list specific IT or admin options. Be prescriptive about pilot setup: warehouse access unlocks live metric definitions, table shape, query logic, and current-source validation; dashboards and BI let Data Analytics inspect dashboards and BI reports for metric definitions, filters, and saved views; behavior signals unlock product usage, funnels, retention, adoption, and experiment evidence; notebook labs let Data Analytics inspect prior analyses, reuse notebook logic, and continue exploratory work; Slack or Teams unlock recent discussion, owners, caveats, and decision context; Drive, SharePoint, or Notion unlock source-of-truth docs, specs, dashboard notes, and governance context; GitHub unlocks model, query, schema, and semantic-layer ownership.
+- Reference copy: Active and appropriate sources are FYI only. Do not preflight-read installed or active sources just to prove they work. For each category, compare `saved_source_preferences` and `preferred` from preflight, configured `preferred_plugins` from `source-category-config.json`, legacy `preferred_apps` only when present, `.app.json` ids for configured preferred providers, the session `Available plugins` and `Available skills` blocks, and the single `host_available_plugin_catalog` result for the setup pass. If one or more related plugins are installed with visible skill or tool surfaces, write them to `connector_confirmation` as active routes under `routes[]` with `source_kind: plugin`, `skill_surface`, plugin details, and evidence fields. Related means the plugin or provider itself matches the configured preferred plugin route, or its declared connector id matches a configured preferred provider id from `.app.json`; cross-source search surfaces are not active source routes for another category. Do not classify Notion, Google Drive, or a broad internal search tool as active team communication solely because it indexes Slack or Teams. If no related plugin is active but a related plugin is installable, highlight it as the recommended setup action even when an app or connector route is already active; explain that Data Analytics should prefer the plugin because it can add dedicated Data Analytics workflow support, and keep the existing app or connector route as fallback if the user defers or install visibility is pending. Rank plugin candidates by saved preferences first, then configured `preferred_plugins`, then legacy `preferred_apps` when present, then `.app.json` connector-id intersections. If no related plugin is installed or installable and exactly one plausible app or connector is installed or available, write it as active with `source_kind`, `skill_surface`, and route details when available, then let the workflow's first real read handle auth, query, or schema issues. If multiple plausible source tools are complementary rather than mutually exclusive, such as Drive and Notion for docs, write multiple active routes instead of asking the user to pick a winner. If multiple plausible source tools are mutually exclusive for the same category, ask the user which one to prefer and write the selected route only after resolving its plugin, app, connector, or manual route. Missing sources should explain practical workflow impact and list specific IT or admin options. Be prescriptive about pilot setup: warehouse access unlocks live metric definitions, table shape, query logic, and current-source validation; dashboards and BI let Data Analytics inspect dashboards and BI reports for metric definitions, filters, and saved views; behavior signals unlock product usage, funnels, retention, adoption, and experiment evidence; notebook labs let Data Analytics inspect prior analyses, reuse notebook logic, and continue exploratory work; Slack or Teams unlock recent discussion, owners, caveats, and decision context; Drive, SharePoint, or Notion unlock source-of-truth docs, specs, dashboard notes, and governance context; GitHub unlocks model, query, schema, and semantic-layer ownership.
 - Next-step copy: If one or more source categories need user input, make the `Next Step` only about resolving those questions. When the Step 2 source result includes explanatory optional sources before a separate core-source reply line, render `**Next Step**` immediately before that final reply line so the action close stays visually distinct. If no source questions need input, move directly into Step 3A with a short transition note and the semantic-layer introduction; do not ask whether to introduce it.
 
 ### Step 2A: Resolve Source Questions
@@ -238,7 +238,7 @@ You can defer warehouse or team communication access, but say it explicitly so D
 
 After the user answers, install confirmed plugin or connector candidates one at a time, save any clear source preferences or accepted skips, then move directly into the semantic-layer introduction. Do not ask whether to introduce it. For routine source setup preferences in onboarding, do not render a saved-context recap or `Saved today` list; use only the short transition into Step 3A below, then render Step 3A in the same response:
 
-If the user confirms an installable plugin or connector candidate returned by `functions.list_available_plugins_to_install`, call `functions.request_plugin_install` with `action_type: "install"`, the returned candidate `tool_type`, the returned candidate `id`, and a concise reason such as `Use Databricks as the preferred Data Analytics source for data warehouse.` Pass the returned `tool_type` directly; it may be `plugin` or `connector`. Do not call `request_plugin_install` in parallel with any other tool. If multiple related plugin candidates tie after saved preference order, configured `preferred_plugins` order, legacy `preferred_apps` order when present, and connector-id matching, ask the user to choose; if no related plugin candidate exists, say so and offer admin, app, connector, or manual fallback. If plugin install fails, setup fails, or install succeeds but the plugin-owned skills or tools are not visible yet, record the category as `needs_confirmation`, `deferred`, `deferred_environment_api_limitations`, or `skipped_for_now`; do not mark it active and do not treat the failed setup as a durable decline. Keep plugin-first setup eligible for retry in future workflows when that source category matters. If the user explicitly declines a plugin, suppress that plugin in the current workflow and fall back to the next related plugin candidate, existing connector or app route, or manual setup for that category; save a future `do not use` rule only when the user asks for durable avoidance.
+If the user confirms an installable plugin or connector candidate returned by `host_available_plugin_catalog`, call `host_authorized_plugin_install` with `action_type: "install"`, the returned candidate `tool_type`, the returned candidate `id`, and a concise reason such as `Use Databricks as the preferred Data Analytics source for data warehouse.` Pass the returned `tool_type` directly; it may be `plugin` or `connector`. Do not call `request_plugin_install` in parallel with any other tool. If multiple related plugin candidates tie after saved preference order, configured `preferred_plugins` order, legacy `preferred_apps` order when present, and connector-id matching, ask the user to choose; if no related plugin candidate exists, say so and offer admin, app, connector, or manual fallback. If plugin install fails, setup fails, or install succeeds but the plugin-owned skills or tools are not visible yet, record the category as `needs_confirmation`, `deferred`, `deferred_environment_api_limitations`, or `skipped_for_now`; do not mark it active and do not treat the failed setup as a durable decline. Keep plugin-first setup eligible for retry in future workflows when that source category matters. If the user explicitly declines a plugin, suppress that plugin in the current workflow and fall back to the next related plugin candidate, existing connector or app route, or manual setup for that category; save a future `do not use` rule only when the user asks for durable avoidance.
 
 If the user selects or confirms an installed or available plugin, app, or connector, treat it as usable for setup purposes only when the route evidence matches `source-category-runtime.md`, write the resolved route to `connector_confirmation`, and transition without a proof read. If the selected source is missing, use the matching source category and native plugin, app, or connector path: load any relevant helper skill from `source-category-config.json`, use tool discovery or exposed app tools if needed, and run the smallest safe read-only action only when a workflow needs the source. If the workflow-time read triggers auth or setup, let that flow complete before continuing and then write the resolved app or connector route. If no read action or setup route is exposed, keep the category unresolved and ask the user whether to install, connect, or authorize it, ask IT or admin to enable it, defer or skip the category, or proceed with manual or exported context. Adapt the source list in the transition to the resolved active or default sources, but when the standard onboarding source set applies, use this copy spine:
 

package/template/.codex/skills/data-analytics/skills/user-context/references/source-category-runtime.md

@@ -13,19 +13,19 @@ A source category is the kind of analytical evidence a workflow may need, such a
 
 ## Setup-Owned Source Routes
 
-Source route selection happens during onboarding, an explicit source-setup turn, or workflow-time repair for a missing or broken source, not during ordinary preflight. The setup or search step is responsible for inspecting the current environment, preferring related plugins before raw app or connector routes, asking for installation or setup when needed, and writing compact resolved routes to `onboarding-state.json` under `connector_confirmation`. Do not persist the raw `functions.list_available_plugins_to_install` response, full session plugin inventory, connector descriptions, or discovery transcript into onboarding state.
+Source route selection happens during onboarding, an explicit source-setup turn, or workflow-time repair for a missing or broken source, not during ordinary preflight. The setup or search step is responsible for inspecting the current environment, preferring related plugins before raw app or connector routes, asking for installation or setup when needed, and writing compact resolved routes to `onboarding-state.json` under `connector_confirmation`. Do not persist the raw `host_available_plugin_catalog` response, full session plugin inventory, connector descriptions, or discovery transcript into onboarding state.
 
 Preflight is a reader. It should return the configured routes that setup wrote, plus unresolved setup gaps, but it must not choose a plugin, app, connector, or manual route on its own. Runtime workflows consume the configured routes.
 
 During setup, prefer source routes in this order:
 
 1. Installed or enabled related plugin from the session `Available plugins` block when it has visible plugin-owned skill or tool surface.
-2. Installable related plugin returned by `functions.list_available_plugins_to_install`, including a plugin that contains or declares a connector or app id from the category's configured preferred plugin route.
+2. Installable related plugin returned by `host_available_plugin_catalog`, including a plugin that contains or declares a connector or app id from the category's configured preferred plugin route.
 3. Installed or installable app or connector returned by the same install listing or exposed in the session or tool surface.
 4. Manual, uploaded, pasted, or exported context.
 5. Missing or unavailable with practical IT or admin options.
 
-At the start of onboarding source resolution or explicit source setup, call `functions.list_available_plugins_to_install` once and reuse those results for all source categories in that pass. Also read the session `Available plugins` block to identify installed plugins, and read the session `Available skills` block when deciding whether an installed plugin has plugin-owned skills exposed. Load `../plugin-author-config/source-category-config.json` for category `preferred_plugins` and legacy `preferred_apps` only when present, and load `.app.json` to map configured preferred provider names to app or connector ids.
+At the start of onboarding source resolution or explicit source setup, inspect the host-provided installable-plugin catalog once and reuse those results for all source categories in that pass. Also read the session `Available plugins` block to identify installed plugins, and read the session `Available skills` block when deciding whether an installed plugin has plugin-owned skills exposed. Load `../plugin-author-config/source-category-config.json` for category `preferred_plugins` and legacy `preferred_apps` only when present, and load `.app.json` to map configured preferred provider names to app or connector ids.
 
 Installed source tools are treated as usable for setup purposes only when their surface is visible enough to use later. If setup finds one or more installed related plugins with visible plugin-owned skill or tool surfaces for the same category, write all useful routes as active under `routes` and let workflows choose among them by evidence need. Do not force a preference question just because several non-conflicting sources are available, such as Google Drive and Notion for company docs; the agent can use both. If setup finds an installed app or connector and also finds a related plugin candidate, prefer the plugin anyway because Data Analytics workflows should use plugin-owned skills and tools when available; keep the app or connector route as fallback if the user defers or install visibility is pending. If setup finds one installed app or connector and no related plugin candidate, write the app or connector route as active and let the workflow try the actual read only when it needs that source. Do not perform a read merely to prove an installed source works during onboarding.
 
@@ -74,7 +74,7 @@ Recommended active multi-route state:
           "source_kind": "plugin",
           "skill_surface": "plugin_owned",
           "plugin": {
-            "id": "google-drive@openai-curated",
+            "id": "<google-drive-id-from-host-catalog>",
             "name": "Google Drive"
           },
           "plugin_install_evidence": "plugin_in_available_plugins",
@@ -150,9 +150,9 @@ When setup finds that a needed source category is not already covered by a prove
 
 1. Build the plugin preference order from `saved_source_preferences` when preflight provides them first, then the source category's configured `preferred_plugins`, then legacy `preferred_apps` only when present. Use that order to rank plugins, but do not require the user to have saved a preference before plugin setup is attempted.
 2. Check the session `Available plugins` block for an installed plugin whose name, display name, id, or declared app or connector ids match a configured preferred plugin route for the category. If it has visible plugin-owned skill or tool surface, write it as the active route.
-3. If no installed related plugin exists, call `functions.list_available_plugins_to_install` if it has not already been called in this setup pass, then look for related plugin candidates.
+3. If no installed related plugin exists, inspect the host-provided installable-plugin catalog if it has not already been inspected in this setup pass, then look for related plugin candidates.
 4. A candidate is related only when the plugin or provider itself matches the configured preferred plugin route, or its declared `app_connector_ids` intersects the `.app.json` ids for a configured preferred plugin route. Legacy `preferred_apps` may contribute only when an older config still declares them. Do not treat broad search, mirrored content, imported content, or a description-level category similarity as enough to make a plugin related.
-5. Prefer plugin candidates over connector candidates even when the app or connector route is already callable or active. If one related plugin candidate is clearly best by saved preference order, configured `preferred_plugins` order, legacy `preferred_apps` order when present, or connector-id intersection, ask one clear install or defer question unless the user explicitly requested installation. If the user confirms, call `functions.request_plugin_install` with the exact returned candidate `tool_type` and `id`. Do not call `request_plugin_install` in parallel with any other tool.
+5. Prefer plugin candidates over connector candidates even when the app or connector route is already callable or active. If one related plugin candidate is clearly best by saved preference order, configured `preferred_plugins` order, legacy `preferred_apps` order when present, or connector-id intersection, ask one clear install or defer question unless the user explicitly requested installation. If the user confirms, call `host_authorized_plugin_install` with the exact returned candidate `tool_type` and `id`. Do not call `request_plugin_install` in parallel with any other tool.
 6. If multiple related plugin candidates tie after saved preference order, configured `preferred_plugins` order, legacy `preferred_apps` order when present, and connector-id matching, ask the user to choose among only those tied relevant candidates.
 7. If installation or setup fails, or install succeeds but plugin skills or tools are not visible yet, keep the plugin setup path retryable. Record `needs_confirmation`, `deferred`, `deferred_environment_api_limitations`, or `skipped_for_now` for operational state, not `declined`, and surface plugin-first setup again in a future workflow when that source category is material. Use connector or app or manual fallback for the current run when useful.
 8. If the user declines a plugin, suppress that plugin for the current workflow and continue with the next related plugin candidate, the existing app or connector route, another user-selected source, or manual or exported context. Save a durable `do not use` or `do not offer` rule only when the user explicitly asks for that future behavior.
@@ -256,7 +256,7 @@ Do not write `available`, `verified`, `checked`, `installed`, or automatic `bloc
 
 ## Onboarding Behavior
 
-The first direct onboarding response should not inspect connectors. After the user approves setup, run source setup or search, call `functions.list_available_plugins_to_install` once, prefer related plugins over raw app or connector routes, and write resolved routes for each category to `connector_confirmation`. Do not preflight-read installed or active connectors merely to prove they work. Active sources are informational only; do not ask the user to confirm every source when setup finds clear active installed plugins, apps, or connectors that can coexist in the same category.
+The first direct onboarding response should not inspect connectors. After the user approves setup, run source setup or search, inspect the host-provided installable-plugin catalog once, prefer related plugins over raw app or connector routes, and write resolved routes for each category to `connector_confirmation`. Do not preflight-read installed or active connectors merely to prove they work. Active sources are informational only; do not ask the user to confirm every source when setup finds clear active installed plugins, apps, or connectors that can coexist in the same category.
 
 Ask for help only when there are multiple mutually exclusive plausible source tools, an installable related plugin needs approval, no source was found, or IT or admin action may be needed. For missing or connector-covered sources, use plugin setup before connector or app setup and manual fallback. When a later focused workflow needs a source, that workflow attempts the configured source route at that moment and handles plugin install, auth, connection, skip, or manual fallback in context.
 

package/template/.codex/skills/data-analytics/skills/user-context/scripts/data_analytics_preflight.py

@@ -690,9 +690,9 @@ def plugin_first_setup_recovery(
         "type": "plugin_first_source_setup",
         "preferred_plugins": unique_strings(metadata.get("preferred_plugins") or []),
         "configured_source_routes": preferred_source_routes(metadata),
-        "candidate_lookup": "functions.list_available_plugins_to_install",
+        "candidate_lookup": "host_available_plugin_catalog",
         "candidate_match": "plugin_name_slug_or_app_connector_id_intersection",
-        "install_request": "functions.request_plugin_install",
+        "install_request": "host_authorized_plugin_install",
         "install_requires_user_approval": True,
         "fallback_setup_action": fallback_setup_action,
     }
@@ -1328,6 +1328,7 @@ def final_obligations(
             {
                 "id": "offer_data_analytics_onboarding_next_step",
                 "timing": "append_after_main_answer",
+                "only_when": "missing setup materially affects the requested output and the user has not requested inline-only or quiet delivery",
                 "template": markdown_template_from_onboarding_reference(
                     "Ordinary Workflow Onboarding CTA"
                 ),
@@ -1340,6 +1341,7 @@ def final_obligations(
             {
                 "id": "complete_data_analytics_core_onboarding",
                 "timing": "append_after_main_answer",
+                "only_when": "missing setup materially affects the requested output and the user has not requested inline-only or quiet delivery",
                 "template": markdown_template_from_onboarding_reference(
                     "Active Core Onboarding Reminder"
                 ),

package/template/.codex/skills/data-analytics/skills/user-context/scripts/validate_user_context_preflight.py

@@ -16,10 +16,10 @@ MANDATORY_GATE_PHRASES = (
     "not as substitutes for workflow-time reads from connected or provided sources",
 )
 USER_CONTEXT_MANDATORY_GATE_PHRASES = (
-    "set the tool's `max_output_tokens` to at least `25000`",
+    "there is no fixed minimum token allocation",
     "warn the user that Data Analytics could not load all source-routing preferences and semantic-layer registry entries in one pass",
     "do not use the payload until the complete output is visible",
-    "reports read status for `$CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md`",
+    "reports read status for `$CODEX_HOME/state/plugins/data-analytics/user-context.md`",
 )
 PREFLIGHT_HELPER_PHRASES = (
     "summarize_user_context",
@@ -30,8 +30,8 @@ PREFLIGHT_HELPER_PHRASES = (
     "preferred_source_routes",
     "match_installable_plugin_candidates",
     "plugin_first_setup_recovery",
-    "functions.list_available_plugins_to_install",
-    "functions.request_plugin_install",
+    "host_available_plugin_catalog",
+    "host_authorized_plugin_install",
     "plugin_setup_opportunities",
 )
 
@@ -171,7 +171,7 @@ def main() -> int:
     for phrase in (
         "## Setup-Owned Source Routes",
         "Preflight is a reader.",
-        "functions.list_available_plugins_to_install",
+        "host_available_plugin_catalog",
         "## Plugin-First Setup For Missing Sources",
         "Do not proactively suggest every installable plugin",
         "## Missing Sources And Fallbacks",

package/template/.codex/skills/data-analytics/skills/user-context/tests/test_state_helpers.py

@@ -36,7 +36,7 @@ assert PREFLIGHT_SPEC and PREFLIGHT_SPEC.loader
 PREFLIGHT_MODULE = importlib.util.module_from_spec(PREFLIGHT_SPEC)
 PREFLIGHT_SPEC.loader.exec_module(PREFLIGHT_MODULE)
 
-# Representative functions.list_available_plugins_to_install fixture for plugin-first routing.
+# Representative host_available_plugin_catalog fixture for plugin-first routing.
 LIVE_INSTALLABLE_PLUGIN_CANDIDATES = [
     {
         "id": "databricks@openai-curated",
@@ -371,11 +371,11 @@ class DataAnalyticsStateHelperTests(unittest.TestCase):
         self.assertEqual(slack["plugin_preference_order"], ["Slack", "Teams"])
         self.assertEqual(
             slack["setup_recovery"]["candidate_lookup"],
-            "functions.list_available_plugins_to_install",
+            "host_available_plugin_catalog",
         )
         self.assertEqual(
             slack["setup_recovery"]["install_request"],
-            "functions.request_plugin_install",
+            "host_authorized_plugin_install",
         )
         calendar = confirmation["calendar_context"]
         self.assertEqual(

package/template/.codex/skills/data-analytics/skills/validate-data/SKILL.md

@@ -13,10 +13,13 @@ duplicates, join coverage, or source mismatches, use $analyze-data-quality as a
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
+Choose checks from the data grain, intended decision and known risk. Reuse fresh checks already covering the same source/query/transform; do not repeat the catalog. A notebook is needed only when reproducibility or multi-step analysis warrants it. Preserve blocking correctness findings and report material limitations.
+
+
 1. Inventory the artifact and claims.
 
    Identify the report, notebook, spreadsheet, SQL, dashboard, chart, pasted analysis, or recommendation being validated. Inspect source artifacts when a path, link, query, notebook, spreadsheet, or dashboard is referenced. Extract the main question, audience, decision, key claims, headline numbers, data sources, time windows, populations, filters, comparison baselines, and stated caveats. Verify that every metric or KPI requested by the user appears in the analysis or is explicitly marked unavailable, not applicable, or out of scope.
@@ -76,76 +79,9 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
   high-impact decisions, and externally shared analyses as higher-risk validation targets.
 - Select checks that match the artifact and decision. Do not run every possible check mechanically.
 
-### Methodology Checks
-
-- Question framing: the analysis answers the stated business or product question.
-- Data selection: sources are appropriate and current enough for the decision.
-- Population: inclusions, exclusions, eligibility rules, and sampling are explicit.
-- Metric definitions: formulas, units, denominators, and timezones are clear and aligned with stakeholder definitions.
-- Baselines: comparison periods, cohorts, and contexts are comparable.
-- Causality: causal wording is backed by experimental or otherwise credible causal evidence.
-
-### Data Quality Checks
-
-- Freshness: the analysis states or can recover the data "as of" date.
-- Completeness: no unexpected missing partitions, segments, rows, or categories.
-- Null handling: key columns have expected null rates or explicit treatment.
-- Deduplication: primary entities are not double counted.
-- Filter verification: filters and WHERE clauses do not silently exclude the population of interest.
-- Join coverage: dimensions, experiments, and reference tables do not drop or multiply important rows.
-
-### Calculation Checks
-
-- Grain: the aggregation level matches the intended analysis grain.
-- Denominators: rates and percentages use the correct population and non-zero denominators.
-- Period alignment: comparisons use equal or explicitly caveated windows.
-- Weighted metrics: averages are weighted correctly when group sizes differ.
-- Subtotals: parts add to totals where categories are mutually exclusive.
-- Units: currency, token, user, request, account, day/week/month, and timezone units are consistent.
-
-### Reasonableness Checks
-
-- Magnitudes are plausible relative to known dashboards, historical reports, or expected product scale.
-- Percentages fall in expected ranges and segment shares sum to about 100% where expected.
-- Trend jumps, drops, flatlines, exact round numbers, and 0% or 100% rates have an explanation.
-- Results do not perfectly confirm the hypothesis without friction or exceptions.
-- Edge cases such as empty segments, new entities, and boundary dates behave sensibly.
-
-### Common Pitfalls
-
-- Join explosion: many-to-many joins silently multiply rows and inflate counts or sums. Compare row counts and distinct primary entities before and after the join, and check whether the right-hand table has multiple rows per join key.
-  Aggregate the right-hand table to the intended grain before joining when needed, use `COUNT(DISTINCT primary_id)` when counting entities through joins,
-  and comment intentional one-to-many joins.
-- Survivorship bias: the analysis only includes entities that exist today and misses deleted, churned, failed, or otherwise absent entities. Ask who is not in the dataset and whether the missing population changes the conclusion.
-- Incomplete period comparison: a partial period is compared with a complete period. Use complete periods, compare the same number of elapsed days, or label the partial-period caveat prominently.
-- Denominator shifting: the eligible population changes between periods or segments. Validate that conversion, churn, activation, attach, and retention rates use stable definitions across compared groups.
-- Average of averages: pre-computed averages are averaged without weighting for group size. Aggregate from raw numerators and denominators or use a weighted average.
-- Timezone mismatch: sources use different timestamp conventions or daily cutoffs. Confirm the analysis standardizes timestamps or explicitly states the timezone and cutoff.
-- Selection bias in segmentation: segments are defined by the outcome being measured. Define comparison groups by pre-treatment characteristics when making lift, causality, or behavior-difference claims.
-- Other statistical traps: Simpson's paradox where aggregate and segment-level trends conflict, correlation presented as causation, small samples,
-  outlier-dominated averages that need medians or distribution views, multiple testing, cherry-picked time ranges, and look-ahead bias.
-
-### Spot-Check Recipes
-
-- Recompute a key metric from raw numerators and denominators.
-- Trace a few individual records through joins, filters, and final output.
-- Reconcile a key total against a trusted dashboard, prior report, or finance source.
-- Reverse engineer a headline number from component metrics, such as users times per-user revenue.
-- Run a one-day, one-segment, or one-entity boundary check to make sure filters and joins behave sensibly.
-- Compare the same metric through an alternate query path when a claim is surprising or high stakes.
-
-### Visualization Checks
-
-- Bar charts should generally start at zero.
-- Comparison charts should use consistent scales unless the scale difference is explicit and justified.
-- Axes, units, legends, and date ranges should be labeled.
-- Category ordering should match the comparison the reader should make.
-- Truncated axes, dual axes, 3D effects, and inconsistent intervals require explicit justification or redesign.
-- Chart titles and annotations should match exactly what the data supports.
-- Titles should state the finding and include date range or scope when needed.
-- Caveats should be visible near the claims they qualify.
-- Number formatting should use appropriate precision and units.
-- Rendered artifacts should be checked in their final form when available, not only in source form.
+### 按风险选择方法
+
+核验方法、数据质量、计算、合理性或可视化时，按对应风险读取 [方法与抽查示例](references/validation-methods.md)。验证同一证据不重复逐项抄写；影响结论的错误必须修复或阻断，非阻断限制显式随结果交付。
 
 ### Confidence Ratings
 

package/template/.codex/skills/data-analytics/skills/validate-data/references/validation-methods.md

@@ -0,0 +1,70 @@
+### Methodology Checks
+
+- Question framing: the analysis answers the stated business or product question.
+- Data selection: sources are appropriate and current enough for the decision.
+- Population: inclusions, exclusions, eligibility rules, and sampling are explicit.
+- Metric definitions: formulas, units, denominators, and timezones are clear and aligned with stakeholder definitions.
+- Baselines: comparison periods, cohorts, and contexts are comparable.
+- Causality: causal wording is backed by experimental or otherwise credible causal evidence.
+
+### Data Quality Checks
+
+- Freshness: the analysis states or can recover the data "as of" date.
+- Completeness: no unexpected missing partitions, segments, rows, or categories.
+- Null handling: key columns have expected null rates or explicit treatment.
+- Deduplication: primary entities are not double counted.
+- Filter verification: filters and WHERE clauses do not silently exclude the population of interest.
+- Join coverage: dimensions, experiments, and reference tables do not drop or multiply important rows.
+
+### Calculation Checks
+
+- Grain: the aggregation level matches the intended analysis grain.
+- Denominators: rates and percentages use the correct population and non-zero denominators.
+- Period alignment: comparisons use equal or explicitly caveated windows.
+- Weighted metrics: averages are weighted correctly when group sizes differ.
+- Subtotals: parts add to totals where categories are mutually exclusive.
+- Units: currency, token, user, request, account, day/week/month, and timezone units are consistent.
+
+### Reasonableness Checks
+
+- Magnitudes are plausible relative to known dashboards, historical reports, or expected product scale.
+- Percentages fall in expected ranges and segment shares sum to about 100% where expected.
+- Trend jumps, drops, flatlines, exact round numbers, and 0% or 100% rates have an explanation.
+- Results do not perfectly confirm the hypothesis without friction or exceptions.
+- Edge cases such as empty segments, new entities, and boundary dates behave sensibly.
+
+### Common Pitfalls
+
+- Join explosion: many-to-many joins silently multiply rows and inflate counts or sums. Compare row counts and distinct primary entities before and after the join, and check whether the right-hand table has multiple rows per join key.
+  Aggregate the right-hand table to the intended grain before joining when needed, use `COUNT(DISTINCT primary_id)` when counting entities through joins,
+  and comment intentional one-to-many joins.
+- Survivorship bias: the analysis only includes entities that exist today and misses deleted, churned, failed, or otherwise absent entities. Ask who is not in the dataset and whether the missing population changes the conclusion.
+- Incomplete period comparison: a partial period is compared with a complete period. Use complete periods, compare the same number of elapsed days, or label the partial-period caveat prominently.
+- Denominator shifting: the eligible population changes between periods or segments. Validate that conversion, churn, activation, attach, and retention rates use stable definitions across compared groups.
+- Average of averages: pre-computed averages are averaged without weighting for group size. Aggregate from raw numerators and denominators or use a weighted average.
+- Timezone mismatch: sources use different timestamp conventions or daily cutoffs. Confirm the analysis standardizes timestamps or explicitly states the timezone and cutoff.
+- Selection bias in segmentation: segments are defined by the outcome being measured. Define comparison groups by pre-treatment characteristics when making lift, causality, or behavior-difference claims.
+- Other statistical traps: Simpson's paradox where aggregate and segment-level trends conflict, correlation presented as causation, small samples,
+  outlier-dominated averages that need medians or distribution views, multiple testing, cherry-picked time ranges, and look-ahead bias.
+
+### Spot-Check Recipes
+
+- Recompute a key metric from raw numerators and denominators.
+- Trace a few individual records through joins, filters, and final output.
+- Reconcile a key total against a trusted dashboard, prior report, or finance source.
+- Reverse engineer a headline number from component metrics, such as users times per-user revenue.
+- Run a one-day, one-segment, or one-entity boundary check to make sure filters and joins behave sensibly.
+- Compare the same metric through an alternate query path when a claim is surprising or high stakes.
+
+### Visualization Checks
+
+- Bar charts should generally start at zero.
+- Comparison charts should use consistent scales unless the scale difference is explicit and justified.
+- Axes, units, legends, and date ranges should be labeled.
+- Category ordering should match the comparison the reader should make.
+- Truncated axes, dual axes, 3D effects, and inconsistent intervals require explicit justification or redesign.
+- Chart titles and annotations should match exactly what the data supports.
+- Titles should state the finding and include date range or scope when needed.
+- Caveats should be visible near the claims they qualify.
+- Number formatting should use appropriate precision and units.
+- Rendered artifacts should be checked in their final form when available, not only in source form.