AltimateAI · anandgupta42 · Mar 4, 2026 · Mar 4, 2026
diff --git a/README.md b/README.md
@@ -1,104 +1,124 @@
 <div align="center">
 
+<img src="docs/docs/assets/images/altimate-code-banner.png" alt="altimate-code" width="600" />
+
 # altimate-code
 
-**The AI coding agent for data teams.**
+**The data engineering agent for dbt, SQL, and cloud warehouses.**
 
-Batteries included for SQL, dbt, and data warehouses.
+An AI-powered CLI with 55+ specialized tools — SQL analysis, schema inspection,
+column-level lineage, FinOps, and PII detection. Connects to your warehouse,
+understands your data, and helps you ship faster.
 
 [![npm](https://img.shields.io/npm/v/@altimateai/altimate-code)](https://www.npmjs.com/package/@altimateai/altimate-code)
 [![PyPI](https://img.shields.io/pypi/v/altimate-engine)](https://pypi.org/project/altimate-engine/)
 [![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)
+[![Docs](https://img.shields.io/badge/docs-altimate--code.sh-blue)](https://altimate-code.sh)
 
 </div>
 
 ---
 
-An AI coding agent with 40+ specialized data tools, column-level lineage, dbt integration, and warehouse connectivity built in -- all available to any AI provider.
+## Why altimate-code?
 
-## Install
+General-purpose coding agents can write SQL, but they don't *understand* it. They can't trace lineage, detect anti-patterns, check PII exposure, or optimize warehouse costs — because they don't have the tools.
+
+altimate-code is a fork of [OpenCode](https://github.com/anomalyco/opencode) rebuilt for data teams. It gives any LLM access to 55+ specialized data engineering tools, 11 purpose-built skills, and direct warehouse connectivity — so the AI works with your actual schemas, not guesses.
+
+## General agents vs altimate-code
+
+| Capability | General coding agents | altimate-code |
+|---|---|---|
+| SQL anti-pattern detection | None | 19 rules with confidence scoring |
+| Column-level lineage | None | Automatic from SQL |
+| Schema-aware autocomplete | None | Indexes your warehouse metadata |
+| Cross-dialect translation | None | Snowflake, BigQuery, Databricks, Redshift |
+| FinOps analysis | None | Credit analysis, expensive queries, warehouse sizing |
+| PII detection | None | Automatic column scanning |
+| dbt integration | Basic file editing | Manifest parsing, test generation, model scaffolding |
+
+## Quick demo
 
 ```bash
-# npm
-npm i -g @altimateai/altimate-code
+# Auto-detect your data stack (dbt projects, warehouse connections, installed tools)
+> /discover
 
-# Homebrew
-brew install AltimateAI/tap/altimate-code
+# Analyze a query for anti-patterns and optimization opportunities
+> Analyze this query for issues: SELECT * FROM orders JOIN customers ON orders.id = customers.order_id
+
+# Translate SQL across dialects
+> /sql-translate this Snowflake query to BigQuery: SELECT DATEADD(day, 7, current_date())
+
+# Generate dbt tests for a model
+> /generate-tests for models/staging/stg_orders.sql
+
+# Get a cost report for your Snowflake account
+> /cost-report
 ```
 
-Then run `altimate-code` to launch the interactive TUI, or `altimate-code run "your prompt"` for one-shot mode.
+## Key Features
 
-## Highlights
+### SQL Anti-Pattern Detection
+19 rules with confidence scoring — catches SELECT *, cartesian joins, non-sargable predicates, correlated subqueries, and more. **100% accuracy** on 1,077 benchmark queries.
 
-| Capability | Details |
-|---|---|
-| **SQL analysis** | 40+ tools -- lint, format, transpile, optimize, safety checks |
-| **Column-level lineage** | Trace data flow through complex SQL and dbt models |
-| **dbt integration** | Manifest parsing, profile management, `+` operator |
-| **Warehouse connectivity** | Snowflake, BigQuery, Redshift, Databricks, Postgres, DuckDB, MySQL, SQL Server |
-| **PII detection** | Classify sensitive columns, flag risky queries |
-| **Query cost prediction** | Estimate execution costs before running |
-| **FinOps** | Credit analysis, query history insights |
-| **AI providers** | 15+ providers -- Anthropic, OpenAI, Gemini, Bedrock, and more |
-| **TUI + headless** | Interactive terminal UI or `altimate-code serve` for CI/CD |
-| **MCP + LSP** | Model Context Protocol and Language Server Protocol support |
+### Column-Level Lineage
+Automatic lineage extraction from SQL. Trace any column back through joins, CTEs, and subqueries to its source. Works standalone or with dbt manifests for project-wide lineage. **100% edge match** on 500 benchmark queries.
 
-## Features
+### FinOps & Cost Analysis
+Credit analysis, expensive query detection, warehouse right-sizing, unused resource cleanup, and RBAC auditing.
 
-### SQL Analysis (40+ tools)
+### Cross-Dialect Translation
+Transpile SQL between Snowflake, BigQuery, Databricks, Redshift, PostgreSQL, MySQL, SQL Server, and DuckDB.
 
-The AI has access to specialized SQL tools that go far beyond what a general coding agent can do:
+### PII Detection & Safety
+Automatic column scanning for PII across 15 categories with 30+ regex patterns. Safety checks and policy enforcement before query execution.
 
-- **Lint & validate** -- Catch anti-patterns like implicit casts, NULL comparisons, unused CTEs
-- **Format** -- Consistent SQL formatting across your team
-- **Transpile** -- Convert between Snowflake, BigQuery, Postgres, T-SQL, MySQL, DuckDB
-- **Optimize** -- Get index suggestions, query rewrites, complexity reduction
-- **Safety checks** -- Detect breaking changes, SQL injection risks, schema violations
-- **Test generation** -- Auto-generate SQL tests for your models
-- **Equivalence checking** -- Verify two queries produce the same results
+### dbt Native
+Manifest parsing, test generation, model scaffolding, incremental model detection, and lineage-aware refactoring. 11 purpose-built skills including medallion patterns, yaml config generation, and dbt docs.
 
-### Column-Level Lineage
+## Install
+
+```bash
+# npm (recommended)
+npm install -g @altimateai/altimate-code
 
-Trace data flow at the column level through complex SQL transformations. Works standalone or with dbt manifests for project-wide lineage across models.
+# Homebrew
+brew install AltimateAI/tap/altimate-code
+```
 
-### dbt Integration
+Then:
 
-- Parse `manifest.json` and `profiles.yml` natively
-- Column-level lineage across dbt models with `+` operator for upstream/downstream selection
-- Execute dbt commands (compile, run, test) directly from the agent
-- Profile management across environments
+```bash
+altimate-code            # Launch the interactive TUI
+altimate-code /discover  # Auto-detect your data stack and go
+```
 
-### Warehouse Connectivity
+`/discover` auto-detects dbt projects, warehouse connections (from `~/.dbt/profiles.yml`, Docker, environment variables), and installed tools (dbt, sqlfluff, airflow, dagster, and more).
 
-Connect directly to your data warehouse -- the AI can query schemas, run SQL, and analyze query history:
+## Agent Modes
 
-- Snowflake (with IAM auth)
-- BigQuery (service account + ADC)
-- Redshift (with IAM auth)
-- Databricks
-- PostgreSQL
-- DuckDB
-- MySQL
-- SQL Server
-- SSH tunneling for secure connections
+Each agent has scoped permissions and purpose-built tools for its role.
 
-### AI Providers
+| Agent | 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 |
+| **Executive** | Business-audience summaries — translates findings into revenue, cost, and compliance impact | Read-only |
 
-Use any model you want. altimate-code supports 15+ providers via the Vercel AI SDK:
+## Supported Warehouses
 
-Anthropic, OpenAI, Google Gemini, Google Vertex AI, Amazon Bedrock, Azure OpenAI, Mistral, Groq, DeepInfra, Cerebras, Cohere, Together AI, Perplexity, xAI, OpenRouter, GitHub Copilot, GitLab
+Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · DuckDB · MySQL · SQL Server
 
-### And more
+First-class support with schema indexing, query execution, and metadata introspection. SSH tunneling available for secure connections.
 
-- Interactive TUI with Solid.js + OpenTUI
-- Headless server mode (`altimate-code serve`)
-- MCP server support (stdio, HTTP, SSE transports)
-- LSP integration (workspace symbols, diagnostics)
-- Session management (continue, fork, export/import)
-- Custom agents and plugins
-- GitHub integration (PR analysis, automated workflows)
-- Token usage stats and cost tracking
+## Works with Any LLM
+
+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
 
 ## Architecture
 
@@ -115,25 +135,6 @@ The CLI handles AI interactions, TUI, and tool orchestration. The Python engine
 
 **Zero-dependency bootstrap**: On first run the CLI downloads [`uv`](https://github.com/astral-sh/uv), creates an isolated Python environment, and installs the engine automatically. No system Python required.
 
-## Development
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full setup guide.
-
-```bash
-git clone https://github.com/AltimateAI/altimate-code.git
-cd altimate-code
-
-# TypeScript
-bun install
-cd packages/altimate-code && bun test
-
-# Python engine
-cd packages/altimate-engine
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
-pytest
-```
-
 ### Monorepo structure
 
 ```
@@ -147,16 +148,32 @@ packages/
 
 ## Documentation
 
-Full docs at [altimate-code.sh](https://altimate-code.sh).
+Full docs at **[altimate-code.sh](https://altimate-code.sh)**.
+
+- [Getting Started](https://altimate-code.sh/getting-started/)
+- [SQL Tools](https://altimate-code.sh/data-engineering/tools/sql-tools/)
+- [Agent Modes](https://altimate-code.sh/data-engineering/agent-modes/)
+- [Configuration](https://altimate-code.sh/configure/model-providers/)
 
-## Contributing
+## Community & Contributing
+
+- **Issues**: [GitHub Issues](https://github.com/AltimateAI/altimate-code/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/AltimateAI/altimate-code/discussions)
+- **Security**: See [SECURITY.md](./SECURITY.md)
 
 Contributions welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) before opening a PR.
 
+```bash
+git clone https://github.com/AltimateAI/altimate-code.git
+cd altimate-code
+bun install
+cd packages/altimate-engine && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
+```
+
 ## Acknowledgements
 
-altimate-code is a fork of [opencode](https://github.com/anomalyco/opencode), the open-source AI coding agent. We build on top of their excellent foundation to add data-team-specific capabilities.
+altimate-code is a fork of [OpenCode](https://github.com/anomalyco/opencode), the open-source AI coding agent. We build on top of their excellent foundation to add data-team-specific capabilities.
 
 ## License
 
-MIT -- see [LICENSE](./LICENSE).
+MIT — see [LICENSE](./LICENSE).