altimate-code 0.4.9 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-03-19
+
+### Added
+
+- Simplified agent modes: 3 primary modes (`builder`, `analyst`, `plan`) replacing 7 — cleaner UX with focused roles (#282)
+- SQL write access control — `builder` prompts for approval on write queries, `analyst` blocks them entirely, destructive SQL (`DROP DATABASE`, `TRUNCATE`) hard-blocked (#282)
+- `core_failure` telemetry with PII-safe input signatures — captures tool failures with masked SQL literals and redacted secrets (#245)
+- `peerDependencies` for database drivers in published npm packages (#273)
+- Comprehensive docs restructuring with new Changelog, Getting Started, and Tools reference pages (#284)
+
+### Fixed
+
+- Replace `escapeSqlString` with parameterized query binds in `finops/schema` modules (#277)
+- Driver error messages now suggest `npm install` instead of `bun add` (#273)
+- System prompt traced only once per session to avoid duplication (#287)
+
+### Changed
+
+- Bump `@altimateai/altimate-core` to 0.2.5 — adds Rust-side failure telemetry with PII masking
+- Removed 5 agent prompts: `executive`, `migrator`, `researcher`, `trainer`, `validator` (#282)
+- README cleanup and updated branding (#288)
+
+## [0.5.0] - 2026-03-18
+
+### Added
+
+- Smooth streaming mode for TUI response rendering (#281)
+- Ship builtin skills to customers via `postinstall` (#279)
+- `/configure-claude` and `/configure-codex` built-in commands (#235)
+
+### Fixed
+
+- Brew formula stuck at v0.3.1 — version normalization in publish pipeline (#286)
+- Harden auth field handling for all warehouse drivers (#271)
+- Suppress console logging that corrupts TUI display (#269)
+
 ## [0.4.9] - 2026-03-18
 
 ### Added

package/README.md

@@ -7,19 +7,16 @@
 
 **The open-source data engineering harness.**
 
-The intelligence layer for data engineering AI — 99+ deterministic tools for SQL analysis,
+The intelligence layer for data engineering AI — 100+ deterministic tools for SQL analysis,
 column-level lineage, dbt, FinOps, and warehouse connectivity across every major cloud platform.
 
 Run standalone in your terminal, embed underneath Claude Code or Codex, or integrate
 into CI pipelines and orchestration DAGs. Precision data tooling for any LLM.
 
-[![npm](https://img.shields.io/npm/v/@altimateai/altimate-code)](https://www.npmjs.com/package/@altimateai/altimate-code)
-[![npm](https://img.shields.io/npm/v/@altimateai/altimate-core)](https://www.npmjs.com/package/@altimateai/altimate-core)
-[![npm downloads](https://img.shields.io/npm/dm/@altimateai/altimate-code)](https://www.npmjs.com/package/@altimateai/altimate-code)
+[![npm](https://img.shields.io/npm/v/altimate-code)](https://www.npmjs.com/package/altimate-code)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![CI](https://github.com/AltimateAI/altimate-code/actions/workflows/ci.yml/badge.svg)](https://github.com/AltimateAI/altimate-code/actions/workflows/ci.yml)
-[![Slack](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://altimate.ai/slack)
-[![Docs](https://img.shields.io/badge/docs-altimateai.github.io-blue)](https://altimateai.github.io/altimate-code)
+[![Slack](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://altimate.studio/join-agentic-data-engineering-slack)
+[![Docs](https://img.shields.io/badge/docs-docs.altimate.sh-blue)](https://docs.altimate.sh)
 
 </div>
 
@@ -29,7 +26,7 @@ into CI pipelines and orchestration DAGs. Precision data tooling for any LLM.
 
 ```bash
 # npm (recommended)
-npm install -g @altimateai/altimate-code
+npm install -g altimate-code
 
 # Homebrew
 brew install AltimateAI/tap/altimate-code
@@ -43,8 +40,6 @@ altimate        # Launch the TUI
 /connect        # Interactive setup — choose your provider and enter your API key
 ```
 
-> **No API key?** Select **Codex** in the `/connect` menu — it's built-in and requires no setup.
-
 Or set an environment variable directly:
 ```bash
 export ANTHROPIC_API_KEY=your_key   # Anthropic Claude
@@ -58,7 +53,9 @@ altimate /discover
 
 `/discover` auto-detects dbt projects, warehouse connections (from `~/.dbt/profiles.yml`, Docker, environment variables), and installed tools (dbt, sqlfluff, airflow, dagster, and more). Skip this and start building — you can always run it later.
 
-> **Zero Python setup required.** On first run, the CLI automatically downloads [`uv`](https://github.com/astral-sh/uv), creates an isolated Python environment, and installs the data engine with all warehouse drivers. No `pip install`, no virtualenv management.
+> **Headless / scripted usage:** `altimate --yolo` auto-approves all permission prompts. Not recommended with live warehouse connections.
+
+> **Zero additional setup.** One command install.
 
 ## Why a specialized harness?
 
@@ -90,7 +87,7 @@ no hallucinated SQL advice, no guessing at schema, no missed PII.
 - **FinOps** — credit consumption, expensive query detection, warehouse right-sizing, idle resource cleanup
 - **PII Detection** — 15 categories, 30+ regex patterns, enforced pre-execution
 
-**Works seamlessly with Claude Code and Codex.** altimate is the data engineering tool layer — use it standalone in your terminal, or mount it as the harness underneath whatever AI agent you already run. The two are complementary.
+**Works seamlessly with Claude Code and Codex.** Use `/configure-claude` or `/configure-codex` to set up integration in one step. altimate is the data engineering tool layer — use it standalone in your terminal, or mount it as the harness underneath whatever AI agent you already run. The two are complementary.
 
 altimate is a fork of [OpenCode](https://github.com/anomalyco/opencode) rebuilt for data teams. Model-agnostic — bring your own LLM or run locally with Ollama.
 
@@ -146,23 +143,19 @@ Teach your AI teammate project-specific patterns, naming conventions, and best p
 
 ## Agent Modes
 
-Each agent has scoped permissions and purpose-built tools for its role.
+Each mode has scoped permissions, tool access, and SQL write-access control.
 
-| Agent | Role | Access |
+| Mode | Role | Access |
 |---|---|---|
-| **Builder** | Create dbt models, SQL pipelines, and data transformations | Full read/write |
-| **Analyst** | Explore data, run SELECT queries, and generate insights | Read-only enforced |
-| **Validator** | Data quality checks, schema validation, test coverage analysis | Read + validate |
-| **Migrator** | Cross-warehouse SQL translation, schema migration, dialect conversion | Read/write for migrations |
-| **Researcher** | Deep-dive analysis, documentation research, and knowledge extraction | Read-only |
-| **Trainer** | Teach project-specific patterns, naming conventions, and best practices | Read + write training data |
-| **Executive** | Business-audience summaries — translates findings into revenue, cost, and compliance impact | Read-only |
+| **Builder** | Create dbt models, SQL pipelines, and data transformations | Full read/write (write SQL prompts for approval; `DROP DATABASE`/`DROP SCHEMA`/`TRUNCATE` hard-blocked) |
+| **Analyst** | Explore data, run SELECT queries, FinOps analysis, and generate insights | Read-only enforced (SELECT only, no file writes) |
+| **Plan** | Outline an approach before acting | Minimal (read files only, no SQL or bash) |
 
-> **New to altimate?** Start with **Analyst mode** — it's read-only and safe to run against production connections.
+> **New to altimate?** Start with **Analyst mode** — it's read-only and safe to run against production connections. Need specialized workflows (validation, migration, research)? Create [custom agent modes](https://docs.altimate.sh).
 
 ## Supported Warehouses
 
-Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · DuckDB · MySQL · SQL Server
+Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · DuckDB · MySQL · SQL Server · Oracle · SQLite
 
 First-class support with schema indexing, query execution, and metadata introspection. SSH tunneling available for secure connections.
 
@@ -172,46 +165,13 @@ Model-agnostic — bring your own provider or run locally.
 
 Anthropic · OpenAI · Google Gemini · Google Vertex AI · Amazon Bedrock · Azure OpenAI · Mistral · Groq · DeepInfra · Cerebras · Cohere · Together AI · Perplexity · xAI · OpenRouter · Ollama · GitHub Copilot
 
-> **No API key?** **Codex** is a built-in provider with no key required. Select it via `/connect` to start immediately.
-
 ## Skills
 
 altimate ships with built-in skills for every common data engineering task — type `/` in the TUI to browse available skills and get autocomplete. No memorization required.
 
-## Architecture
-
-```
-altimate (TypeScript CLI)
-        |
-   @altimateai/altimate-core (napi-rs → Rust)
-   SQL analysis, lineage, PII, safety — 45 functions, ~2ms per call
-        |
-   Native Node.js drivers
-   10 warehouses: Snowflake, BigQuery, PostgreSQL, Databricks,
-   Redshift, MySQL, SQL Server, Oracle, DuckDB, SQLite
-```
-
-The CLI handles AI interactions, TUI, and tool orchestration. SQL analysis is powered by the Rust-based `@altimateai/altimate-core` engine via napi-rs bindings (no Python required). Database connectivity uses native Node.js drivers with lazy loading.
-
-**No Python dependency**: All 73 tool methods run natively in TypeScript. No pip, venv, or Python installation needed.
-
-**dbt-first**: When working in a dbt project, the CLI automatically uses dbt's connection from `profiles.yml` — no separate warehouse configuration needed.
-
-### Monorepo structure
-
-```
-packages/
-  altimate-code/       TypeScript CLI (main entry point)
-  drivers/             Shared database drivers (10 warehouses)
-  dbt-tools/           dbt integration (TypeScript)
-  plugin/              Plugin system
-  sdk/                 SDKs (includes VS Code extension)
-  util/                Shared utilities
-```
-
 ## Community & Contributing
 
-- **Slack**: [altimate.ai/slack](https://altimate.ai/slack) — Real-time chat for questions, showcases, and feature discussion
+- **Slack**: [Join Slack](https://altimate.studio/join-agentic-data-engineering-slack) — Real-time chat for questions, showcases, and feature discussion
 - **Issues**: [GitHub Issues](https://github.com/AltimateAI/altimate-code/issues) — Bug reports and feature requests
 - **Discussions**: [GitHub Discussions](https://github.com/AltimateAI/altimate-code/discussions) — Long-form questions and proposals
 - **Security**: See [SECURITY.md](./SECURITY.md) for responsible disclosure
@@ -220,10 +180,12 @@ Contributions welcome — docs, SQL rules, warehouse connectors, and TUI improve
 
 **[Read CONTRIBUTING.md →](./CONTRIBUTING.md)**
 
-## What's New
+## Changelog
 
-- **v0.4.1** (March 2026) — env-based skill selection, session caching, tracing improvements
-- **v0.4.0** (Feb 2026) — data visualization skill, 99+ tools, training system
+- **v0.5.0** (March 2026) — smooth streaming mode, builtin skills via postinstall, `/configure-claude` and `/configure-codex` commands, warehouse auth hardening
+- **v0.4.9** (March 2026) — Snowflake auth overhaul (all auth methods), dbt tool regression fixes, parallel CI builds
+- **v0.4.2** (March 2026) — yolo mode, Python engine elimination (all-native TypeScript), tool consolidation, path sandboxing hardening, altimate-dbt CLI, unscoped npm package
+- **v0.4.0** (March 2026) — data visualization skill, 100+ tools, training system
 - **v0.3.x** — [See full changelog →](CHANGELOG.md)
 
 ## License

package/package.json

@@ -14,23 +14,63 @@
   "scripts": {
     "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
   },
-  "version": "v0.4.9",
+  "version": "0.5.1",
   "license": "MIT",
   "dependencies": {
-    "@altimateai/altimate-core": "^0.2.3"
+    "@altimateai/altimate-core": "^0.2.5"
   },
   "optionalDependencies": {
-    "@altimateai/altimate-code-linux-x64": "v0.4.9",
-    "@altimateai/altimate-code-windows-arm64": "v0.4.9",
-    "@altimateai/altimate-code-linux-arm64-musl": "v0.4.9",
-    "@altimateai/altimate-code-darwin-x64": "v0.4.9",
-    "@altimateai/altimate-code-windows-x64": "v0.4.9",
-    "@altimateai/altimate-code-linux-x64-musl": "v0.4.9",
-    "@altimateai/altimate-code-darwin-x64-baseline": "v0.4.9",
-    "@altimateai/altimate-code-linux-x64-baseline-musl": "v0.4.9",
-    "@altimateai/altimate-code-linux-x64-baseline": "v0.4.9",
-    "@altimateai/altimate-code-linux-arm64": "v0.4.9",
-    "@altimateai/altimate-code-darwin-arm64": "v0.4.9",
-    "@altimateai/altimate-code-windows-x64-baseline": "v0.4.9"
+    "@altimateai/altimate-code-linux-x64": "0.5.1",
+    "@altimateai/altimate-code-windows-arm64": "0.5.1",
+    "@altimateai/altimate-code-linux-arm64-musl": "0.5.1",
+    "@altimateai/altimate-code-darwin-x64": "0.5.1",
+    "@altimateai/altimate-code-windows-x64": "0.5.1",
+    "@altimateai/altimate-code-linux-x64-musl": "0.5.1",
+    "@altimateai/altimate-code-darwin-x64-baseline": "0.5.1",
+    "@altimateai/altimate-code-linux-x64-baseline-musl": "0.5.1",
+    "@altimateai/altimate-code-linux-x64-baseline": "0.5.1",
+    "@altimateai/altimate-code-linux-arm64": "0.5.1",
+    "@altimateai/altimate-code-darwin-arm64": "0.5.1",
+    "@altimateai/altimate-code-windows-x64-baseline": "0.5.1"
+  },
+  "peerDependencies": {
+    "pg": ">=8",
+    "snowflake-sdk": ">=1",
+    "@google-cloud/bigquery": ">=8",
+    "@databricks/sql": ">=1",
+    "mysql2": ">=3",
+    "mssql": ">=11",
+    "oracledb": ">=6",
+    "duckdb": ">=1",
+    "better-sqlite3": ">=11"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "snowflake-sdk": {
+      "optional": true
+    },
+    "@google-cloud/bigquery": {
+      "optional": true
+    },
+    "@databricks/sql": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    },
+    "oracledb": {
+      "optional": true
+    },
+    "duckdb": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    }
   }
 }

package/postinstall.mjs

@@ -115,6 +115,39 @@ function printWelcome(version) {
   out(bot)
 }
 
+function copyDirRecursive(src, dst) {
+  fs.mkdirSync(dst, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name)
+    const dstPath = path.join(dst, entry.name)
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, dstPath)
+    } else {
+      fs.copyFileSync(srcPath, dstPath)
+    }
+  }
+}
+
+/**
+ * Copy bundled skills to ~/.altimate/builtin/ on every install/upgrade.
+ * The entire directory is wiped and replaced so each release is the single
+ * source of truth. Intentionally separate from ~/.altimate/skills/ which users own.
+ */
+function copySkillsToAltimate() {
+  try {
+    const skillsSrc = path.join(__dirname, "skills")
+    if (!fs.existsSync(skillsSrc)) return // skills not in package (shouldn't happen)
+
+    const builtinDst = path.join(os.homedir(), ".altimate", "builtin")
+
+    // Full wipe-and-replace — each release owns this directory entirely
+    if (fs.existsSync(builtinDst)) fs.rmSync(builtinDst, { recursive: true, force: true })
+    copyDirRecursive(skillsSrc, builtinDst)
+  } catch {
+    // Non-fatal — skills can be installed manually
+  }
+}
+
 /**
  * Write a marker file so the CLI can show a welcome/upgrade banner on first run.
  * npm v7+ silences postinstall stdout, so the CLI reads this marker at startup instead.
@@ -144,6 +177,7 @@ async function main() {
       // On Windows, the .exe is already included in the package and bin field points to it
       // No postinstall setup needed
       if (version) writeUpgradeMarker(version)
+      copySkillsToAltimate()
       return
     }
 
@@ -161,6 +195,7 @@ async function main() {
     // Write marker only — npm v7+ suppresses all postinstall output.
     // The CLI picks up the marker and shows the welcome box on first run.
     if (version) writeUpgradeMarker(version)
+    copySkillsToAltimate()
   } catch (error) {
     console.error("Failed to setup altimate-code binary:", error.message)
     process.exit(1)

package/skills/cost-report/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: cost-report
+description: Analyze Snowflake query costs and identify optimization opportunities
+---
+
+# Cost Report
+
+## Requirements
+**Agent:** any (read-only analysis)
+**Tools used:** sql_execute, sql_analyze, finops_analyze_credits, finops_expensive_queries, finops_warehouse_advice, finops_unused_resources, finops_query_history
+
+Analyze Snowflake warehouse query costs, identify the most expensive queries, detect anti-patterns, and recommend optimizations.
+
+## Workflow
+
+1. **Query SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY** for the top 20 most expensive queries by credits used:
+
+   ```sql
+   SELECT
+       query_id,
+       query_text,
+       user_name,
+       warehouse_name,
+       query_type,
+       credits_used_cloud_services,
+       bytes_scanned,
+       rows_produced,
+       total_elapsed_time,
+       execution_status,
+       start_time
+   FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
+   WHERE start_time >= DATEADD('day', -30, CURRENT_TIMESTAMP())
+     AND execution_status = 'SUCCESS'
+     AND credits_used_cloud_services > 0
+   ORDER BY credits_used_cloud_services DESC
+   LIMIT 20;
+   ```
+
+   Use `sql_execute` to run this query against the connected Snowflake warehouse.
+
+2. **Group and summarize** the results by:
+   - **User**: Which users are driving the most cost?
+   - **Warehouse**: Which warehouses consume the most credits?
+   - **Query type**: SELECT vs INSERT vs CREATE TABLE AS SELECT vs MERGE, etc.
+
+   Present each grouping as a markdown table.
+
+3. **Analyze the top offenders** - For each of the top 10 most expensive queries:
+   - Run `sql_analyze` on the query text to detect anti-patterns (SELECT *, missing LIMIT, cartesian products, correlated subqueries, etc.)
+   - Summarize anti-patterns found and their severity
+
+4. **Classify each query into a cost tier**:
+
+   | Tier | Credits | Label | Action |
+   |------|---------|-------|--------|
+   | 1 | < $0.01 | Cheap | No action needed |
+   | 2 | $0.01 - $1.00 | Moderate | Review if frequent |
+   | 3 | $1.00 - $100.00 | Expensive | Optimize or review warehouse sizing |
+   | 4 | > $100.00 | Dangerous | Immediate review required |
+
+5. **Warehouse analysis** - Run `finops_warehouse_advice` to check if warehouses used by the top offenders are right-sized.
+
+6. **Unused resource detection** - Run `finops_unused_resources` to find:
+   - **Stale tables**: Tables not accessed in the last 30+ days (candidates for archival/drop)
+   - **Idle warehouses**: Warehouses with no query activity (candidates for suspension/removal)
+
+   Include findings in the report under a "Waste Detection" section.
+
+7. **Query history enrichment** - Run `finops_query_history` to fetch recent execution patterns:
+   - Identify frequently-run expensive queries (high frequency × high cost = top optimization target)
+   - Find queries that could benefit from result caching or materialization
+
+8. **Output the final report** as a structured markdown document:
+
+   ```
+   # Snowflake Cost Report (Last 30 Days)
+
+   ## Summary
+   - Total credits consumed: X
+   - Number of unique queries: Y
+   - Most expensive query: Z credits
+
+   ## Cost by User
+   | User | Total Credits | Query Count | Avg Credits/Query |
+   |------|--------------|-------------|-------------------|
+
+   ## Cost by Warehouse
+   | Warehouse | Total Credits | Query Count | Avg Credits/Query |
+   |-----------|--------------|-------------|-------------------|
+
+   ## Cost by Query Type
+   | Query Type | Total Credits | Query Count | Avg Credits/Query |
+   |------------|--------------|-------------|-------------------|
+
+   ## Top 10 Expensive Queries (Detailed Analysis)
+
+   ### Query 1 (X credits) - DANGEROUS
+   **User:** user_name | **Warehouse:** wh_name | **Type:** SELECT
+   **Anti-patterns found:**
+   - SELECT_STAR (warning): Query uses SELECT * ...
+   - MISSING_LIMIT (info): ...
+
+   **Optimization suggestions:**
+   1. Select only needed columns
+   2. Add LIMIT clause
+   3. Consider partitioning strategy
+
+   **Cost tier:** Tier 1 (based on credits used)
+
+   ...
+
+   ## Waste Detection
+   ### Unused Tables
+   | Table | Last Accessed | Size | Recommendation |
+   |-------|--------------|------|----------------|
+
+   ### Idle Warehouses
+   | Warehouse | Last Query | Size | Recommendation |
+   |-----------|-----------|------|----------------|
+
+   ## Recommendations
+   1. Top priority optimizations
+   2. Warehouse sizing suggestions
+   3. Unused resource cleanup
+   4. Scheduling recommendations
+   ```
+
+## Usage
+
+The user invokes this skill with:
+- `/cost-report` -- Analyze the last 30 days
+- `/cost-report 7` -- Analyze the last 7 days (adjust the DATEADD interval)
+
+Use the tools: `sql_execute`, `sql_analyze`, `finops_analyze_credits`, `finops_expensive_queries`, `finops_warehouse_advice`, `finops_unused_resources`, `finops_query_history`.

package/skills/data-viz/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: data-viz
+description: >
+  Build modern, interactive data visualizations and dashboards using code-based
+  component libraries (shadcn/ui, Recharts, Tremor, Nivo, D3, Victory, visx).
+  Use this skill whenever the user asks to visualize data, build dashboards,
+  create analytics views, chart metrics, tell a data story, build a reporting
+  interface, create KPI cards, plot graphs, or explore a dataset — even if they
+  mention PowerBI, Tableau, Streamlit, Metabase, Looker, Grafana, or similar
+  tools. Also trigger when the user says "make a dashboard", "show me the data",
+  "chart this", "visualize trends", "build an analytics page", "data story", or
+  anything involving turning raw data into interactive visual interfaces. If the
+  task involves presenting data visually — this is the skill. Always prefer
+  building a real, interactive, code-based UI over exporting to or recommending
+  a BI platform.
+---
+
+# AI-First Data Visualization
+
+## Philosophy
+
+Build production-quality interactive data interfaces with modern component libraries — no vendor lock-in, embeddable anywhere. When no tool is specified, build code-first. When the user explicitly names a BI tool, use it — only suggest code-first if they ask for options or hit a technical blocker.
+
+## Technology Stack
+
+Full API patterns & code: `references/component-guide.md`
+
+### Framework Priority
+
+1. **React + Tailwind** — Default when JSX/TSX supported
+2. **HTML + CSS + Vanilla JS** — Fallback (use D3 or Chart.js)
+3. **Python (Plotly/Dash)** — Python-only environments only
+
+### Library Selection
+
+| Library | Best For |
+|---------|----------|
+| **shadcn/ui charts** | Default first choice — general dashboards, most chart types |
+| **Recharts** | Line, bar, area, composed, radar — fine-grained control |
+| **Tremor** | KPI cards, metric displays, full dashboard layouts |
+| **Nivo** | Heatmaps, treemaps, choropleth, calendar, Sankey, funnel |
+| **visx** | Bespoke custom viz — D3-level control with React |
+| **D3.js** | Force-directed graphs, DAGs, maps — maximum flexibility |
+| **Victory** | When animation quality matters most |
+
+**Supporting**: Tailwind CSS · Radix UI · Framer Motion · Lucide React · date-fns · Papaparse · lodash
+
+## Building a Visualization
+
+### Step 1: Understand the Data Story
+
+Before code, identify: **What question does the data answer?** Who is the audience (exec → KPIs only, analyst → drill-down, public → narrative)? **What's the ONE key insight?** Design around it.
+
+### Step 2: Choose Chart Type
+
+| Data Relationship | Chart Type | Library |
+|---|---|---|
+| Trend over time | Line, Area | shadcn/Recharts |
+| Category comparison | Bar (horizontal if many) | shadcn/Recharts |
+| Part of whole | Donut, Treemap | shadcn/Nivo |
+| Distribution | Histogram, Box, Violin | Nivo/visx |
+| Correlation | Scatter, Bubble | Recharts/visx |
+| Geographic | Choropleth, Dot map | Nivo/D3 |
+| Hierarchical | Treemap, Sunburst | Nivo |
+| Flow / Process | Sankey, Funnel | Nivo/D3 |
+| Single KPI | Metric card, Gauge, Sparkline | Tremor/shadcn |
+| Multi-metric overview | Dashboard grid of cards | Tremor + shadcn |
+| Ranking | Horizontal bar, Bar list | Tremor |
+| Column/model lineage | Force-directed DAG | D3 |
+| Pipeline dependencies | Hierarchical tree, DAG | D3/Nivo |
+| Multi-dimensional quality | Radar/Spider | Recharts |
+| Activity density over time | Calendar heatmap | Nivo |
+| Incremental change breakdown | Waterfall | Recharts (custom) |
+
+### Step 3: Build the Interface
+
+Start from this layout — remove what the data doesn't need:
+
+```
+┌─────────────────────────────────────────┐
+│ Header: Title + Description + Date Range│
+├─────────────────────────────────────────┤
+│ KPI Row: 3-5 metric cards + sparklines  │
+├─────────────────────────────────────────┤
+│ Primary Visualization (largest chart)   │
+├──────────────────┬──────────────────────┤
+│ Secondary Chart  │ Supporting Chart/Tbl │
+├──────────────────┴──────────────────────┤
+│ Detail Table (sortable, filterable)     │
+└─────────────────────────────────────────┘
+```
+
+A single insight might just be one chart with a headline and annotation. Scale complexity to audience.
+
+### Step 4: Design Principles
+
+- **Data-ink ratio**: Remove chartjunk — unnecessary gridlines, redundant labels, decorative borders
+- **Color with purpose**: Encode meaning (red=bad, green=good, blue=neutral). Max 5-7 colors. Single-hue gradient for sequential data
+- **Typography hierarchy**: Title → subtitle (muted) → axis labels (small) → data labels
+- **Responsive**: `min-h-[VALUE]` on all charts. Grid stacks on mobile
+- **Animation**: Entry transitions only, `duration-300` to `duration-500`. Never continuous
+- **Accessibility**: `aria-label` on charts, WCAG AA contrast, don't rely on color alone
+
+### Step 5: Interactivity & Annotations
+
+**Priority**: Tooltips (every chart) → Filtering → Sorting → Drill-down → Cross-filtering → Export → Annotations
+
+**Annotations** turn charts into stories. Mark: inflection points, threshold crossings (amber), external events (indigo/red), anomalies (red), achievements (green). **Limit 3 per chart.** Implementation: `references/component-guide.md` → Annotation Patterns.
+
+### Step 6: Tell the Story
+
+- **Headline states insight**: "Revenue grew 23% QoQ, driven by enterprise" — not "Q3 Revenue Chart"
+- **Annotate key moments** directly on chart
+- **Contextual comparisons**: vs. prior period, vs. target, vs. benchmark
+- **Progressive disclosure**: Overview first — detail on demand
+
+## Environment-Specific Guidance
+
+| Environment | Approach |
+|---|---|
+| **Claude Artifacts** | React (JSX), single file, default export. Available: `recharts`, `lodash`, `d3`, `lucide-react`, shadcn via `@/components/ui/*`, Tailwind |
+| **Claude Code / Terminal** | Vite + React + Tailwind. Add shadcn/ui + Recharts. Structure: `src/components/charts/`, `src/components/cards/`, `src/data/` |
+| **Python / Jupyter** | Plotly for charts, Plotly Dash for dashboards |
+| **Cursor / Bolt / other IDEs** | Match existing framework. Prefer shadcn/ui if present |
+
+## Anti-Patterns
+
+- Screenshot/static charts — build interactive components
+- Defaulting to BI tools unprompted — build code-first when no tool specified
+- Default matplotlib — always customize in Python
+- Rainbow palettes — use deliberate, meaningful colors
+- 3D charts — almost never appropriate
+- Pie charts > 5 slices — use horizontal bar
+- Unlabeled dual y-axes — use two separate charts
+- Truncated bar axes — always start at zero