create-yss-spec 3.5.2 → 3.5.3

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

@@ -1,197 +0,0 @@
----
-name: user-context
-description: Load or manage the Data Analytics plugin's durable source-routing preferences, onboarding logic, setup progress, and semantic-layer registry.
----
-
-# User Context
-
-This skill is the Data Analytics plugin's source-routing, semantic-layer registry, setup, and onboarding layer. It loads explicit future source-routing choices, semantic-layer pointers, onboarding progress, and reusable setup obligations for Data Analytics workflows. It does not act as general Data Analytics memory.
-
-## Mandatory Pre-Answer Gate
-
-- 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, 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/data-analytics/onboarding-state.json` only when onboarding state, semantic-layer refresh setup, hero prompt progress, or progressive nudges are relevant.
-
-## Skill Configuration
-
-### Audience And Language
-
-Write for Data Analytics users, not plugin maintainers. This applies to final answers, setup/status readbacks, failure explanations, tool preambles, and mid-turn progress narration.
-
-Translate implementation work into practical Data Analytics impact: what Data Analytics is checking, setting up, saving, or preparing, and why it matters. Avoid implementation terms such as preflight, state file, cache, raw connector id, heartbeat, targetThreadId, schema, API, runtime, metadata, and provider taxonomy unless the user asks for debugging details.
-
-### Source Links
-
-When referencing sources inline, prefer clickable Markdown links over plain bracket labels whenever the source exposes a useful URL. Use the source title, record name, channel/thread, or meeting/date as the link text, for example a clickable Markdown link whose visible text is Meeting notes: May 19 or Slack thread: May 15-21. Use plain text labels only when no useful URL or stable connector-visible link is available, and say (no useful link available) when that absence matters.
-
-## Purpose
-
-User Context keeps two durable Data Analytics-scoped things in a local state file: source-routing choices explicitly selected for future use, and semantic-layer registry pointers. Operational onboarding bookkeeping belongs in a separate JSON state file so `user-context.md` stays small, readable, and cheap to load. Do not use `user-context.md` as a general memory file for arbitrary facts, preferences, output style, caveats, accepted drafts, or "remember this" requests.
-
-Use this skill as the fast preflight for every substantive Data Analytics workflow before ordinary work begins. Use it as the primary workflow when the user asks to onboard, set up, inspect source-routing preferences, inspect semantic layers, create or maintain a semantic layer, or reset Data Analytics setup. If the user asks Data Analytics to remember arbitrary context, explain that general memory is not supported here; persist only an explicit future source-routing choice or a semantic-layer registry pointer produced by semantic-layer setup.
-
-## Reference Loading
-
-`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. 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.
-- Use `plugin-author-config/user-context-config.md` for the copy-ready minimal user-context scaffold.
-- Use `plugin-author-config/source-category-config.json` for source category ids, labels, preferred plugin routes, and relevant helper skills.
-- Use `references/source-category-runtime.md` for workflow-time source attempts, onboarding connector confirmation, plugin-first source setup, ON_USE auth behavior, failure classes, fallback rules, and explicit future source-routing choice storage.
-- Use `references/onboarding-state-template.json` only as the default operational onboarding-state shape; `references/onboarding.md` owns onboarding behavior, transitions, and completion rules.
-- Use `plugin-author-config/automation-config.md`, `references/automation.md`, and `references/semantic-layer/weekly-polling-automation.md` for semantic-layer weekly source polling setup.
-- Use `references/onboarding-examples.md` only to audit or explain onboarding traces. Examples do not override the rules above.
-- Use `scripts/validate_user_context_preflight.py` and `tests/test_state_helpers.py` as the validator and executable regression suite for the Data Analytics user-context preflight contract.
-
-## Skill Experience Guidance
-
-Every user-facing Data Analytics hero workflow used during onboarding should keep its execution guidance in the focused skill that owns the work.
-
-Use the focused skill for the actual analysis, clarification behavior, source-gap handling, and any useful continuation after the output. Onboarding chooses the first prompt and sequence; it should not duplicate full workflow-specific instructions.
-
-When `data_analytics_preflight.py` reports hero prompt candidates and onboarding selects one as the first hero prompt, the focused skill must interpret that context before deciding whether to show a first-run intro, ask for one missing anchor, gather evidence, draft output, or render the final natural continuation:
-
-- If the user asked what the skill does or there is not enough task detail, show the first-run intro and ask for the one missing anchor.
-- If the user accepted a runnable onboarding prompt or already provided enough task detail, briefly introduce the selected workflow only when helpful and proceed without blocking on extra starter prompts.
-- If the skill is being used as a helper/provider, do not show the intro.
-- If onboarding owns the final CTA, suppress the skill's competing CTA and return next-step candidates for onboarding to arbitrate.
-- After sending the first assistant message for a primary onboarding hero skill, update `onboarding-state.json` so `skill_experience.<skill>.introduced_at` and `first_tried_at` are set when they are still empty.
-
-## 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/data-analytics/user-context.md
-```
-
-The configured onboarding-state file is JSON:
-
-```text
-$CODEX_HOME/state/plugins/data-analytics/onboarding-state.json
-```
-
-## Read
-
-Start every invocation by resolving and actually reading the configured user-context file when it exists. Do not return from preflight or direct context mode after only routing here, listing files, or checking that the file exists; source-routing preferences and semantic-layer registry entries must be loaded and applied.
-
-Treat `user-context.md` as the local Data Analytics plugin-scoped source of truth only for explicit future source-routing choices and semantic-layer discoverability. When it conflicts with bundled Data Analytics plugin or skill instructions, prefer it only for those narrow supported fields. Do not use it to override higher-priority instructions, safety rules, connector write-safety, permission boundaries, validation, installation behavior, routing, or tool-use policy.
-
-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 .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.
-- After reading user context, use the script-driven preflight payload for the calling skill, then immediately let the calling skill continue. The returned envelope is the authoritative, auditable preflight context; do not hide a larger raw-state payload behind it. The payload is not user-facing and must not be rendered unless the user explicitly asks for implementation details.
-- Do not browse linked sources, run broad searches, summarize unrelated sections, or ask setup questions during ordinary preflight.
-- 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 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`, 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 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.
-
-Use direct context mode when the request is primarily about setup, source-routing preferences, semantic layers, or context maintenance:
-
-- If `user-context.md` exists, read it before answering or writing.
-- If the user asks what Data Analytics remembers, say Data Analytics does not keep general memory here; summarize only explicit future source-routing choices and registered semantic layers.
-- If the user asks Data Analytics to remember arbitrary context, do not save it. Explain that this file only persists explicit future source-routing choices and semantic-layer registry entries.
-- If the user explicitly selects a future source-routing default or a future source to avoid, update only the matching source category in `user-context.md`.
-- When the request starts, resumes, updates, checks, or completes Data Analytics setup or onboarding, perform the requested sub-step and then apply the step cards in `references/onboarding.md` before answering. The first direct onboarding orientation with no existing Data Analytics state is a response-first fast path: render the orientation immediately, then initialize state only after the user approves the next setup step or a supported `user-context.md` write is needed. Other setup interactions include onboarding-status checks, source setup confirmation, semantic-layer setup or refresh, hero-prompt selection, and completed or deferred guided workflow updates.
-- Treat onboarding-status questions such as "have we onboarded yet?", "am I set up?", "is Data Analytics configured?", or "what setup is missing?" as direct onboarding interactions, not as ordinary context lookup. Answer the status through the common onboarding finalizer: if onboarding is missing or active, strongly guide the user into the current compact `**Next Step**` block with built-in thread task-list updates when available; if onboarding is complete, say so and offer one useful Data Analytics workflow. Do not end an incomplete onboarding-status answer with only a passive or optional setup suggestion.
-
-Outside explicit linked-source refresh, semantic-layer setup, or semantic-layer refresh work, retrieve linked Google Docs, Drive files, Notion pages, or other resources only when they are accessible through available connectors or explicit local APIs and the user asked to inspect or refresh that source. Do not use browser automation, in-app browser, or Computer Use as fallback retrieval paths for ordinary context-source retrieval.
-
-## Onboarding
-
-Use `references/onboarding.md` as the source of truth when the user asks what Data Analytics can do, asks to set up Data Analytics, invokes onboarding, asks whether onboarding is complete, asks for Data Analytics TODOs, asks which sources Data Analytics can try, asks to create or inspect a semantic layer during onboarding, or when `onboarding-state.json` says onboarding is active and a nudge is due. During ordinary preflight, do not show full onboarding; parse only relevant JSON fields and return the hard setup obligation or one source/semantic-layer gap note when applicable, then let the calling skill continue. When onboarding is already active during an ordinary workflow, do not ask whether to start onboarding. If core onboarding is incomplete, answer only directly requested Data Analytics work best effort and direct the user back to the next unresolved core setup item. If core onboarding is complete, preserve the workflow's own final natural continuation and mention resuming guided onboarding only as a short non-competing note when directly useful. During the first direct onboarding message with no state, render Step 1 directly from `references/onboarding.md` without creating scaffold files first.
-
-When direct context work happens while onboarding is missing or active, apply the current step-card continuation in `references/onboarding.md` before finalizing. This includes source setup confirmation, onboarding-status checks, source-routing preference changes, semantic-layer setup or refresh, hero prompt selection, and skill-experience updates. A recap of the just-completed sub-step is not sufficient while onboarding is active unless onboarding is complete, quiet, or stopped by the user. During source setup confirmation, surface unresolved `structured_data`, `team_communication`, and `company_docs` before optional source categories and do not downgrade installable core routes into quiet optional deferrals.
-
-When a focused workflow is run from the visible onboarding path, call preflight with `--request-mode guided_onboarding_workflow` so the workflow can answer normally without adding a redundant onboarding reminder. Focused hero skills own their own first-run banner, anchor rules, prompt execution behavior, and next-step guidance. Onboarding owns the first prompt choice, extra prompt sequencing, and state updates.
-
-## Action-Oriented Continuation
-
-Default Data Analytics outputs should be useful launchpads, not dead ends. In almost all cases, after answering the user's immediate request, add one concise next step that helps them act on the result. Good next steps continue the same workflow by iterating on the analysis, validating one gap, creating the next artifact, checking one missing source, setting up or refreshing a semantic layer, or showing one remaining hero prompt when onboarding owns the final CTA. Do not recommend moving to another Data Analytics skill as a generic continuation; route elsewhere only when the user's request has clearly changed or the current workflow's own routing rules say another skill owns the job.
-
-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 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
-
-Write only two kinds of durable Data Analytics user context to `user-context.md`:
-
-- explicit future source-routing choices, such as `Prefer: Databricks` or `Avoid: Snowflake`, under the matching source category;
-- semantic-layer registry pointers under `# Semantic Layers`.
-
-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 .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 .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:
-
-```md
-# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer: Databricks
-- Avoid: Snowflake
-```
-
-Use this semantic-layer registry shape:
-
-```md
-# Semantic Layers
-
-- Area: Customer onboarding
-  - Skill Name: api-semantic-layer
-  - Skill Path: /absolute/path/to/api-semantic-layer
-  - Source Inventory Path: /absolute/path/to/api-semantic-layer/references/source-inventory.md
-  - Last Updated: 2026-06-01
-```
-
-## First Run Setup
-
-Use first-run setup in direct context mode when `user-context.md` is missing, unreadable, or lacks the bundled minimal scaffold. For a pure onboarding or "what can Data Analytics do?" request, show the orientation first and defer scaffold creation. If a supported future source-routing choice or semantic-layer pointer needs persistence, create the scaffold first, then update only the relevant supported section.
-
-For first-run setup after the first orientation, use `scripts/init_user_context_state.py` to create missing local state files when possible, then read `plugin-author-config/user-context-config.md` and treat the bundled source category sections as a minimal routing scaffold, not a questionnaire. Read `references/onboarding.md` before presenting first-run orientation, source setup confirmation guidance, semantic-layer setup guidance, or hero prompt sequencing. Read the relevant hero skill's experience guidance before presenting that skill's intro, prompt, or anchor rule.
-
-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 .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.
-5. Continue the user's original request using the updated supported context.
-
-If the user declines setup, continue the original request without durable source-routing preferences or semantic-layer registry. Keep the explanation user-facing; do not describe internal files unless the user asks.

package/template/.codex/skills/data-analytics/skills/user-context/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Data Analytics User Context"
-  short_description: "Manage source routing, onboarding, and semantic layers"
-  default_prompt: "Read Data Analytics source-routing preferences, apply semantic-layer registry entries, and help me finish analytics setup."
-policy:
-  allow_implicit_invocation: false

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

@@ -1,26 +0,0 @@
-# Data Analytics Automation Config
-
-Plugin authors edit this file when adding, removing, renaming, or clarifying default Data Analytics onboarding automations. Keep setup mechanics, thread creation, pinning, readback, duplicate cleanup, failure handling, and automation tool usage in `../references/automation.md`.
-
-The default automations are offered during Data Analytics onboarding when their prerequisites are met. Later journey automations are offered only when a focused workflow reaches the right point. This config should stay friendly for plugin authors: name the automation, say how often it should run, and write the instructions. The dedicated thread title is derived from `Name`. Runtime mechanics such as heartbeat kind, RRULE conversion, tool calls, target thread ids, pinning, readback, cleanup, and state metadata belong in `../references/automation.md`.
-
-## Automation Entry Shape
-
-Every automation entry must use this shape:
-
-```md
-`automation_id`
-
-- Name: human-facing automation name.
-- Frequency: Data Analytics user-facing cadence and local time.
-- 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/data-analytics/onboarding-state.json`.
-
-## Default Automations
-
-`weekly_semantic_layer_refresh`
-- Name: Semantic Layer Weekly Source Polling.
-- Frequency: weekly on Mondays at 9:00 AM local time.
-- Instructions: Check the saved semantic-layer source inventory for source-backed changes, propose safe updates, validate any edited semantic-layer skill, and report conflicts, skipped sources, or permission gaps.

package/template/.codex/skills/data-analytics/skills/user-context/plugin-author-config/source-category-config.json

@@ -1,51 +0,0 @@
-{
-  "schema_version": "data_analytics_source_category_config.v1",
-  "description": "Author-owned Data Analytics source category catalog. Runtime source resolution, preferred plugin routing hints, relevant helper skills, fallback, and durable user-approved preference rules live in ../references/source-category-runtime.md. Skills decide which categories they attempt. User-specific source-routing preferences and semantic-layer registry pointers live in $CODEX_HOME/state/plugins/{marketplace_id}/{plugin_id}/user-context.md.",
-  "categories": {
-    "structured_data": {
-      "label": "Data warehouse",
-      "preferred_plugins": ["Databricks", "BigQuery", "Snowflake"],
-      "relevant_skills": []
-    },
-    "team_communication": {
-      "label": "Team communication",
-      "preferred_plugins": ["Slack", "Teams"],
-      "relevant_skills": []
-    },
-    "company_docs": {
-      "label": "Company docs",
-      "preferred_plugins": ["Google Drive", "SharePoint", "Notion"],
-      "relevant_skills": []
-    },
-    "dashboards_bi": {
-      "label": "Dashboards and BI",
-      "preferred_plugins": ["ThoughtSpot", "Omni Analytics", "Metabase"],
-      "relevant_skills": []
-    },
-    "behavior_signals": {
-      "label": "Behavior signals",
-      "preferred_plugins": ["Amplitude", "Mixpanel"],
-      "relevant_skills": []
-    },
-    "notebook_lab": {
-      "label": "Notebook lab",
-      "preferred_plugins": ["Hex", "Deepnote"],
-      "relevant_skills": []
-    },
-    "email_context": {
-      "label": "Email context",
-      "preferred_plugins": ["Gmail", "Outlook Email"],
-      "relevant_skills": []
-    },
-    "calendar_context": {
-      "label": "Calendar context",
-      "preferred_plugins": ["Google Calendar", "Outlook Calendar"],
-      "relevant_skills": []
-    },
-    "code_repository": {
-      "label": "Code repository",
-      "preferred_plugins": ["GitHub"],
-      "relevant_skills": []
-    }
-  }
-}

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

@@ -1,66 +0,0 @@
-# Data Analytics User Context Config
-
-Plugin authors edit this file when clarifying the minimal Data Analytics `user-context.md` scaffold. Keep onboarding mechanics in `../references/onboarding.md`, source-routing behavior in `../references/source-category-runtime.md`, and placeholder insertion in `../scripts/init_user_context_state.py`.
-
-This file is intentionally narrow. `user-context.md` stores only durable Data Analytics source-routing choices explicitly selected for future use plus semantic-layer registry entries. Do not add general memory, output preferences, action-orientation preferences, connector readiness, onboarding state, automation setup details, copied source inventories, or arbitrary saved links here.
-
-## User Context Shape
-
-The initializer copies the content below `## Default User Context` into the user-facing file. Keep source category ids aligned with `source-category-config.json`. Each source category keeps blank `Prefer` and `Avoid` rows until the user explicitly selects a future routing default or a future source to avoid.
-
-## Default User Context
-
-# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer:
-- Avoid:
-
-## team_communication
-
-- Prefer:
-- Avoid:
-
-## company_docs
-
-- Prefer:
-- Avoid:
-
-## dashboards_bi
-
-- Prefer:
-- Avoid:
-
-## behavior_signals
-
-- Prefer:
-- Avoid:
-
-## notebook_lab
-
-- Prefer:
-- Avoid:
-
-## email_context
-
-- Prefer:
-- Avoid:
-
-## calendar_context
-
-- Prefer:
-- Avoid:
-
-## code_repository
-
-- Prefer:
-- Avoid:
-
-# Semantic Layers
-
-Store durable semantic-layer registry entries that future Data Analytics runs should load before choosing metrics, tables, joins, or definitions.
-
-status: not provided

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

@@ -1,69 +0,0 @@
-# Data Analytics Onboarding Automations
-
-Use this reference only when Data Analytics onboarding is setting up, checking, repairing, or later offering recurring Data Analytics automations. Keep this file as the runtime owner for automation setup. Keep ordinary onboarding flow, copy, and workflow choices in onboarding.md.
-
-The automation catalog is ../plugin-author-config/automation-config.md. Always read it before setup and use its Name, Frequency, and Instructions; do not duplicate focused-skill workflow rules in automation prompts.
-
-## Default Setup
-
-After the current semantic layer has a stable target skill path and a usable, pollable source inventory, Data Analytics offers exactly one refresh automation unless the user skips or defers it:
-
-| Automation id | Thread | Model/thinking | Schedule | Prompt | Kickoff |
-| --- | --- | --- | --- | --- | --- |
-| `weekly_semantic_layer_refresh` | Dedicated projectless thread titled `Semantic Layer Weekly Source Polling`, pinned | `model="gpt-5.5"`, `thinking="xhigh"` when supported | Weekly Monday 9:00 AM local time | Configured `Instructions` from `automation-config.md` | Send one setup kickoff to the pinned thread |
-
-The refresh automation is optional: do not create it during the first onboarding orientation, before those prerequisites exist, or without explicit user approval unless the user already directly instructed Data Analytics to set up weekly polling.
-
-If a tool cannot set model or thinking for heartbeat automations, set them on the target thread or Semantic Layer Weekly Source Polling kickoff when supported, record the limitation in onboarding state, and do not fall back to `gpt-5`.
-
-The onboarding thread is never an automation target. Do not rename, pin, unpin, attach a heartbeat to, or send kickoff messages into the current onboarding thread while setting up Data Analytics automations. Only the dedicated automation target thread may be renamed, pinned, and attached to heartbeat automations.
-
-## Fast Setup Checklist
-
-After the user approves Data Analytics automation setup:
-
-1. Discover `automation_update` and the thread tools: `create_thread`, `set_thread_title`, `set_thread_pinned`, and `send_message_to_thread`. Use `list_threads` only to reuse a clearly matching existing pinned automation thread with the exact configured title; never treat the current onboarding thread as reusable, even if it has been accidentally renamed or pinned.
-2. Read `../plugin-author-config/automation-config.md` and identify the default automation id, name, frequency, and prompt.
-3. For the default automation, create or reuse its dedicated projectless thread, capture the returned or reused thread id, set the exact configured title on only that thread id, pin only that thread id, and keep its thread id.
-4. Create or update the automation with `kind="heartbeat"`, `destination="thread"`, the configured prompt, the configured cadence converted to the narrowest supported RRULE, `status="ACTIVE"`, and the exact `targetThreadId` of the dedicated automation thread.
-5. Read back `$CODEX_HOME/automations/<automation_id>/automation.toml` when available. Confirm `kind = "heartbeat"`, the stored `target_thread_id` matches the pinned thread, the prompt and cadence match the config, and no cron-only workspace fields are present. Use `automation_update mode=view` only when file readback is unavailable.
-6. Send one kickoff message only to the pinned Semantic Layer Weekly Source Polling thread after readback succeeds: run the configured semantic-layer source polling instructions now.
-7. Update `onboarding-state.json` with only operational metadata: canonical automation id, `kind`, readback status, target thread id/title, target thread pin status, and semantic-layer refresh kickoff status/thread info. Do not copy semantic-layer content, polling results, source URLs, or source data into onboarding state.
-8. Stop. Report the concise setup result and move to the first hero prompt step. Do not inspect hero workflow skill files or run another guided workflow until the user picks one.
-
-## Readiness Rules
-
-Only say the default automation setup is complete when the default automation is heartbeat-backed, targeted to its dedicated pinned thread, read back successfully, and the Semantic Layer Weekly Source Polling kickoff has started or was explicitly deferred by the user.
-
-Do not mark setup complete after a plain cron automation, an automation attached to the onboarding thread, missing readback, missing target thread metadata, or a missing first Semantic Layer Weekly Source Polling kickoff.
-
-If `automation_update` cannot persist a dedicated heartbeat thread after one repair attempt, use the fallback path: leave semantic-layer refresh manual, record the limitation as `environment_api_limitations`, and report it as a fallback rather than full setup.
-
-Ask for explicit user approval before deleting automations, pausing automations, unpinning threads, or cleaning up duplicate/stale Data Analytics automation resources.
-
-## Thin Prompts
-
-Automation prompts and kickoff prompts should be thin launchers:
-
-- Semantic Layer Weekly Source Polling: load and follow `semantic-layer/weekly-polling-automation.md` in scheduled source polling mode, using that reference's source inventory, update boundary, validation, and output contract.
-
-Do not paste source precedence, evidence standards, update boundaries, validation commands, output examples, model names, reasoning effort, or focused-skill workflow contracts into automation prompts or kickoff messages.
-
-## User-Facing Result
-
-When setup succeeds, use this shape and continue to the next onboarding step:
-
-```md
-Semantic-layer refresh is set up and read back cleanly.
-
-- **Semantic Layer Weekly Source Polling**: checks the saved source inventory each week and posts its review summary in the pinned **Semantic Layer Weekly Source Polling** thread. I also kicked off the first source polling run in that thread.
-```
-
-When setup cannot be completed, use this shape and continue to the next onboarding step:
-
-```md
-Weekly semantic-layer refresh is still manual because the automation could not be persisted and read back cleanly.
-
-- **Current setup**: the semantic layer and source inventory are saved.
-- **Refresh status**: manual for now. I recorded the setup blocker so refresh can be repaired later without repeating semantic-layer setup.
-```