diff --git a/docs/docs/configure/warehouses.md b/docs/docs/configure/warehouses.md
index 4185576ba..22fdcb85a 100644
--- a/docs/docs/configure/warehouses.md
+++ b/docs/docs/configure/warehouses.md
@@ -1,6 +1,6 @@
 # Warehouses
 
-Altimate Code connects to 8 warehouse types. Configure them in the `warehouses` section of your config file or in `.altimate-code/connections.json`.
+Altimate Code connects to 8 warehouse types. Configure them in `.altimate-code/connections.json` (project-local) or `~/.altimate-code/connections.json` (global).
 
 ## Configuration
 
@@ -8,11 +8,9 @@ Each warehouse has a key (the connection name) and a config object:
 
 ```json
 {
-  "warehouses": {
-    "my-connection-name": {
-      "type": "<warehouse-type>",
-      ...
-    }
+  "my-connection-name": {
+    "type": "<warehouse-type>",
+    ...
   }
 }
 ```
@@ -24,16 +22,14 @@ Each warehouse has a key (the connection name) and a config object:
 
 ```json
 {
-  "warehouses": {
-    "prod-snowflake": {
-      "type": "snowflake",
-      "account": "xy12345.us-east-1",
-      "user": "analytics_user",
-      "password": "{env:SNOWFLAKE_PASSWORD}",
-      "warehouse": "COMPUTE_WH",
-      "database": "ANALYTICS",
-      "role": "ANALYST_ROLE"
-    }
+  "prod-snowflake": {
+    "type": "snowflake",
+    "account": "xy12345.us-east-1",
+    "user": "analytics_user",
+    "password": "{env:SNOWFLAKE_PASSWORD}",
+    "warehouse": "COMPUTE_WH",
+    "database": "ANALYTICS",
+    "role": "ANALYST_ROLE"
   }
 }
 ```
@@ -54,17 +50,15 @@ Each warehouse has a key (the connection name) and a config object:
 
 ```json
 {
-  "warehouses": {
-    "prod-snowflake": {
-      "type": "snowflake",
-      "account": "xy12345.us-east-1",
-      "user": "svc_altimate",
-      "private_key_path": "~/.ssh/snowflake_rsa_key.p8",
-      "private_key_passphrase": "{env:SNOWFLAKE_KEY_PASSPHRASE}",
-      "warehouse": "COMPUTE_WH",
-      "database": "ANALYTICS",
-      "role": "TRANSFORM_ROLE"
-    }
+  "prod-snowflake": {
+    "type": "snowflake",
+    "account": "xy12345.us-east-1",
+    "user": "svc_altimate",
+    "private_key_path": "~/.ssh/snowflake_rsa_key.p8",
+    "private_key_passphrase": "{env:SNOWFLAKE_KEY_PASSPHRASE}",
+    "warehouse": "COMPUTE_WH",
+    "database": "ANALYTICS",
+    "role": "TRANSFORM_ROLE"
   }
 }
 ```
@@ -73,13 +67,11 @@ Each warehouse has a key (the connection name) and a config object:
 
 ```json
 {
-  "warehouses": {
-    "bigquery-prod": {
-      "type": "bigquery",
-      "project": "my-gcp-project",
-      "credentials_path": "/path/to/service-account.json",
-      "location": "US"
-    }
+  "bigquery-prod": {
+    "type": "bigquery",
+    "project": "my-gcp-project",
+    "credentials_path": "/path/to/service-account.json",
+    "location": "US"
   }
 }
 ```
@@ -96,11 +88,9 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "bigquery-prod": {
-      "type": "bigquery",
-      "project": "my-gcp-project"
-    }
+  "bigquery-prod": {
+    "type": "bigquery",
+    "project": "my-gcp-project"
   }
 }
 ```
@@ -109,15 +99,13 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "databricks-prod": {
-      "type": "databricks",
-      "server_hostname": "adb-1234567890.1.azuredatabricks.net",
-      "http_path": "/sql/1.0/warehouses/abcdef1234567890",
-      "access_token": "{env:DATABRICKS_TOKEN}",
-      "catalog": "main",
-      "schema": "default"
-    }
+  "databricks-prod": {
+    "type": "databricks",
+    "server_hostname": "adb-1234567890.1.azuredatabricks.net",
+    "http_path": "/sql/1.0/warehouses/abcdef1234567890",
+    "access_token": "{env:DATABRICKS_TOKEN}",
+    "catalog": "main",
+    "schema": "default"
   }
 }
 ```
@@ -134,15 +122,13 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "my-postgres": {
-      "type": "postgres",
-      "host": "localhost",
-      "port": 5432,
-      "database": "analytics",
-      "user": "analyst",
-      "password": "{env:PG_PASSWORD}"
-    }
+  "my-postgres": {
+    "type": "postgres",
+    "host": "localhost",
+    "port": 5432,
+    "database": "analytics",
+    "user": "analyst",
+    "password": "{env:PG_PASSWORD}"
   }
 }
 ```
@@ -160,11 +146,9 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "my-postgres": {
-      "type": "postgres",
-      "connection_string": "postgresql://analyst:secret@localhost:5432/analytics"
-    }
+  "my-postgres": {
+    "type": "postgres",
+    "connection_string": "postgresql://analyst:secret@localhost:5432/analytics"
   }
 }
 ```
@@ -173,15 +157,13 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "redshift-prod": {
-      "type": "redshift",
-      "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
-      "port": 5439,
-      "database": "analytics",
-      "user": "admin",
-      "password": "{env:REDSHIFT_PASSWORD}"
-    }
+  "redshift-prod": {
+    "type": "redshift",
+    "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
+    "port": 5439,
+    "database": "analytics",
+    "user": "admin",
+    "password": "{env:REDSHIFT_PASSWORD}"
   }
 }
 ```
@@ -202,16 +184,14 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "redshift-prod": {
-      "type": "redshift",
-      "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
-      "database": "analytics",
-      "user": "admin",
-      "iam_role": "arn:aws:iam::123456789012:role/RedshiftReadOnly",
-      "cluster_identifier": "my-cluster",
-      "region": "us-east-1"
-    }
+  "redshift-prod": {
+    "type": "redshift",
+    "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
+    "database": "analytics",
+    "user": "admin",
+    "iam_role": "arn:aws:iam::123456789012:role/RedshiftReadOnly",
+    "cluster_identifier": "my-cluster",
+    "region": "us-east-1"
   }
 }
 ```
@@ -220,11 +200,9 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "dev-duckdb": {
-      "type": "duckdb",
-      "path": "./dev.duckdb"
-    }
+  "dev-duckdb": {
+    "type": "duckdb",
+    "path": "./dev.duckdb"
   }
 }
 ```
@@ -237,15 +215,13 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "mysql-prod": {
-      "type": "mysql",
-      "host": "localhost",
-      "port": 3306,
-      "database": "analytics",
-      "user": "analyst",
-      "password": "{env:MYSQL_PASSWORD}"
-    }
+  "mysql-prod": {
+    "type": "mysql",
+    "host": "localhost",
+    "port": 3306,
+    "database": "analytics",
+    "user": "analyst",
+    "password": "{env:MYSQL_PASSWORD}"
   }
 }
 ```
@@ -265,15 +241,13 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 
 ```json
 {
-  "warehouses": {
-    "sqlserver-prod": {
-      "type": "sqlserver",
-      "host": "localhost",
-      "port": 1433,
-      "database": "analytics",
-      "user": "sa",
-      "password": "{env:MSSQL_PASSWORD}"
-    }
+  "sqlserver-prod": {
+    "type": "sqlserver",
+    "host": "localhost",
+    "port": 1433,
+    "database": "analytics",
+    "user": "sa",
+    "password": "{env:MSSQL_PASSWORD}"
   }
 }
 ```
@@ -295,19 +269,17 @@ All warehouse types support SSH tunneling for connections behind a bastion host:
 
 ```json
 {
-  "warehouses": {
-    "prod-via-bastion": {
-      "type": "postgres",
-      "host": "10.0.1.50",
-      "database": "analytics",
-      "user": "analyst",
-      "password": "{env:PG_PASSWORD}",
-      "ssh_host": "bastion.example.com",
-      "ssh_port": 22,
-      "ssh_user": "ubuntu",
-      "ssh_auth_type": "key",
-      "ssh_key_path": "~/.ssh/id_rsa"
-    }
+  "prod-via-bastion": {
+    "type": "postgres",
+    "host": "10.0.1.50",
+    "database": "analytics",
+    "user": "analyst",
+    "password": "{env:PG_PASSWORD}",
+    "ssh_host": "bastion.example.com",
+    "ssh_port": 22,
+    "ssh_user": "ubuntu",
+    "ssh_auth_type": "key",
+    "ssh_key_path": "~/.ssh/id_rsa"
   }
 }
 ```
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
index 9f823fbea..a81b2caa0 100644
--- a/docs/docs/getting-started.md
+++ b/docs/docs/getting-started.md
@@ -64,19 +64,17 @@ Once complete, altimate indexes your schemas and detects your tooling, enabling
 
 ### Option B: Manual configuration
 
-Add a warehouse connection to your `altimate-code.json`. Here's a quick example:
+Add a warehouse connection to `.altimate-code/connections.json`. Here's a quick example:
 
 ```json
 {
-  "warehouses": {
-    "snowflake": {
-      "type": "snowflake",
-      "account": "xy12345.us-east-1",
-      "user": "your_user",
-      "password": "${SNOWFLAKE_PASSWORD}",
-      "warehouse": "COMPUTE_WH",
-      "database": "ANALYTICS"
-    }
+  "snowflake": {
+    "type": "snowflake",
+    "account": "xy12345.us-east-1",
+    "user": "your_user",
+    "password": "${SNOWFLAKE_PASSWORD}",
+    "warehouse": "COMPUTE_WH",
+    "database": "ANALYTICS"
   }
 }
 ```
@@ -120,7 +118,7 @@ Place `.altimate-code/altimate-code.json` in your dbt project root for project-s
 ```
 my-dbt-project/
   .altimate-code/
-    altimate-code.json    # warehouse connections, model preferences
+    altimate-code.json    # providers, model preferences, permissions
     agents/               # custom agent prompts
     commands/             # custom slash commands
     plugins/              # custom plugins
diff --git a/docs/docs/getting-started/quickstart-new.md b/docs/docs/getting-started/quickstart-new.md
index fb6bc81de..3586e7fae 100644
--- a/docs/docs/getting-started/quickstart-new.md
+++ b/docs/docs/getting-started/quickstart-new.md
@@ -50,23 +50,21 @@ Indexing schema... 142 tables, 1,847 columns indexed
 
 ### Option B: Manual configuration
 
-Add to `altimate-code.json` in your project root:
+Add to `.altimate-code/connections.json` in your project root:
 
 === "Snowflake"
 
     ```json
     {
-      "connections": {
-        "snowflake": {
-          "type": "snowflake",
-          "account": "xy12345.us-east-1",
-          "user": "dbt_user",
-          "password": "${SNOWFLAKE_PASSWORD}",
-          "warehouse": "TRANSFORM_WH",
-          "database": "ANALYTICS",
-          "schema": "PUBLIC",
-          "role": "TRANSFORMER"
-        }
+      "snowflake": {
+        "type": "snowflake",
+        "account": "xy12345.us-east-1",
+        "user": "dbt_user",
+        "password": "${SNOWFLAKE_PASSWORD}",
+        "warehouse": "TRANSFORM_WH",
+        "database": "ANALYTICS",
+        "schema": "PUBLIC",
+        "role": "TRANSFORMER"
       }
     }
     ```
@@ -75,12 +73,10 @@ Add to `altimate-code.json` in your project root:
 
     ```json
     {
-      "connections": {
-        "bigquery": {
-          "type": "bigquery",
-          "project": "my-project-id",
-          "keyfile": "~/.config/gcloud/application_default_credentials.json"
-        }
+      "bigquery": {
+        "type": "bigquery",
+        "project": "my-project-id",
+        "keyfile": "~/.config/gcloud/application_default_credentials.json"
       }
     }
     ```
@@ -89,15 +85,13 @@ Add to `altimate-code.json` in your project root:
 
     ```json
     {
-      "connections": {
-        "postgres": {
-          "type": "postgres",
-          "host": "localhost",
-          "port": 5432,
-          "database": "analytics",
-          "user": "postgres",
-          "password": "${POSTGRES_PASSWORD}"
-        }
+      "postgres": {
+        "type": "postgres",
+        "host": "localhost",
+        "port": 5432,
+        "database": "analytics",
+        "user": "postgres",
+        "password": "${POSTGRES_PASSWORD}"
       }
     }
     ```
@@ -106,11 +100,9 @@ Add to `altimate-code.json` in your project root:
 
     ```json
     {
-      "connections": {
-        "local": {
-          "type": "duckdb",
-          "database": "./data/analytics.duckdb"
-        }
+      "local": {
+        "type": "duckdb",
+        "database": "./data/analytics.duckdb"
       }
     }
     ```
diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md
index 908c9c236..92ae5f137 100644
--- a/docs/docs/getting-started/quickstart.md
+++ b/docs/docs/getting-started/quickstart.md
@@ -168,23 +168,21 @@ Auto-detects your dbt projects, warehouse credentials from `~/.dbt/profiles.yml`
 
 ### Manual configuration
 
-Add a warehouse connection to `altimate-code.json`:
+Add a warehouse connection to `.altimate-code/connections.json`:
 
 === "Snowflake"
 
     ```json
     {
-      "warehouses": {
-        "snowflake": {
-          "type": "snowflake",
-          "account": "xy12345.us-east-1",
-          "user": "dbt_user",
-          "password": "{env:SNOWFLAKE_PASSWORD}",
-          "warehouse": "TRANSFORM_WH",
-          "database": "ANALYTICS",
-          "schema": "PUBLIC",
-          "role": "TRANSFORMER"
-        }
+      "snowflake": {
+        "type": "snowflake",
+        "account": "xy12345.us-east-1",
+        "user": "dbt_user",
+        "password": "{env:SNOWFLAKE_PASSWORD}",
+        "warehouse": "TRANSFORM_WH",
+        "database": "ANALYTICS",
+        "schema": "PUBLIC",
+        "role": "TRANSFORMER"
       }
     }
     ```
@@ -193,12 +191,10 @@ Add a warehouse connection to `altimate-code.json`:
 
     ```json
     {
-      "warehouses": {
-        "bigquery": {
-          "type": "bigquery",
-          "project": "my-project-id",
-          "credentials_path": "~/.config/gcloud/application_default_credentials.json"
-        }
+      "bigquery": {
+        "type": "bigquery",
+        "project": "my-project-id",
+        "credentials_path": "~/.config/gcloud/application_default_credentials.json"
       }
     }
     ```
@@ -207,15 +203,13 @@ Add a warehouse connection to `altimate-code.json`:
 
     ```json
     {
-      "warehouses": {
-        "databricks": {
-          "type": "databricks",
-          "server_hostname": "dbc-abc123.cloud.databricks.com",
-          "http_path": "/sql/1.0/warehouses/abcdef",
-          "access_token": "{env:DATABRICKS_TOKEN}",
-          "catalog": "main",
-          "schema": "default"
-        }
+      "databricks": {
+        "type": "databricks",
+        "server_hostname": "dbc-abc123.cloud.databricks.com",
+        "http_path": "/sql/1.0/warehouses/abcdef",
+        "access_token": "{env:DATABRICKS_TOKEN}",
+        "catalog": "main",
+        "schema": "default"
       }
     }
     ```
@@ -224,15 +218,13 @@ Add a warehouse connection to `altimate-code.json`:
 
     ```json
     {
-      "warehouses": {
-        "postgres": {
-          "type": "postgres",
-          "host": "localhost",
-          "port": 5432,
-          "database": "analytics",
-          "user": "postgres",
-          "password": "{env:POSTGRES_PASSWORD}"
-        }
+      "postgres": {
+        "type": "postgres",
+        "host": "localhost",
+        "port": 5432,
+        "database": "analytics",
+        "user": "postgres",
+        "password": "{env:POSTGRES_PASSWORD}"
       }
     }
     ```
@@ -241,11 +233,9 @@ Add a warehouse connection to `altimate-code.json`:
 
     ```json
     {
-      "warehouses": {
-        "local": {
-          "type": "duckdb",
-          "path": "./data/analytics.duckdb"
-        }
+      "local": {
+        "type": "duckdb",
+        "path": "./data/analytics.duckdb"
       }
     }
     ```
@@ -254,15 +244,13 @@ Add a warehouse connection to `altimate-code.json`:
 
     ```json
     {
-      "warehouses": {
-        "redshift": {
-          "type": "redshift",
-          "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
-          "port": 5439,
-          "database": "analytics",
-          "user": "admin",
-          "password": "{env:REDSHIFT_PASSWORD}"
-        }
+      "redshift": {
+        "type": "redshift",
+        "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
+        "port": 5439,
+        "database": "analytics",
+        "user": "admin",
+        "password": "{env:REDSHIFT_PASSWORD}"
       }
     }
     ```
diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md
index d2f3d8e42..38c9ee6be 100644
--- a/docs/docs/quickstart.md
+++ b/docs/docs/quickstart.md
@@ -60,11 +60,9 @@ Auto-detects your dbt projects, warehouse credentials, and installed tools. See
 
 ```json
 {
-  "connections": {
-    "local": {
-      "type": "duckdb",
-      "database": "~/.altimate/local.duckdb"
-    }
+  "local": {
+    "type": "duckdb",
+    "database": "~/.altimate/local.duckdb"
   }
 }
 ```
diff --git a/docs/docs/reference/windows-wsl.md b/docs/docs/reference/windows-wsl.md
index a3285a03a..8dac0f46f 100644
--- a/docs/docs/reference/windows-wsl.md
+++ b/docs/docs/reference/windows-wsl.md
@@ -71,15 +71,13 @@ export ALTIMATE_CLI_GIT_BASH_PATH="C:\\Program Files\\Git\\bin\\bash.exe"
 
 ### 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`:
+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/connections.json`:
 
 ```json
 {
-  "warehouses": {
-    "local-duckdb": {
-      "type": "duckdb",
-      "database": "C:/Users/analyst/projects/dev.duckdb"
-    }
+  "local-duckdb": {
+    "type": "duckdb",
+    "database": "C:/Users/analyst/projects/dev.duckdb"
   }
 }
 ```