Run interactively, automate in CI, embed in DAGs, or mount as the tool layer for your AI agents.
+
+- :material-console:{ .lg .middle } **Terminal**
+
+ ---
+
+ Interactive TUI with 99+ tools, autocomplete for skills, and persistent memory across sessions.
+
+- :material-pipe-disconnected:{ .lg .middle } **CI Pipeline**
+
+ ---
+
+ Headless mode for automated validation, schema diffing, and anti-pattern checks in GitHub Actions or any CI system.
+
+- :material-graph:{ .lg .middle } **Orchestration DAGs**
+
+ ---
+
+ Call the harness from Airflow, Dagster, or Prefect tasks to add data quality gates and lineage checks to your pipelines.
+
+- :material-robot-outline:{ .lg .middle } **Data Agent Harness**
+
+ ---
+
+ Mount altimate as the tool layer underneath Claude Code, Codex, or any AI agent — giving it deterministic, warehouse-aware capabilities.
+
+
Each agent has scoped permissions and purpose-built tools for its role.
First-class support for 8 data platforms.
First-class support for 8 warehouses. Migrate, compare, and translate across platforms — not locked to one vendor.
@@ -171,8 +204,8 @@ npm install -g altimate-code
-**Documentation** — [Getting Started](getting-started.md) | [Data Engineering](data-engineering/agent-modes.md) | [Configuration](configure/config.md)
+**Documentation** — [Getting Started](getting-started.md) | [Guides](data-engineering/guides/cost-optimization.md) | [Tools](data-engineering/tools/sql-tools.md) | [Configuration](configure/config.md)
-**Develop & Extend** — [SDK](develop/sdk.md) | [Plugins](develop/plugins.md) | [Server API](develop/server.md)
+**Extend** — [SDK](develop/sdk.md) | [Plugins](develop/plugins.md) | [Server API](develop/server.md)
diff --git a/docs/docs/llms.txt b/docs/docs/llms.txt
new file mode 100644
index 0000000000..70eaa8733f
--- /dev/null
+++ b/docs/docs/llms.txt
@@ -0,0 +1,42 @@
+# altimate-code llms.txt
+# AI-friendly documentation index for altimate-code
+# Generated: 2026-03-17 | Version: v0.4.1
+# Source: https://altimateai.github.io/altimate-code
+
+> altimate-code is an open-source data engineering harness — 99+ tools for building, validating, optimizing, and shipping data products. Use in your terminal, CI pipeline, orchestration DAGs, or as the tool layer for your data agents. Includes a deterministic SQL Intelligence Engine (100% F1 across 1,077 queries), column-level lineage, FinOps analysis, PII detection, and dbt integration. Works with any LLM provider. Local-first, MIT-licensed.
+
+## Get Started
+
+- [Quickstart (5 min)](https://altimateai.github.io/altimate-code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes.
+- [Full Setup Guide](https://altimateai.github.io/altimate-code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough.
+- [Network & Proxy](https://altimateai.github.io/altimate-code/network/): Proxy configuration, CA certificate setup, firewall requirements.
+
+## Data Engineering
+
+- [Agent Modes](https://altimateai.github.io/altimate-code/data-engineering/agent-modes/): 7 specialized agents — Builder (full read/write), Analyst (read-only enforced), Validator, Migrator, Researcher, Trainer, Executive — each with scoped permissions and purpose-built tool access.
+- [Training Overview](https://altimateai.github.io/altimate-code/data-engineering/training/): How to teach altimate project-specific patterns, naming conventions, and corrections that persist across sessions and team members.
+- [Team Deployment](https://altimateai.github.io/altimate-code/data-engineering/training/team-deployment/): How to commit training to git so your entire team inherits SQL conventions automatically.
+- [SQL Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/sql-tools/): 9 SQL analysis tools with 19 anti-pattern rules. 100% F1 accuracy on 1,077 benchmark queries.
+- [Schema Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/schema-tools/): Warehouse schema introspection, metadata indexing, and column-level analysis tools.
+- [FinOps Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/finops-tools/): Credit analysis, expensive query detection, warehouse right-sizing, unused resource cleanup, RBAC auditing.
+- [Lineage Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/lineage-tools/): Column-level lineage extraction from SQL. 100% edge-match accuracy on 500 benchmark queries.
+- [dbt Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/dbt-tools/): dbt manifest parsing, test generation, model scaffolding, incremental logic detection.
+- [Warehouse Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/warehouse-tools/): Direct connectivity to Snowflake, BigQuery, Databricks, PostgreSQL, Redshift, DuckDB, MySQL, SQL Server.
+- [Memory Tools](https://altimateai.github.io/altimate-code/data-engineering/tools/memory-tools/): Session memory, persistent corrections, and team training storage.
+- [Cost Optimization Guide](https://altimateai.github.io/altimate-code/data-engineering/guides/cost-optimization/): Step-by-step warehouse cost reduction with before/after SQL examples and savings estimates.
+- [Migration Guide](https://altimateai.github.io/altimate-code/data-engineering/guides/migration/): Cross-warehouse SQL migration with side-by-side examples.
+- [CI & Headless Mode](https://altimateai.github.io/altimate-code/data-engineering/guides/ci-headless/): Non-interactive use in GitHub Actions, scheduled jobs, and pre-commit hooks.
+
+## Configure
+
+- [Configuration Overview](https://altimateai.github.io/altimate-code/configure/config/): Full altimate-code.json schema, value substitution, project structure, experimental flags.
+- [Providers](https://altimateai.github.io/altimate-code/configure/providers/): 17 LLM provider configurations with JSON examples: Anthropic, OpenAI, Google Gemini, Vertex AI, Amazon Bedrock, Azure OpenAI, Mistral, Groq, Ollama, and more.
+- [Agent Skills](https://altimateai.github.io/altimate-code/configure/skills/): How to configure, discover, and add custom skills.
+- [Permissions](https://altimateai.github.io/altimate-code/configure/permissions/): Permission levels, pattern matching, per-agent restrictions, deny rules for destructive SQL.
+- [Tracing](https://altimateai.github.io/altimate-code/configure/tracing/): Local-first observability — trace schema, span types, live viewing, remote OTLP exporters, crash recovery.
+- [Telemetry](https://altimateai.github.io/altimate-code/configure/telemetry/): 25 anonymized event types, privacy guarantees, opt-out instructions.
+
+## Reference
+
+- [Security FAQ](https://altimateai.github.io/altimate-code/security-faq/): 12 Q&A pairs on data handling, credentials, permissions, network endpoints, and team hardening.
+- [Troubleshooting](https://altimateai.github.io/altimate-code/troubleshooting/): 6 common issues with step-by-step fixes, including Python bridge failures and warehouse connection errors.
diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md
new file mode 100644
index 0000000000..a0292ffaad
--- /dev/null
+++ b/docs/docs/quickstart.md
@@ -0,0 +1,102 @@
+---
+description: "Install altimate-code and run your first SQL analysis. The open-source data engineering harness — 99+ tools for building, validating, optimizing, and shipping data products."
+---
+
+# Quickstart
+
+> **You need:** npm 8+ or Homebrew. An API key for any supported LLM provider — or use Codex (built-in, no key required).
+
+---
+
+## Step 1 — Install
+
+```bash
+# npm (recommended)
+npm install -g @altimateai/altimate-code
+
+# Homebrew
+brew install AltimateAI/tap/altimate-code
+```
+
+> **Zero Python setup required.** On first run, the CLI automatically downloads `uv`, creates an isolated Python environment, and installs the data engine. No `pip install`, no virtualenv management.
+
+---
+
+## Step 2 — Configure Your LLM
+
+```bash
+altimate # Launch the TUI
+/connect # Choose your provider and enter your API key
+```
+
+Or set an environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=your-key-here # Anthropic Claude (recommended)
+export OPENAI_API_KEY=your-key-here # OpenAI
+```
+
+Minimal config file option (`altimate-code.json` in your project root):
+
+```json
+{
+ "providers": {
+ "anthropic": {
+ "apiKey": "your-key-here"
+ }
+ }
+}
+```
+
+> **No API key?** Select **Codex** in the `/connect` menu — it's a built-in provider with no setup required.
+
+---
+
+## Step 3 — Connect Your Warehouse _(Optional)_
+
+> Skip this step if you want to work locally or don't need warehouse/orchestration connections. You can always run `/discover` later.
+
+```bash
+altimate /discover
+```
+
+`/discover` scans for dbt projects, warehouse credentials (from `~/.dbt/profiles.yml`, environment variables, and Docker), and installed tools. It **reads but never writes** — safe to run against production.
+
+**No cloud warehouse?** Use DuckDB with a local file:
+
+```json
+{
+ "connections": {
+ "local": {
+ "type": "duckdb",
+ "database": "~/.altimate/local.duckdb"
+ }
+ }
+}
+```
+
+---
+
+## Step 4 — Build Your First Artifact
+
+In the TUI, try these prompts or describe your own use case:
+
+```
+
+Look at my snowflake account and do a comprehensive Analysis our Snowflake credit consumption over the last 30 days. After doing this generate a dashboard for my consumption.
+
+```
+
+```
+
+Build me a real time, interactive dashboard for my macbook system metrics and health. Use python, iceberg, dbt for various time slices.
+
+```
+
+---
+
+## What's Next
+
+- [Full Setup](getting-started.md) — All warehouse configs, LLM providers, advanced setup
+- [Agent Modes](data-engineering/agent-modes.md) — Choose the right agent for your task
+- [CI & Automation](data-engineering/guides/ci-headless.md) — Run altimate in automated pipelines
diff --git a/docs/docs/windows-wsl.md b/docs/docs/windows-wsl.md
index 68f6f00d81..0367a64436 100644
--- a/docs/docs/windows-wsl.md
+++ b/docs/docs/windows-wsl.md
@@ -1,8 +1,24 @@
# Windows / WSL
-altimate is supported on Windows through WSL (Windows Subsystem for Linux).
+altimate runs on Windows both natively (via Node.js on Windows) and through WSL (Windows Subsystem for Linux). WSL 2 is recommended for the best experience, but it is not required.
-## WSL Setup
+## Windows Native Install
+
+You can install and run altimate directly in PowerShell or Command Prompt without WSL:
+
+```powershell
+# PowerShell or CMD — install globally
+npm install -g @altimateai/altimate-code
+
+# Launch
+altimate
+```
+
+This works with Node.js 18+ installed natively on Windows. All core features work in native mode, including warehouse connections, agent modes, and the TUI.
+
+## WSL Setup (Recommended)
+
+For the best experience — especially with file watching, shell tools, and dbt — we recommend WSL 2:
1. Install WSL:
```powershell
@@ -25,6 +41,18 @@ altimate is supported on Windows through WSL (Windows Subsystem for Linux).
altimate
```
+## Windows Terminal
+
+For the best TUI experience on Windows, use [Windows Terminal](https://aka.ms/terminal) with a Nerd Font installed. Windows Terminal supports true color, Unicode, and the full range of TUI features that altimate uses.
+
+To install a Nerd Font:
+
+1. Download a Nerd Font from [nerdfonts.com](https://www.nerdfonts.com/font-downloads) (e.g., "FiraCode Nerd Font")
+2. Install the font on your system
+3. In Windows Terminal, go to **Settings > Profiles > Defaults > Appearance** and set the font face to the installed Nerd Font
+
+> **Note:** The default `cmd.exe` and older PowerShell windows have limited Unicode support, which may cause rendering issues with altimate's TUI elements.
+
## Git Bash Path
If you need to use Git Bash instead of WSL:
@@ -39,8 +67,52 @@ export ALTIMATE_CLI_GIT_BASH_PATH="C:\\Program Files\\Git\\bin\\bash.exe"
- Some terminal features may not work in older cmd.exe or PowerShell windows
- File watching may have delays due to WSL filesystem bridging
+## Troubleshooting
+
+### Path separator issues
+
+Windows uses backslashes (`\`) in file paths, but altimate config files should always use **forward slashes** (`/`), even on Windows. This applies to all paths in `altimate-code.json`:
+
+```json
+{
+ "warehouses": {
+ "local-duckdb": {
+ "type": "duckdb",
+ "database": "C:/Users/analyst/projects/dev.duckdb"
+ }
+ }
+}
+```
+
+**Wrong** (will cause errors):
+
+```json
+{
+ "database": "C:\\Users\\analyst\\projects\\dev.duckdb"
+}
+```
+
+**Right:**
+
+```json
+{
+ "database": "C:/Users/analyst/projects/dev.duckdb"
+}
+```
+
+This also applies to paths like `private_key_path`, `service_account`, and any plugin paths specified in the config.
+
+### Node.js not found after install
+
+If you installed Node.js but `npm` or `node` is not recognized:
+
+- Restart your terminal after installing Node.js
+- Ensure the Node.js installation directory is in your system `PATH`
+- In WSL, make sure you installed Node.js inside WSL, not on the Windows side
+
## Tips
- Use WSL 2 for better performance
- Store your projects in the WSL filesystem (`~/projects/`) rather than `/mnt/c/` for faster file operations
- Set up your warehouse connections in the WSL environment
+- If using both WSL and native Windows, keep separate config files — the WSL and Windows file systems have different path conventions
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 984b040204..dfb4fa1177 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -1,5 +1,5 @@
site_name: altimate-code
-site_description: The data engineering agent for dbt, SQL, and cloud warehouses
+site_description: The open-source data engineering harness. 99+ tools for building, validating, optimizing, and shipping data products.
site_url: https://altimateai.github.io/altimate-code
repo_url: https://github.com/AltimateAI/altimate-code
repo_name: AltimateAI/altimate-code
@@ -31,13 +31,33 @@ theme:
features:
- navigation.sections
- navigation.top
+ - navigation.instant
+ - navigation.tracking
- search.suggest
- search.highlight
- content.code.copy
+ - toc.follow
+ - content.tooltips
extra_css:
- assets/css/extra.css
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/AltimateAI/altimate-code
+ - icon: fontawesome/brands/discord
+ link: https://altimate.ai/discord
+ - icon: fontawesome/brands/python
+ link: https://pypi.org/project/altimate-engine/
+ analytics:
+ provider: google
+ property: G-XXXXXXXXXX # TODO: Replace with actual GA4 property ID
+ consent:
+ title: Cookie consent
+ description: >-
+ We use cookies to measure usage and improve the documentation.
+
markdown_extensions:
- admonition
- pymdownx.details
@@ -53,64 +73,76 @@ markdown_extensions:
nav:
- Home: index.md
- - Getting Started: getting-started.md
- - Data Engineering:
+
+ - Get Started:
+ - Quickstart: quickstart.md
+ - Full Setup: getting-started.md
- Agent Modes: data-engineering/agent-modes.md
- - Training:
- - Overview: data-engineering/training/index.md
- - Tools:
- - Overview: data-engineering/tools/index.md
- - SQL Tools: data-engineering/tools/sql-tools.md
- - Schema Tools: data-engineering/tools/schema-tools.md
- - FinOps Tools: data-engineering/tools/finops-tools.md
- - Lineage Tools: data-engineering/tools/lineage-tools.md
- - dbt Tools: data-engineering/tools/dbt-tools.md
- - Warehouse Tools: data-engineering/tools/warehouse-tools.md
- - Guides:
- - Overview: data-engineering/guides/index.md
- - Cost Optimization: data-engineering/guides/cost-optimization.md
- - Migration: data-engineering/guides/migration.md
- - Using with Claude Code: data-engineering/guides/using-with-claude-code.md
- - Using with Codex: data-engineering/guides/using-with-codex.md
- - Usage:
- - TUI: usage/tui.md
- - CLI: usage/cli.md
- - Web: usage/web.md
- - IDE: usage/ide.md
- - GitHub: usage/github.md
- - GitLab: usage/gitlab.md
+ - Interfaces:
+ - Terminal UI: usage/tui.md
+ - CLI: usage/cli.md
+ - IDE / VS Code: usage/ide.md
+ - Web UI: usage/web.md
+
+ - Guides:
+ - Cost Optimization: data-engineering/guides/cost-optimization.md
+ - SQL Migration: data-engineering/guides/migration.md
+ - CI & Automation: data-engineering/guides/ci-headless.md
+
+ - Tools:
+ - SQL Analysis: data-engineering/tools/sql-tools.md
+ - Schema & Metadata: data-engineering/tools/schema-tools.md
+ - Column-Level Lineage: data-engineering/tools/lineage-tools.md
+ - dbt Integration: data-engineering/tools/dbt-tools.md
+ - Cost & FinOps: data-engineering/tools/finops-tools.md
+ - Warehouse Tools: data-engineering/tools/warehouse-tools.md
+
+ - Integrations:
+ - GitHub Actions: usage/github.md
+ - GitLab CI: usage/gitlab.md
+ - Claude Code: data-engineering/guides/using-with-claude-code.md
+ - Codex: data-engineering/guides/using-with-codex.md
+ - MCP Servers: configure/mcp-servers.md
+ - LSP: configure/lsp.md
+ - ACP: configure/acp.md
+
- Configure:
- - Overview: configure/config.md
- - Providers & Models:
+ - Config Files: configure/config.md
+ - AI Providers & Models:
- Providers: configure/providers.md
- Models: configure/models.md
- - Agents & Tools:
+ - Agents & Skills:
- Agents: configure/agents.md
- - Tools: configure/tools.md
- - Agent Skills: configure/skills.md
+ - Skills: configure/skills.md
+ - Tools & Access:
+ - Allowed Tools: configure/tools.md
- Custom Tools: configure/custom-tools.md
- - Commands: configure/commands.md
+ - Access Control: configure/permissions.md
- Behavior:
- Rules: configure/rules.md
- - Permissions: configure/permissions.md
+ - Commands: configure/commands.md
- Context Management: configure/context-management.md
- - Formatters: configure/formatters.md
+ - Memory: data-engineering/tools/memory-tools.md
+ - Training:
+ - Overview: data-engineering/training/index.md
+ - Team Deployment: data-engineering/training/team-deployment.md
- Appearance:
- Themes: configure/themes.md
- Keybinds: configure/keybinds.md
- - Tracing: configure/tracing.md
- - Telemetry: configure/telemetry.md
- - Integrations:
- - LSP Servers: configure/lsp.md
- - MCP Servers: configure/mcp-servers.md
- - ACP Support: configure/acp.md
- - Develop:
+ - Formatters: configure/formatters.md
+ - Observability:
+ - Tracing: configure/tracing.md
+ - Telemetry: configure/telemetry.md
+ - Network & Proxy: network.md
+ - Windows / WSL: windows-wsl.md
+
+ - Extend:
- SDK: develop/sdk.md
- - Server: develop/server.md
+ - Server API: develop/server.md
- Plugins: develop/plugins.md
- Ecosystem: develop/ecosystem.md
+
- Reference:
- Security FAQ: security-faq.md
- - Network: network.md
- Troubleshooting: troubleshooting.md
- - Windows / WSL: windows-wsl.md
+ - Changelog: https://github.com/AltimateAI/altimate-code/blob/main/CHANGELOG.md
+
-