docs(skills): use top-level databricks aitools everywhere

Follow-up to #60, which only touched README/manifest and the jobs +
pipelines SKILL.md. This sweeps the remaining `databricks experimental
aitools` references across the core/apps skills, the experimental
skills, and reference docs.

The old paths still work as deprecated aliases (see databricks/cli#4917),
but new readers should be pointed at the supported command.

Co-authored-by: Isaac

Author: jamesbroadhead

experimental/databricks-agent-bricks/SKILL.md

@@ -19,7 +19,7 @@ Agent Bricks are pre-built AI tiles in Databricks that provide conversational in
 ```bash
 # Find volumes
 databricks volumes list CATALOG SCHEMA
-databricks experimental aitools tools query --warehouse WH "LIST '/Volumes/catalog/schema/volume/'"
+databricks aitools tools query --warehouse WH "LIST '/Volumes/catalog/schema/volume/'"
 
 # Create KA
 databricks knowledge-assistants create-knowledge-assistant "Name" "Description"

experimental/databricks-aibi-dashboards/SKILL.md

@@ -14,15 +14,15 @@ A dashboard should be showing something relevant for a human, typically some KPI
 | Task | Command |
 |------|---------|
 | List warehouses | `databricks warehouses list` |
-| List tables | `databricks experimental aitools tools query --warehouse WH "SHOW TABLES IN catalog.schema"` |
-| Get schema | `databricks experimental aitools tools discover-schema catalog.schema.table1 catalog.schema.table2` |
-| Test query | `databricks experimental aitools tools query --warehouse WH "SELECT..."` |
+| List tables | `databricks aitools tools query --warehouse WH "SHOW TABLES IN catalog.schema"` |
+| Get schema | `databricks aitools tools discover-schema catalog.schema.table1 catalog.schema.table2` |
+| Test query | `databricks aitools tools query --warehouse WH "SELECT..."` |
 | Create dashboard | `databricks lakeview create --display-name "X" --warehouse-id "WH" --dataset-catalog CATALOG --dataset-schema SCHEMA --serialized-dashboard "$(cat file.json)" --json '{"parent_path": "/Workspace/Users/<you>/path"}'` — `--dataset-catalog` / `--dataset-schema` are **flag-only** (REQUIRED; CLI silently drops them if put in `--json`); `parent_path` is JSON-only (no flag). Queries must use bare table names. |
 | Update dashboard | `databricks lakeview update DASHBOARD_ID --serialized-dashboard "$(cat file.json)"` |
 | Publish | `databricks lakeview publish DASHBOARD_ID --warehouse-id WH` |
 | Delete | `databricks lakeview trash DASHBOARD_ID` |
 
-> **`--warehouse` flag**: if `databricks experimental aitools tools query --warehouse WH "..."` fails with `unknown flag: --warehouse` on your CLI version, set `DATABRICKS_WAREHOUSE_ID=WH` in the environment instead and drop the flag — the command auto-picks it from there.
+> **`--warehouse` flag**: if `databricks aitools tools query --warehouse WH "..."` fails with `unknown flag: --warehouse` on your CLI version, set `DATABRICKS_WAREHOUSE_ID=WH` in the environment instead and drop the flag — the command auto-picks it from there.
 
 ---
 
@@ -57,9 +57,9 @@ A good dashboard comes from knowing the data first. Spend time here — the expl
 
 Use `discover-schema` as the default — one call returns columns, types, sample rows, null counts, and row count. If you only know the schema, list tables first with `query "SHOW TABLES IN ..."`.
 
-`databricks experimental aitools tools discover-schema catalog.schema.orders catalog.schema.customers`
+`databricks aitools tools discover-schema catalog.schema.orders catalog.schema.customers`
 
-Sample rows alone don't tell you what to build. you can write aggregate SQL through `databricks experimental aitools tools query --warehouse <WH> "..."` to probe typically:
+Sample rows alone don't tell you what to build. you can write aggregate SQL through `databricks aitools tools query --warehouse <WH> "..."` to probe typically:
 
 - **Cardinality** of candidate grouping columns → decides chart color-group vs. table (≤8 distinct values for charts, see Cardinality & Readability below).
 - **Top categorical values** → populates filter options and chart legends meaningfully.

experimental/databricks-apps-python/SKILL.md

@@ -39,7 +39,7 @@ databricks apps deploy
 ### AI-assisted development
 ```bash
 # Install agent skills for AI-powered scaffolding
-databricks experimental aitools skills install
+databricks aitools install
 
 # Query AppKit docs inline
 npx @databricks/appkit docs "your question here"

experimental/databricks-dbsql/SKILL.md

@@ -297,4 +297,4 @@ Load these for detailed syntax, full parameter lists, and advanced patterns:
 - **Star schema in Gold layer** for BI; OBT acceptable in Silver
 - **Define PK/FK constraints** on dimensional models for query optimization
 - **Use `COLLATE UTF8_LCASE`** for user-facing string columns that need case-insensitive search
-- **Test SQL via CLI** (`databricks experimental aitools tools query`) or notebooks before deploying. If `--warehouse` is rejected on your CLI version, set `DATABRICKS_WAREHOUSE_ID` in the environment instead.
+- **Test SQL via CLI** (`databricks aitools tools query`) or notebooks before deploying. If `--warehouse` is rejected on your CLI version, set `DATABRICKS_WAREHOUSE_ID` in the environment instead.

experimental/databricks-metric-views/SKILL.md

@@ -29,9 +29,9 @@ Use this skill when:
 
 Before authoring a metric view, inspect the source tables. Use `discover-schema` as the default — one call returns columns, types, sample rows, null counts, and row count. If you only know the schema, list tables first with `query "SHOW TABLES IN ..."`.
 
-`databricks experimental aitools tools discover-schema catalog.schema.orders catalog.schema.customers`
+`databricks aitools tools discover-schema catalog.schema.orders catalog.schema.customers`
 
-For dimensions and measures, probe distribution beyond sampling — cardinality of candidate dimensions, min/max/percentiles for measures, top categorical values. Write aggregate SQL through `databricks experimental aitools tools query --warehouse <WH> "..."`. Both commands auto-pick the default warehouse; set `DATABRICKS_WAREHOUSE_ID` or pass `--warehouse <ID>` to override.
+For dimensions and measures, probe distribution beyond sampling — cardinality of candidate dimensions, min/max/percentiles for measures, top categorical values. Write aggregate SQL through `databricks aitools tools query --warehouse <WH> "..."`. Both commands auto-pick the default warehouse; set `DATABRICKS_WAREHOUSE_ID` or pass `--warehouse <ID>` to override.
 
 ### Create a Metric View
 
@@ -157,7 +157,7 @@ DROP VIEW IF EXISTS catalog.schema.orders_metrics;
 
 ```bash
 # Execute SQL via CLI
-databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
+databricks aitools tools query --warehouse WAREHOUSE_ID "
 CREATE OR REPLACE VIEW catalog.schema.orders_metrics
 WITH METRICS
 LANGUAGE YAML

experimental/databricks-synthetic-data-gen/SKILL.md

@@ -128,10 +128,10 @@ Show a clear specification with **the business story and your assumptions surfac
 
 ### Post-Generation Validation
 
-Use `databricks experimental aitools tools query` to validate generated data (row counts, distributions, referential integrity). Query parquet files directly:
+Use `databricks aitools tools query` to validate generated data (row counts, distributions, referential integrity). Query parquet files directly:
 
 ```bash
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT COUNT(*) FROM parquet.\`/Volumes/CATALOG/SCHEMA/raw_data/customers\`
 "
 ```

experimental/databricks-synthetic-data-gen/references/2-troubleshooting.md

@@ -293,30 +293,30 @@ WAREHOUSE_ID="your-warehouse-id"
 VOLUME_PATH="/Volumes/CATALOG/SCHEMA/raw_data"
 
 # 1. Check row counts
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT 'customers' as table_name, COUNT(*) as row_count FROM parquet.\`${VOLUME_PATH}/customers\`
 UNION ALL
 SELECT 'orders', COUNT(*) FROM parquet.\`${VOLUME_PATH}/orders\`
 "
 
 # 2. Preview schema and sample data
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 DESCRIBE SELECT * FROM parquet.\`${VOLUME_PATH}/customers\`
 "
 
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT * FROM parquet.\`${VOLUME_PATH}/customers\` LIMIT 5
 "
 
 # 3. Verify distributions
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT tier, COUNT(*) as count, ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER(), 1) as pct
 FROM parquet.\`${VOLUME_PATH}/customers\`
 GROUP BY tier ORDER BY tier
 "
 
 # 4. Check amount statistics
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT
   MIN(amount) as min_amount,
   MAX(amount) as max_amount,
@@ -326,15 +326,15 @@ FROM parquet.\`${VOLUME_PATH}/orders\`
 "
 
 # 5. Check referential integrity
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT COUNT(*) as orphan_orders
 FROM parquet.\`${VOLUME_PATH}/orders\` o
 LEFT JOIN parquet.\`${VOLUME_PATH}/customers\` c ON o.customer_id = c.customer_id
 WHERE c.customer_id IS NULL
 "
 
 # 6. Verify date range
-databricks experimental aitools tools query --warehouse $WAREHOUSE_ID "
+databricks aitools tools query --warehouse $WAREHOUSE_ID "
 SELECT MIN(order_date) as min_date, MAX(order_date) as max_date
 FROM parquet.\`${VOLUME_PATH}/orders\`
 "

experimental/databricks-unity-catalog/SKILL.md

@@ -101,11 +101,11 @@ GROUP BY workspace_id, sku_name;
 
 ## SQL Queries via CLI
 
-Use `databricks experimental aitools tools query` for system table queries:
+Use `databricks aitools tools query` for system table queries:
 
 ```bash
 # Query lineage via CLI
-databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
+databricks aitools tools query --warehouse WAREHOUSE_ID "
   SELECT source_table_full_name, target_table_full_name
   FROM system.access.table_lineage
   WHERE event_date >= current_date() - 7

experimental/databricks-unity-catalog/references/7-data-profiling.md

@@ -68,7 +68,7 @@ DROP QUALITY MONITOR catalog.schema.my_table;
 ### Execute via CLI
 
 ```bash
-databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
+databricks aitools tools query --warehouse WAREHOUSE_ID "
 CREATE OR REPLACE QUALITY MONITOR catalog.schema.my_table
 OPTIONS (OUTPUT_SCHEMA 'catalog.schema')
 "

experimental/databricks-vector-search/references/end-to-end-rag.md

@@ -6,7 +6,7 @@ Build a complete Retrieval-Augmented Generation pipeline: prepare documents, cre
 
 | Command | Step |
 |---------|------|
-| `databricks experimental aitools tools query` | Create source table, insert documents |
+| `databricks aitools tools query` | Create source table, insert documents |
 | `databricks vector-search-endpoints create-endpoint` | Create compute endpoint |
 | `databricks vector-search-indexes create-index` | Create Delta Sync index with managed embeddings |
 | `databricks vector-search-indexes sync-index` | Trigger index sync |
@@ -37,7 +37,7 @@ INSERT INTO catalog.schema.knowledge_base VALUES
 Or via CLI:
 
 ```bash
-databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
+databricks aitools tools query --warehouse WAREHOUSE_ID "
     CREATE TABLE IF NOT EXISTS catalog.schema.knowledge_base (
         doc_id STRING,
         title STRING,