create-yss-spec 3.5.2 → 3.5.3

package/template/.codex/skills/data-analytics/package.json

@@ -1,43 +0,0 @@
-{
-  "name": "datascience-mcp-widgets",
-  "version": "0.1.34",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "build": "npm run build:chart && npm run build:table && npm run build:artifact && npm run normalize:assets",
-    "build:artifact": "cross-env INPUT=datascience-artifact-widget.html vite build",
-    "build:chart": "cross-env INPUT=datascience-chart-widget.html vite build",
-    "build:table": "cross-env INPUT=datascience-table-widget.html vite build",
-    "dev": "concurrently \"npm:dev:chart\" \"npm:dev:table\" \"npm:dev:artifact\"",
-    "dev:artifact": "cross-env INPUT=datascience-artifact-widget.html vite build --watch",
-    "dev:chart": "cross-env INPUT=datascience-chart-widget.html vite build --watch",
-    "dev:table": "cross-env INPUT=datascience-table-widget.html vite build --watch",
-    "preview:widgets": "vite --host 127.0.0.1",
-    "normalize:assets": "node scripts/normalize-widget-assets.mjs",
-    "test": "node --test tests/*.test.mjs",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@lexical/history": "^0.44.0",
-    "@lexical/link": "^0.44.0",
-    "@lexical/list": "^0.44.0",
-    "@lexical/markdown": "^0.44.0",
-    "@lexical/react": "^0.44.0",
-    "@lexical/rich-text": "^0.44.0",
-    "@modelcontextprotocol/ext-apps": "^1.7.0",
-    "html-to-image": "1.11.13",
-    "lexical": "^0.44.0",
-    "lucide-react": "^0.468.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "recharts": "^3.8.1"
-  },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "concurrently": "^9.2.1",
-    "cross-env": "^10.1.0",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.8",
-    "vite-plugin-singlefile": "^2.3.3"
-  }
-}

package/template/.codex/skills/data-analytics/scripts/normalize-widget-assets.mjs

@@ -1,75 +0,0 @@
-import { readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { gzipSync } from "node:zlib";
-
-const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const assetDir = resolve(pluginRoot, "assets");
-const maxChunkChars = 120_000;
-const widgetAssets = [
-  "datascience-artifact-widget.html",
-  "datascience-chart-widget.html",
-  "datascience-table-widget.html",
-];
-
-for (const asset of widgetAssets) {
-  const path = resolve(assetDir, asset);
-  const html = readFileSync(path, "utf8");
-  assertBuiltWidgetHtml(asset, html);
-  const normalized = sanitizePublicCopy(html).replace(/[ \t]+$/gm, "");
-  const encoded = gzipSync(Buffer.from(normalized, "utf8"), { level: 9 }).toString("base64");
-  const prefix = `${asset}.gz.b64.part`;
-
-  for (const name of readdirSync(assetDir)) {
-    if (name.startsWith(prefix)) rmSync(resolve(assetDir, name));
-  }
-
-  for (let offset = 0, index = 1; offset < encoded.length; offset += maxChunkChars, index += 1) {
-    const chunk = encoded.slice(offset, offset + maxChunkChars);
-    const chunkName = `${prefix}${String(index).padStart(3, "0")}`;
-    writeFileSync(resolve(assetDir, chunkName), `${chunk}\n`);
-  }
-
-  writeFileSync(path, localDevRedirect(asset));
-}
-
-function assertBuiltWidgetHtml(asset, html) {
-  if (html.includes("Redirecting to the local widget source") || html.includes("window.location.replace(target)")) {
-    throw new Error(
-      `${asset} is still the local development redirect; run npm run build before npm run normalize:assets`,
-    );
-  }
-}
-
-function sanitizePublicCopy(html) {
-  return html
-    .replace(/\bInternal error\b/g, "Widget error")
-    .replace(/\binternal error\b/g, "widget error")
-    .replace(/\bInternal\b/g, "Implementation")
-    .replace(/\binternal\b/g, "implementation");
-}
-
-function localDevRedirect(asset) {
-  const title = asset.includes("artifact")
-    ? "Data Analytics artifact app"
-    : asset.includes("table")
-      ? "Data Analytics table widget"
-      : "Data Analytics chart widget";
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>${title}</title>
-    <script type="module">
-      const target = new URL("../src/${asset}", import.meta.url);
-      target.search = window.location.search;
-      window.location.replace(target);
-    </script>
-  </head>
-  <body>
-    <p>Redirecting to the local widget source for development.</p>
-    <p><a href="../src/${asset}">Open ${title}</a></p>
-  </body>
-</html>
-`;
-}

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/SKILL.md

@@ -1,137 +0,0 @@
----
-name: analyze-data-quality
-description: "Assess analytical data quality: grain, freshness, nulls, duplicates, joins, schema drift and source consistency."
----
-
-# Analyze Data Quality
-
-Assess whether a dataset is trustworthy enough for analysis, modeling,
-dashboards, experiments, or downstream pipelines. Start with the intended use and grain, run the highest-value checks for the data shape, and report concrete evidence, analytical risk, likely causes, and the smallest useful remediation or automated test.
-
-## Skill Configuration
-
-### 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 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. Clarify the quality question and operating context.
-
-   Establish what the dataset represents, the intended unit of analysis, the downstream use, whether the user cares about raw ingestion quality,
-   transformed-model quality, or both, and the comparison baseline such as prior weeks, prior schema, or a trusted reference table. Identify expected grain,
-   primary keys or candidate keys, important date columns, timezone assumptions,
-   domain rules, allowed values, and business thresholds. If context is missing,
-   infer cautiously and label assumptions.
-
-2. Choose an inspectable analysis path.
-
-   When multi-step SQL/Python analysis needs a reproducible narrative, use a companion notebook; a bounded check may provide its query/script and result directly. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.
-
-3. Build a compact profile.
-
-   Start with row count, column count, column names and types, candidate keys,
-   duplicate rates on likely identifiers, min/max timestamps for relevant date columns, null rates, distinct counts for likely categorical columns, and basic numeric summaries for measure columns. Confirm grain before interpreting anomalies; many apparent quality problems are mixed-grain data,
-   partial backfills, late-arriving data, or duplicated joins.
-
-4. Run core quality checks.
-
-   Select checks that match the dataset and task. Default to the most relevant checks across completeness, uniqueness, validity, consistency, integrity,
-   timeliness, volume, and shape. Compare rates, not just counts, and segment by time, source, country, platform, model version, or other key dimensions when that helps distinguish real issues from expected variation.
-
-5. Run shape-specific checks.
-
-   Adapt the checks to the data shape:
-
-   - Event data: duplicate event IDs, future event timestamps, session or user
-     coverage gaps, and abrupt event-mix changes after releases.
-   - Dimension tables: non-unique business keys, orphan surrogate keys, status
-     changes without corresponding timestamps, and unexpected churn in reference
-     values.
-   - Fact tables: mixed grain, impossible measures such as negative revenue or
-     quantity, join blowups to dimensions, and late-arriving or partially loaded
-     partitions.
-   - ML feature or scoring tables: leakage from post-outcome fields, feature
-     sparsity spikes, range shifts after model or feature-store changes, and
-     class-label drift.
-   - Experiment data: duplicate assignments, variant imbalance beyond
-     expectation, exposure without assignment, and events before assignment
-     timestamp.
-
-6. Run temporal and distribution checks when history exists.
-
-   Prioritize temporal diagnostics when the user mentions "after X date",
-   "suddenly", "recently", or "only started appearing". Check first-seen dates,
-   last-seen dates, daily or weekly null-rate trends, duplicate-rate trends, row count trends, category-share shifts, distribution drift, and change points around launches, migrations, incidents, model changes, or backfills.
-
-7. Investigate analytical risks and likely causes.
-
-   Tie each issue to the downstream risk: broken trusted analysis, biased decisions, broken joins, stale dashboards, incorrect experiments, leakage,
-   unreliable model features, or misleading segments. When possible, identify whether the issue is isolated to a source, segment, partition, time window,
-   release, migration, backfill, or upstream pipeline change.
-
-8. Recommend fixes or automated tests.
-
-   Recommend the smallest set of follow-up fixes, monitoring, or automated tests that would materially reduce risk. Suggest automation only when the rule is stable and worth maintaining. Include or save the notebook/query path when code produced the findings.
-
-## Standards
-
-### 按影响选择检查
-
-先确认 grain、关键字段和决策风险，再按需读取 [质量检查方法](references/quality-checks.md)。对实际使用的字段/关联执行验证；不把全部目录作为每个任务的固定步骤。
-
-### Severity
-
-- Critical: breaks trusted analysis, core joins, production dashboards, or key decisions, such as duplicated grain, missing primary keys, or stale production data.
-- High: materially biases downstream decisions, such as large null spikes,
-  category drift in a core dimension, invalid business-rule values, leakage, or severe join coverage loss.
-- Medium: localized or explainable issues that still need documentation,
-  monitoring, or owner follow-up.
-- Low: cosmetic inconsistencies, expected sparsity, or known edge cases that do not materially affect current use.
-
-Do not dump raw profiling output without interpretation. Tie each finding to an analytical risk and likely impact.
-
-### Automated Test Guidance
-
-- Good candidates for automation: primary key uniqueness, not-null checks on required columns, accepted values for stable enums, referential integrity,
-  freshness thresholds, and seasonality-aware row-count or volume bounds.
-- Use caution with hard-coded distribution thresholds on volatile product metrics, strict uniqueness in messy entity-resolution use cases, and recent partitions when late-arriving data is normal.
-- Suggest automated tests only when the expected rule is stable, important, and maintainable.
-
-### Output Standards
-
-Structure the response with:
-
-1. dataset and grain summary
-2. checks performed
-3. findings
-4. temporal or trend anomalies
-5. likely causes and impacted use cases
-6. recommended fixes or automated tests
-7. assumptions and open questions
-
-For each finding, include:
-
-- what failed
-- evidence: counts, rates, segments, and dates
-- why it matters
-- severity and confidence level
-- likely cause when known
-- suggested remediation or automated test
-
-When code was used, retain the exact queries/scripts and results. Use a notebook when complexity or the requested output calls for one.
-
-### Defaults
-
-- Prefer small, high-signal tables over exhaustive dumps.
-- Compare rates, not just counts.
-- Break checks out by time and key segments whenever possible.
-- Normalize strings before judging duplicates or distinct-count spikes.
-- Treat recent partitions carefully when data arrives late.
-- Call out when an anomaly could be caused by a legitimate product launch,
-  experiment, migration, incident, model change, or backfill.
-- Preserve inspectable evidence: SQL, query links, notebook paths, source paths,
-  sample rows, chart outputs, and calculation notes.

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Analyze Data Quality"
-  short_description: "Assess tables and datasets before analysis or publication"
-  default_prompt: "Assess a dataset or table for quality risks before I rely on it for analysis or reporting."
-policy:
-  allow_implicit_invocation: false

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/references/quality-checks.md

@@ -1,29 +0,0 @@
-### Core Checks
-
-- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.
-- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.
-- Validity: type conformance after casting; format checks for IDs, emails, URLs,
-  enums, country codes, and timestamps; range checks for measures, percentages,
-  counts, and dates; allowed-values checks for controlled vocabularies.
-- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.
-- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.
-- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.
-- Volume and shape: row-count drift, distinct-count drift, distribution drift,
-  share-of-total drift for major categories, and new or disappeared categories.
-
-### Specific Check Guidance
-
-- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,
-  casing, formatting, or late updates. Report count, share of affected rows,
-  duplicated keys, and whether duplication is isolated to a time range, source,
-  or segment.
-- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.
-- Domain validity: check malformed identifiers, country codes, timestamps,
-  impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.
-- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.
-- Freshness and schema drift: check row-count changes against recent history,
-  lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.
-- Outliers and distribution shifts: use robust methods such as quantiles, MAD,
-  or IQR before defaulting to z-scores. Check sudden changes in mean, median,
-  variance, zero rate, category share, and long-tail behavior.
-- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.

package/template/.codex/skills/data-analytics/skills/build-dashboard/SKILL.md

@@ -1,148 +0,0 @@
----
-name: build-dashboard
-description: "Build an analytical dashboard or scorecard with defined metrics, filters, source evidence and validation."
----
-
-# Dashboard Building
-
-Use this skill when the user needs a dashboard rather than a report, notebook-only analysis, spreadsheet, or transient chat summary. A good dashboard is summary-first, chart-led, scannable, and organized around what the audience needs to monitor, understand, or act on.
-
-Clarify with the user when a missing input would materially change the dashboard brief, analysis, or recommendation. Otherwise make a reasonable assumption, state it, and proceed.
-
-This skill owns the dashboard brief, delivery-mode selection, metric definitions, source expectations, layout logic, dashboard QA, and handoff. Delivery-specific mechanics belong in the selected dashboard specification.
-
-## Skill Configuration
-
-### 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 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.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-## Workflow
-
-### 1. Define The Dashboard Brief
-
-Understand who will use the dashboard, what they need to measure or monitor, which metrics matter, what surface it should live in, and what constraints could change the build.
-
-Clarify only the inputs that materially affect the dashboard, such as the primary audience, measurement goal, metric scope, delivery surface, refresh expectations, required filters, access constraints, or sharing needs. Decide whether the dashboard is mainly for status monitoring, recurring operating review, or analytical exploration, because that changes the layout, filter design, and validation bar.
-
-Use $gather-business-context when dashboard purpose, metric definitions, operating context, audience expectations, or existing dashboard conventions are not clear enough to design the dashboard well.
-
-### 2. Select The Delivery Surface
-
-Pick the first delivery surface that fits the user's need and available access. If the user specifies the destination or surface, use that instead of the default order.
-
-1. Use a connected BI tool by default. Use the BI surface identified during onboarding or user context; if none is specified, look for an available connected BI solution before choosing another surface.
-2. Use the MCP artifact app when a connected BI build is unavailable, too heavy for the request, or the user needs a compact in-Codex analytical dashboard.
-3. Use HTML when BI and MCP are not suitable and the user needs a portable static dashboard.
-
-Use Streamlit only when the user explicitly asks for it or an existing Streamlit app must be changed.
-
-Read the matching specification before building:
-
-- `../../src/analytics-app-core.md` for shared MCP artifact mechanics, source safety, runtime behavior, and validation helpers.
-- `specifications/bi-platform-dashboard.md` for BI platform dashboards.
-- `specifications/mcp-artifact-dashboard.md` for dashboards rendered by the MCP artifact app.
-- `specifications/html-dashboard.md` for portable static HTML dashboards.
-- `specifications/streamlit-dashboard.md` for Streamlit dashboards.
-
-### 3. Gather And Validate The Data
-
-Do the data work in this order:
-
-- **Find the source path before rendering.** Source discovery is part of dashboard building, not optional enrichment. Identify the source path for the core dashboard metrics. Use `~~structured_data` when the dashboard needs data from a warehouse or another structured data source. Use context lanes such as `~~company_docs`, `~~team_communication`, or `~~dashboards_or_bi` when the dashboard needs business meaning, source-of-truth guidance, metric definitions, or requirements that are not captured in structured data alone.
-- **Use durable dashboard data.** Validate the data before wiring it into the dashboard. Keep final extracts compact and aggregated unless a bounded detail table is part of the dashboard's purpose. Avoid final dashboards that depend on scratch or temporary tables.
-- **Validate trust.** For straightforward dashboards, confirm the source, grain, freshness, and basic reconciliation needed to trust the displayed metrics. Use $analyze-data-quality when data trust is a material risk, such as a new source, recent backfill, complex join, or surprising result.
-- **Resolve time and context anchors.** Before selecting metrics, establish any date anchor, comparison window, latest complete data date, source coverage, or authoritative artifact needed to shape the dashboard, such as a launch date, incident window, or campaign period. Use $gather-business-context when the prompt does not provide it. If still unclear, ask only when it would materially change the dashboard; otherwise state the assumption and shape queries around it.
-- **Stop if source-backed data is unavailable.** Do not render dashboards from fallback, sample, scratch, or partially blocked data unless the user explicitly asked for a mockup. If the core dashboard data is not available, stop the build path and tell the user what source or access is needed. Do not claim a dashboard was created from real data when the source path is missing.
-
-### 4. Define The Metric Model
-
-**Select the metrics.**
-
-When selecting dashboard metrics, classify the measurement object and choose a balanced metric model for that object. Do not use a fixed checklist. Identify which metric families are decision-relevant and which are intentionally out of scope.
-
-Consider these metric families as prompts, not required sections:
-
-- Reach: who or what is using the thing, eligible population, penetration, activation, adoption, coverage.
-- Volume: events, usage, transactions, sessions, requests, units, throughput, frequency.
-- Value: revenue, cost, margin, savings, conversion, retention value, productivity, business outcome.
-- Quality: success, failure, reliability, latency, satisfaction, correctness, safety, support burden.
-- Depth: repeat usage, intensity, feature mix, workflow completion, productionization, maturity, lifecycle stage.
-- Mix: segment, customer type, geography, channel, model/product/version, plan, use case, cohort.
-- Movement: trend, growth, seasonality, pre/post change, benchmark, target, forecast, leading indicators.
-- Risk and constraints: data coverage, source freshness, known blind spots, capacity, compliance, operational limits.
-
-**Build breadth without flattening the dashboard.**
-
-Build enough metric breadth to cover every family that is relevant to the dashboard's measurement object and decision. Keep the default view hierarchical rather than exhaustive: lead with the primary outcome and the highest-signal drivers, then use sections, tabs, filters, detail tables, or supporting views for additional relevant metrics. A selected family can be represented by one or many KPIs, drivers, guardrails, or breakdowns, depending on what the user needs to monitor or diagnose.
-
-Map the selected families into dashboard roles before building: hero metrics for the default view, diagnostic metrics for movement and breakdowns, guardrails for interpretation, and detail metrics for lookup or follow-up.
-
-**Escalate when metric design is the hard part.**
-
-Invoke $design-kpis when this baseline metric-family pass is not enough, such as when the dashboard needs a deeper metric framework, target-setting, formal KPI tradeoff analysis, or clearer definitions than this workflow can safely infer. Pass the dashboard brief, business context, source context, existing metric definitions, and constraints so the recommended metrics fit the audience and use case.
-
-**Keep the data model consistent.**
-
-Build from a reusable compact data model where possible instead of many slightly different tile queries. Keep date logic, filters, dimensions, and metric definitions consistent across cards, charts, and tables so numbers reconcile. Reuse shared metric definitions from the selected tool or semantic layer when available.
-
-### 5. Design The Dashboard Layout
-
-Make the default view useful before the viewer interacts. Arrange the dashboard from summary to detail: lead with the key status or primary KPI context, follow with movement over time, then show the breakdowns that explain the pattern, and put detail tables lower on the page when lookup or operational follow-up is needed.
-
-Use global filters only when they materially update the dashboard-wide view. Prefer a few high-signal controls over a dense filter panel. Keep dashboards visual-heavy and neutral: short labels, direct metric names, sparse annotations, and minimal explanatory text on the main canvas. Use human-readable short date form in visible labels and freshness text; keep ISO timestamps for machine-readable source metadata.
-
-Prefer human-readable short date forms in visible labels and tooltips unless the dashboard needs timestamps for operational precision.
-
-### 6. Choose The Right Charts
-
-Use $visualize-data when the dashboard needs chart selection, visual encoding, or chart polish. This skill should define what each chart needs to communicate; $visualize-data handles the detailed visual design.
-
-Choose the simplest visual that answers the viewer's question. Use a chart when it makes the pattern easier to understand than text or a table.
-
-Put metrics in the same chart only when comparing them directly makes sense. Otherwise, split them into separate charts, KPI cards, or tables.
-
-Use the selected dashboard specification for exact schema, renderer, and interaction requirements.
-
-### 7. Build And Validate In The Selected Surface
-
-Build in the selected surface using its native patterns. Before handoff, check that the dashboard opens cleanly, filters work, charts render, numbers reconcile, access is handled clearly, and performance is acceptable.
-
-Record the source or query path when it would be hard to rediscover later.
-
-### 8. Hand Off The Dashboard
-
-Include the dashboard link or local artifact path, what validation was performed, source or access caveats, and any remaining sharing or operational steps. For MCP artifact dashboards, follow the validation and render handoff rules in `specifications/mcp-artifact-dashboard.md`.
-
-## Dashboard Quality Bar
-
-Before handoff, make sure the dashboard is usable as a measurement surface:
-
-- The default view answers the primary audience question before the viewer interacts.
-- Filters are few, meaningful, and work across the surfaces they claim to control.
-- Cards, charts, and tables reconcile unless differences are clearly labeled.
-- Charts answer clear questions with compatible metrics.
-- Tables support lookup, comparison, or operational follow-up after the chart-led summary.
-- The metric set is broad enough for the measurement object: it covers the relevant families with primary outcomes, important drivers, guardrails, and supporting breakdowns while keeping the default view usable.
-- KPI cards are precisely defined: business-defined metrics include enough visible or nearby context for a reader to understand what is counted, over what window, and under what denominator or eligibility rule.
-- Source freshness, access limits, and caveats are visible where they matter.
-- The layout, labels, and performance work for the selected delivery mode.
-- The selected dashboard specification's validation and render rules were followed.

package/template/.codex/skills/data-analytics/skills/build-dashboard/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Build Dashboard"
-  short_description: "Create source-backed dashboards for monitoring performance, exploring drivers, and acting on metrics."
-  default_prompt: "Build a dashboard for a product or business metric with clear definitions, useful filters, validation, and handoff."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/build-dashboard/specifications/bi-platform-dashboard.md

@@ -1,18 +0,0 @@
-# BI Platform Dashboard Specification
-
-Use this when the dashboard should live in a third-party or managed dashboard platform such as Tableau, Databricks dashboards, Looker, Power BI, Mode, or an managed BI surface. This surface is for long-lived, broadly shared dashboards with platform ownership, permissions, modeled data, refresh, and publishing.
-
-Default to `~~presentation_surface` when the user is editing an existing BI platform dashboard or making a new dashboard that should be shared broadly in a BI platform.
-
-Use `~~structured_data` before dashboard editing when you need to discover source tables, validate SQL, create query permalinks, or inspect sample rows through the relevant source connector when available.
-Use `~~operations_logs` when you need to check partition freshness and lineage.
-
-Preserve the user's requested audience, metrics, filters, data sources,
-ownership, and publication target. Do not switch to MCP artifact or Streamlit unless the user explicitly wants an in-Codex artifact, prototype, local app, or surface that is unsuitable for the BI platform.
-
-## BI Platform Defaults
-
-- Keep the shared dashboard hierarchy: hero metrics first, then trend, then diagnosis, then detail.
-- Use modeled production tables or views for dashboard queries. Do not finalize dashboards that depend on scratch or temporary tables.
-- Use the BI platform's standard widgets by default. Let `~~presentation_surface` decide whether a classic dashboard tab, freeform tab, or platform specific layout is necessary.
-- Report the dashboard, active draft or platform URL, and any unresolved permission, publishing, or sharing constraints in the handoff.

package/template/.codex/skills/data-analytics/skills/build-dashboard/specifications/html-dashboard.md

@@ -1,24 +0,0 @@
-# HTML Dashboard Specification
-
-Use this when the dashboard should be delivered as a portable static HTML file rather than a connected BI dashboard, MCP artifact dashboard, or Streamlit app.
-
-## When To Use
-
-- Use HTML when the user requests a static file or when BI and MCP surfaces are not suitable for the requested handoff.
-- Do not use HTML to bypass missing source access. HTML dashboards must still be source-backed, validated, and reproducible from reviewed data.
-- Prefer MCP artifacts for in-Codex handoff and BI tools for shared operating dashboards with managed refresh.
-
-## Build Shape
-
-- Build a single portable HTML file when practical, with compact embedded data and no external runtime dependency unless the user asked for one.
-- Lead with the dashboard's primary metric context, then trends, diagnostic breakdowns, and detail tables.
-- Keep filters and interactions limited to controls that materially help the reader explore the dashboard.
-- Preserve source provenance in a visible sources or methodology section, including query links, source tables, freshness, definitions, and important filters.
-- Use compact reader-facing number formats in cards, chart labels, axes, tooltips, headings, and narrative text unless exact values are the point.
-- Define business-specific KPI labels in nearby text or a source/methodology section so the dashboard can be understood without reading SQL.
-
-## Validation
-
-- Validate that the HTML opens locally, renders charts and tables, and has no obvious JavaScript errors.
-- Inspect the rendered page at desktop and narrow widths for clipping, overlap, unreadable labels, and broken controls.
-- Confirm that cards, charts, and tables reconcile against the reviewed source extracts before handoff.

package/template/.codex/skills/data-analytics/skills/build-dashboard/specifications/mcp-artifact-dashboard.md

@@ -1,71 +0,0 @@
-# MCP Artifact Dashboard Specification
-
-Use this when the dashboard should be rendered by the Data Analytics MCP app in Codex using `render_artifact`. This is the first-party dashboard surface for bounded, reviewed dashboard payloads that should stay inside the Codex/MCP Apps handoff instead of being created in an external BI platform.
-
-## When To Use
-
-- The user wants an in-Codex dashboard, quick analytical artifact, prototype, or source-backed dashboard readout without creating a Tableau, Databricks, Looker, Power BI, or other BI-platform asset.
-- The dashboard can be represented as a manifest plus bounded snapshot, with compact reviewed datasets. Customer, account, company, segment, and product names are valid analytical dimensions when they are relevant.
-- The primary value is reader handoff and exploration inside Codex, not long-lived BI governance, platform permissions, or scheduled platform refresh.
-
-Prefer a BI platform dashboard for broadly shared production dashboards, third-party platform edits, managed refresh, or platform-specific publishing. Use Streamlit only when the user explicitly asks for Streamlit or an existing Streamlit app must be changed.
-
-## Build Shape
-
-- Build a dashboard manifest with `version: 1`, `surface: "dashboard"`, a reader-facing `title`, and top-level `blocks`. `cards`, `charts`, and `tables` define reusable renderable assets; `blocks` establish the dashboard reading and layout order. Do not emit a shorthand dashboard that declares cards/charts/tables without blocks.
-- Read `../../../src/analytics-app-core.md` for shared MCP payload safety, source provenance, manifest/snapshot, rendering, and chart encoding rules. In particular, do not bind color, series, grouped, or stacked behavior to the same category already used for an axis just to color bars.
-- Follow the current `render_artifact` and `validate_artifact` MCP chart schema instead of duplicating chart-field rules here. Validate the manifest before rendering.
-- Validate the complete manifest and snapshot first with `validate_artifact`, fix validator errors there, and make only one visible `render_artifact` call after validation succeeds. If visible render fails after validation, record the blocker instead of repeated visible retries.
-- Default to built-in artifact blocks for dashboards: `metric-strip`, `chart`, `table`, and `markdown`. Use these native blocks for ordinary KPI strips, trends, bars, rankings, tables, caveats, source notes, and dashboard structure even when custom HTML would be faster to hand-author.
-- Pair it with a compact bounded snapshot containing reviewed aggregate datasets. Avoid row-level payloads unless a small detail table is essential. Use the canonical snapshot shape: `snapshot.datasets` is an object keyed by dataset id, and each value is a plain array of reviewed row objects. Do not put `{columns, rows}` table objects inside `snapshot.datasets`; keep column metadata in `manifest.tables[].columns`.
-- If a required source is blocked by permissions, set the snapshot status to `partial` or `blocked`, populate `snapshot.accessIssues`, put a clean access notice above the dashboard header, and state the exact missing role/table. Do not bury the blocker inside a chart card.
-- Keep the shared hierarchy: hero metrics first, then trend, then diagnosis, then detail.
-- Render the editable dashboard title from `manifest.title`, the last-refresh date, and a Refresh action in the top bar. Treat the top-bar title as canonical.
-- Keep snapshot freshness quiet in the top bar. Render a compact status pill only when the snapshot is fixture, partial, or blocked.
-- KPI cards render as individual cards from one `metrics[]` list. The first metric renders as the large value; later metrics render as labeled secondary badges. Each metric declares `label`, `field`, optional `format`, and `signed: true` for signed changes.
-- When a metric label is not self-defining, include a card description or nearby markdown that explains the metric in reader terms, and include the exact calculation in `source.query.metric_definitions`.
-- Back every chart with a dataset that remains useful beyond the visible chart encoding when safe reviewed context is available. Retain useful dimensions, time/cohort fields, candidate grouping columns, numerators, denominators, benchmarks, ranks, comparison-period values, and adjacent measures so the expanded table supports inspection, filtering, and realistic chart switching.
-- Percent values rendered with `format: "percent"` or `valueFormat: "percent"` must use the same numeric scale consistently in the provided data. Use decimal rates for computed numeric fields, such as `0.149` for `14.9%`, or pass preformatted reader-facing strings where exact display text matters.
-- Use the shared analytics app Recharts v3 chart system for generated app chart types, and keep card width/order persistence, source dialogs, copy actions, table sorting, pagination, and responsive drag behavior aligned with the shared artifact app and validator instead of reimplementing local variants.
-- Generate manifest and snapshot data first. Do not generate bespoke React unless a requested visualization cannot fit the contract.
-- Use `type: "html"` blocks only when the user requests customization, interaction, or a bespoke visual treatment that is not possible with the built-in artifact blocks. Before choosing HTML, verify that native cards, charts, tables, markdown, filters, chart options, or table formatting cannot satisfy the request. Put the raw markup in `html`; HTML blocks auto-size to their content in the MCP artifact renderer.
-- Use `render_artifact` as the default reader and handoff when the payload is safe and within bounds.
-- If the payload is unsafe, too large, or the MCP artifact tool is unavailable after exact discovery, record the blocker and choose another delivery surface.
-
-## App Visual System
-
-- Use the Data Analytics artifact app's design system, chart renderer, and interaction model.
-- Chart and table panels use the shared two-column grid above the stack breakpoint and full-width cards below it.
-- Tables default to dense full-width lookup surfaces, avoid nested inset containers, allow horizontal overflow for wide rows, and paginate bounded detail data instead of vertically scrolling the table body.
-- Movement columns should be explicitly marked with `movement: true`, `semantic: "movement"`, or `role: "movement"`; render signed positive values with `+` and color only movement cells, not neutral current values or shares.
-- Keep generated app styles theme-aware: component styles should consume `--ds-*` aliases, and those aliases should resolve to Figma-backed PUIK/design-system semantic variables such as `--color-surface`, `--color-text-primary`, and `--color-border` before falling back to standalone values.
-- For the outer page canvas and top bar, prefer Codex artifact window surface tokens `--color-token-main-surface-primary` / `--color-background-surface`; dark mode should fall back to Codex `#181818` while cards and charts continue using Figma surface tokens.
-
-## App Controls And Interaction
-
-- Render filters, chart overflow menus, table overflow menus, and the top-bar Share menu with the shared dashboard menu surface.
-- Menu surfaces and item states should use Codex dropdown/list palette aliases: `--ds-menu-bg`, `--ds-menu-text`, `--ds-menu-border`, and `--ds-menu-hover-bg`, not card surface tokens.
-- For menus, prefer Codex dropdown tokens `--color-token-dropdown-background`, `--color-token-dropdown-foreground`, `--color-token-dropdown-border`, and `--color-token-list-hover-background` so hover/open states match Codex chrome.
-- Menus should support smooth open/close motion, click-outside dismissal, Escape dismissal, and keyboard-friendly navigation.
-- Filter controls should hug their label/value content and avoid native OS select styling. Show filters only when they materially control the visible dashboard surfaces.
-- Chart and table cards should expose lightweight card actions without turning the dashboard into a full editor.
-- Non-interactive card surfaces may be draggable; controls, links, inputs, textareas, and menu surfaces should cancel dragging.
-- Drag preview placeholders should remain visible in dark mode by using `--ds-drag-preview-bg` and `--ds-drag-preview-border`, not card surface tokens that can match the artifact background.
-- Inline chart titles and optional descriptions should wrap, avoid clipping, and stay visually part of the card header. Descriptions should be absent by default; include one only when the title is ambiguous or the note materially changes how to read the chart. If the surface exposes `showDescription`, leave it off unless the description is needed.
-
-## App Chart Rendering
-
-- Box plots and waterfalls may require custom shapes or the app's closest supported equivalent. Use custom panels only for deliberate non-native mark systems such as heatmaps and compact leaderboards.
-- Render compact centered legends outside Recharts for multi-series charts so the plot resizes around them.
-- Size standard Recharts charts with the v3 `responsive` chart prop and CSS sizing, not `ResponsiveContainer` wrappers or measured width/height props. The chart body should flex to fill the vertical space left by the header, with `min-height: 0` and bounded max height so it never grows past the card.
-- Use full-space blue-shade cell heatmaps when a dense row-by-column comparison is needed: right-aligned row labels on the left, adaptive column labels below the grid, and hover tooltips for exact values.
-- For complex custom chart types such as heatmaps, leaderboards, funnels, waterfalls, and box plots, let marks stretch when there are only a few rows; when marks would fall below their readable minimum, grow the chart block height instead of introducing vertical scrolling inside the chart body.
-- Let Recharts v3 auto-size Y-axis gutters from formatted visible tick labels with `width="auto"`; use explicit nice ticks when the data domain needs stable labels.
-- When a non-stacked multi-series chart omits explicit colors, use the fallback order blue, purple, green, neutral, orange, yellow, pink, red. Stacked bars use the generated app's blue/purple token-shade fallback set.
-- Disable chart intro animation when deterministic screenshots or hosted previews matter.
-
-## Handoff
-
-- Lead with the MCP artifact result or the exact blocker.
-- Include source/freshness caveats, query or notebook references, and any omitted filters or datasets. For native artifact charts and tables, use the canonical `source` shape: runnable SQL in `source.query.sql`, plain-English summary in `source.query.description`, source predicates in `source.query.filters`, tables in `source.query.tables_used`, and metric formulas in `source.query.metric_definitions`.
-- Do not ask the user to open a localhost server or static file as the primary dashboard handoff when the MCP artifact app can render the payload.