docs: sync missing content from v2 and rename What's New to Changelog

README.md

@@ -7,19 +7,18 @@
 
 **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)
+[![npm downloads](https://img.shields.io/npm/dm/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)
+[![Docs](https://img.shields.io/badge/docs-docs.altimate.sh-blue)](https://docs.altimate.sh)
 
 </div>
 
@@ -29,7 +28,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
@@ -58,7 +57,7 @@ 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.
+> **Zero additional setup.** One command install.
 
 ## Why a specialized harness?
 
@@ -162,7 +161,7 @@ Each agent has scoped permissions and purpose-built tools for its role.
 
 ## 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.
 
@@ -220,10 +219,11 @@ Contributions welcome — docs, SQL rules, warehouse connectors, and TUI improve
 
 **[Read CONTRIBUTING.md →](./CONTRIBUTING.md)**
 
-## What's New
+## Changelog
 
+- **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.1** (March 2026) — env-based skill selection, session caching, tracing improvements
-- **v0.4.0** (Feb 2026) — data visualization skill, 99+ tools, training system
+- **v0.4.0** (Feb 2026) — data visualization skill, 100+ tools, training system
 - **v0.3.x** — [See full changelog →](CHANGELOG.md)
 
 ## License

docs/docs/assets/css/extra.css

@@ -92,7 +92,7 @@
 /* --- Feature cards --- */
 .grid.cards > ul > li {
   border-radius: 8px;
-  padding: 0.8rem !important;
+  padding: 1rem !important;
   transition: box-shadow 0.2s ease, transform 0.2s ease;
 }
 
@@ -112,15 +112,18 @@
 
 /* --- Pill grid (LLM providers, warehouses) --- */
 .pill-grid {
-  max-width: 600px;
-  margin: 0 auto;
+  width: 100%;
+  max-width: 640px;
+  margin: 1rem auto;
+  padding: 0 1rem;
+  box-sizing: border-box;
 }
 
 .pill-grid ul {
   display: flex;
   flex-wrap: wrap;
   justify-content: center;
-  gap: 0.45rem;
+  gap: 0.6rem 0.75rem;
   list-style: none;
   padding: 0;
   margin: 0;
@@ -129,14 +132,14 @@
 .pill-grid ul li {
   display: inline-flex;
   align-items: center;
-  gap: 0.3rem;
-  padding: 0.4rem 0.85rem;
+  gap: 0.4rem;
+  padding: 0.5rem 1.15rem;
   border-radius: 100px;
   font-size: 0.8rem;
   border: 1px solid var(--md-default-fg-color--lightest);
   color: var(--md-default-fg-color--light);
   white-space: nowrap;
-  margin: 0;
+  flex-shrink: 0;
 }
 
 .pill-grid ul li .twemoji {
@@ -147,6 +150,30 @@
   border-color: rgba(255, 255, 255, 0.12);
 }
 
+/* Responsive pill sizing */
+@media (max-width: 768px) {
+  .pill-grid {
+    max-width: 100%;
+    padding: 0 0.75rem;
+  }
+
+  .pill-grid ul {
+    gap: 0.5rem 0.6rem;
+  }
+
+  .pill-grid ul li {
+    padding: 0.45rem 0.9rem;
+    font-size: 0.75rem;
+  }
+}
+
+@media (max-width: 480px) {
+  .pill-grid ul li {
+    padding: 0.4rem 0.8rem;
+    font-size: 0.72rem;
+  }
+}
+
 /* --- Doc links footer --- */
 .doc-links {
   text-align: center;

docs/docs/configure/agents.md

@@ -4,26 +4,46 @@ Agents define different AI personas with specific models, prompts, permissions,
 
 ## Built-in Agents
 
-### General Purpose
+| Agent | Description | Access Level |
+|-------|------------|-------------|
+| `builder` | Create and modify dbt models, SQL pipelines, and data transformations | Full read/write. SQL mutations prompt for approval. |
+| `analyst` | Explore data, run SELECT queries, inspect schemas, generate insights | Read-only (enforced). SQL writes denied. Safe bash commands auto-allowed. |
+| `plan` | Plan before acting, restricted to planning files only | Minimal: no edits, no bash, no SQL |
 
-| Agent | Description |
-|-------|------------|
-| `general` | Default general-purpose coding agent |
-| `plan` | Planning agent — analyzes before acting |
-| `build` | Build-focused agent — prioritizes code generation |
-| `explore` | Read-only exploration agent |
+### Builder
 
-### Data Engineering
+Full access mode. Can read/write files, run any bash command (with approval), execute SQL, and modify dbt models. SQL write operations (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, etc.) prompt for user approval. Destructive SQL (`DROP DATABASE`, `DROP SCHEMA`, `TRUNCATE`) is hard-blocked.
 
-| Agent | Description | Permissions |
-|-------|------------|------------|
-| `builder` | Create dbt models, SQL pipelines, transformations | Full read/write |
-| `analyst` | Explore data, run SELECT queries, generate insights | Read-only (enforced) |
-| `validator` | Data quality checks, schema validation, test coverage | Read + validate |
-| `migrator` | Cross-warehouse SQL translation and migration | Read/write for migration |
+### Analyst
+
+Truly read-only mode for safe data exploration:
+
+- **File access**: Read, grep, glob without prompts
+- **SQL**: SELECT queries execute freely. Write queries are denied (not prompted, blocked entirely)
+- **Bash**: Safe commands auto-allowed (`ls`, `grep`, `cat`, `head`, `tail`, `find`, `wc`). dbt read commands allowed (`dbt list`, `dbt ls`, `dbt debug`, `dbt deps`). Everything else denied.
+- **Web**: Fetch and search allowed without prompts
+- **Schema/warehouse/finops**: All inspection tools available
 
 !!! tip
-    Use the `analyst` agent when exploring data to ensure no accidental writes. Switch to `builder` when you are ready to create or modify models.
+    Use `analyst` when exploring data to ensure no accidental writes. Switch to `builder` when you're ready to create or modify models.
+
+### Plan
+
+Planning mode with minimal permissions. Can only read files and edit plan files. No SQL, no bash, no file modifications.
+
+## SQL Write Access Control
+
+All SQL queries are classified before execution:
+
+| Query Type | Builder | Analyst |
+|-----------|---------|---------|
+| `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN` | Allowed | Allowed |
+| `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `ALTER` | Prompts for approval | Denied |
+| `DROP DATABASE`, `DROP SCHEMA`, `TRUNCATE` | Blocked (cannot override) | Blocked |
+
+The classifier detects write operations including: `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `DROP`, `ALTER`, `TRUNCATE`, `GRANT`, `REVOKE`, `COPY INTO`, `CALL`, `EXEC`, `EXECUTE IMMEDIATE`, `BEGIN`, `DECLARE`, `REPLACE`, `UPSERT`, `RENAME`.
+
+Multi-statement queries (`SELECT 1; INSERT INTO ...`) are classified as write if any statement is a write.
 
 ## Custom Agents
 
@@ -86,11 +106,11 @@ You are a Snowflake cost optimization expert. For every query:
 ```
 
 !!! info
-    Markdown agent files use YAML frontmatter for configuration and the body as the system prompt. This is a convenient way to define agents without editing your main config file.
+    Markdown agent files use YAML frontmatter for configuration and the body as the system prompt.
 
 ## Agent Permissions
 
-Each agent can have its own permission overrides that restrict or expand the default permissions:
+Each agent can have its own permission overrides:
 
 ```json
 {
@@ -99,10 +119,11 @@ Each agent can have its own permission overrides that restrict or expand the def
       "permission": {
         "write": "deny",
         "edit": "deny",
+        "sql_execute_write": "deny",
         "bash": {
-          "dbt show *": "allow",
+          "*": "deny",
           "dbt list *": "allow",
-          "*": "deny"
+          "ls *": "allow"
         }
       }
     }
@@ -117,4 +138,4 @@ Each agent can have its own permission overrides that restrict or expand the def
 
 - **TUI**: Press leader + `a` or use `/agent <name>`
 - **CLI**: `altimate --agent analyst`
-- **In conversation**: Type `/agent validator`
+- **In conversation**: Type `/agent analyst`

docs/docs/configure/commands.md

@@ -8,7 +8,7 @@ altimate ships with six built-in slash commands:
 |---------|-------------|
 | `/init` | Create or update an AGENTS.md file with build commands and code style guidelines. |
 | `/discover` | Scan your data stack and set up warehouse connections. Detects dbt projects, warehouse connections from profiles/Docker/env vars, installed tools, and config files. Walks you through adding and testing new connections, then indexes schemas. |
-| `/review` | Review changes — accepts `commit`, `branch`, or `pr` as an argument (defaults to uncommitted changes). |
+| `/review` | Review changes. Accepts `commit`, `branch`, or `pr` as an argument (defaults to uncommitted changes). |
 | `/feedback` | Submit product feedback as a GitHub issue. Guides you through title, category, description, and optional session context. |
 | `/configure-claude` | Configure altimate as a `/altimate` slash command in [Claude Code](https://claude.com/claude-code). Writes `~/.claude/commands/altimate.md` so you can invoke altimate from within Claude Code sessions. |
 | `/configure-codex` | Configure altimate as a skill in [Codex CLI](https://developers.openai.com/codex). Creates `~/.codex/skills/altimate/SKILL.md` so Codex can delegate data engineering tasks to altimate. |
@@ -37,10 +37,10 @@ The recommended way to set up a new data engineering project. Run `/discover` in
 
 Submit product feedback directly from the CLI. The agent walks you through:
 
-1. **Title** — a short summary of your feedback
-2. **Category** — bug, feature, improvement, or ux
-3. **Description** — detailed explanation
-4. **Session context** (opt-in) — includes working directory name and session ID for debugging
+1. **Title**, a short summary of your feedback
+2. **Category**: bug, feature, improvement, or ux
+3. **Description** with a detailed explanation
+4. **Session context** (opt-in), which includes working directory name and session ID for debugging
 
 ```
 /feedback                    # start the guided feedback flow
@@ -137,7 +137,7 @@ Commands are loaded from:
 
 Press leader + `/` to see all available commands.
 
-## External CLI integration
+## External CLI Integration
 
 The `/configure-claude` and `/configure-codex` commands write integration files to external CLI tools:
 

docs/docs/configure/config.md

@@ -57,7 +57,7 @@ Configuration is loaded from multiple sources, with later sources overriding ear
 | `skills` | `object` | Skill paths and URLs |
 | `plugin` | `string[]` | Plugin specifiers |
 | `instructions` | `string[]` | Glob patterns for instruction files |
-| `telemetry` | `object` | Telemetry settings (see [Telemetry](telemetry.md)) |
+| `telemetry` | `object` | Telemetry settings (see [Telemetry](../reference/telemetry.md)) |
 | `compaction` | `object` | Context compaction settings (see [Context Management](context-management.md)) |
 | `experimental` | `object` | Experimental feature flags |
 
@@ -149,7 +149,7 @@ Control how context is managed when conversations grow long:
 |-------|---------|-------------|
 | `auto` | `true` | Auto-compact when context is full |
 | `prune` | `true` | Prune old tool outputs |
-| `reserved` | — | Token buffer to reserve |
+| `reserved` | (none) | Token buffer to reserve |
 
 !!! info
     Compaction automatically summarizes older messages to free up context window space, allowing longer conversations without losing important context. See [Context Management](context-management.md) for full details.

docs/docs/configure/context-management.md

@@ -1,14 +1,14 @@
 # Context Management
 
-altimate automatically manages conversation context so you can work through long sessions without hitting model limits. When a conversation grows large, the CLI summarizes older messages, prunes stale tool outputs, and recovers from provider overflow errors — all without losing the important details of your work.
+altimate automatically manages conversation context so you can work through long sessions without hitting model limits. When a conversation grows large, the CLI summarizes older messages, prunes stale tool outputs, and recovers from provider overflow errors, all without losing the important details of your work.
 
 ## How It Works
 
 Every LLM has a finite context window. As you work, each message, tool call, and tool result adds tokens to the conversation. When the conversation approaches the model's limit, altimate takes action:
 
-1. **Prune** — Old tool outputs (file reads, command results, query results) are replaced with compact summaries
-2. **Compact** — The entire conversation history is summarized into a continuation prompt
-3. **Continue** — The agent picks up where it left off using the summary
+1. **Prune.** Old tool outputs (file reads, command results, query results) are replaced with compact summaries
+2. **Compact.** The entire conversation history is summarized into a continuation prompt
+3. **Continue.** The agent picks up where it left off using the summary
 
 This happens automatically by default. You do not need to manually manage context.
 
@@ -38,7 +38,7 @@ When a tool output is pruned, it is replaced with a brief fingerprint:
 [Tool output cleared — read_file(file: src/main.ts) returned 42 lines, 1.2 KB — "import { App } from './app'"]
 ```
 
-This tells the model what tool was called, what arguments were used, how much output it produced, and the first line of the result — enough to maintain continuity without consuming tokens.
+This tells the model what tool was called, what arguments were used, how much output it produced, and the first line of the result. That is enough to maintain continuity without consuming tokens.
 
 **Pruning rules:**
 
@@ -51,12 +51,12 @@ This tells the model what tool was called, what arguments were used, how much ou
 
 Compaction is aware of data engineering workflows. When summarizing a conversation, the compaction prompt preserves:
 
-- **Warehouse connections** — which databases or warehouses are connected
-- **Schema context** — discovered tables, columns, and relationships
-- **dbt project state** — models, sources, tests, and project structure
-- **Lineage findings** — upstream and downstream dependencies
-- **Query patterns** — SQL dialects, anti-patterns, and optimization opportunities
-- **FinOps context** — cost findings and warehouse sizing recommendations
+- **Warehouse connections**, including which databases or warehouses are connected
+- **Schema context**, including discovered tables, columns, and relationships
+- **dbt project state**, including models, sources, tests, and project structure
+- **Lineage findings**, including upstream and downstream dependencies
+- **Query patterns**, including SQL dialects, anti-patterns, and optimization opportunities
+- **FinOps context**, including cost findings and warehouse sizing recommendations
 
 This means you can run a long data exploration session and compaction will not lose track of what schemas you discovered, what dbt models you were working with, or what cost optimizations you identified.
 

docs/docs/configure/governance.md

@@ -0,0 +1,39 @@
+# Governance
+
+Most people think of governance as a cost — something you bolt on for compliance. In practice, governance makes agents produce **better results**, not just safer ones.
+
+LLMs have built-in randomization. Give them too much freedom and they explore dead ends, burn tokens, and produce inconsistent output. Constrain the solution space and they get to correct results faster, in fewer tokens, with more consistency.
+
+Task-scoped permissions aren't just about safety — they're about **focus**. When an Analyst agent knows it can only `SELECT`, it doesn't waste cycles considering whether to `CREATE` a temp table. When it has prescribed, deterministic tools for tracing lineage instead of trying to figure it out from scratch, the results are the same every time.
+
+There's an audit angle too. In regulated industries, prescribed tooling eliminates unnecessary audit cycles. When your tools generate SQL the same way every time, auditors can verify consistency. Change the SQL — even if the results are conceptually identical — and you trigger an investigation to prove equivalence. Deterministic tooling removes that overhead entirely.
+
+Altimate Code enforces governance at the **harness level**, not via prompt instructions the model can ignore. Four mechanisms work together:
+
+## Rules
+
+Project rules via `AGENTS.md` files guide agent behavior — coding conventions, naming standards, warehouse policies, and workflow instructions. Rules are loaded automatically from well-known file patterns and merged into the agent's system prompt. Place them at your project root, in subdirectories for scoped guidance, or host them remotely for organization-wide standards.
+
+[:octicons-arrow-right-24: Rules reference](rules.md)
+
+## Permissions
+
+Every tool has a permission level — `allow`, `ask`, or `deny` — configurable globally or per agent. The Analyst agent can't `INSERT`, `UPDATE`, `DELETE`, or `DROP`. That's not a prompt instruction the model can choose to ignore. It's enforced at the tool level. Pattern-based permissions give you fine-grained control: allow `dbt build *` but deny `rm -rf *`.
+
+[:octicons-arrow-right-24: Permissions reference](permissions.md)
+
+## Context Management
+
+Long sessions produce large conversation histories that can exceed model context windows. Altimate Code automatically prunes old tool outputs, compacts conversations into summaries, and recovers from provider overflow errors — all while preserving critical data engineering context like warehouse connections, schema discoveries, lineage findings, and cost analysis results.
+
+[:octicons-arrow-right-24: Context Management reference](context-management.md)
+
+## Formatters
+
+Every file edit is auto-formatted before it's written. This isn't optional consistency — it's enforced consistency. Altimate Code detects file types and runs the appropriate formatter (prettier, ruff, gofmt, sqlfluff, and 20+ others) automatically. The agent can't produce code that violates your formatting standards.
+
+[:octicons-arrow-right-24: Formatters reference](formatters.md)
+
+---
+
+Together, these four mechanisms mean governance is not an afterthought — it's built into every agent interaction. The harness enforces the rules so your team doesn't have to police the output.