vb-dbrks · vb-dbrks · Mar 11, 2026 · Mar 10, 2026 · Mar 11, 2026 · Mar 11, 2026
diff --git a/contracts/cli-envelopes/runtime_info.success.json b/contracts/cli-envelopes/runtime_info.success.json
@@ -3,7 +3,7 @@
   "command": "runtime-info",
   "status": "success",
   "data": {
-    "cliVersion": "0.2.10",
+    "cliVersion": "0.2.11",
     "envelopeSchemaVersion": "1",
     "supportedCommands": [
       "runtime-info",

diff --git a/docs/schemax/docs/guide/databricks-asset-bundles.mdx b/docs/schemax/docs/guide/databricks-asset-bundles.mdx
@@ -164,13 +164,13 @@ resources:
       tags:
         managed_by: "schemax"
         schemax_project: "<project_name>"
-        schemax_version: "0.2.10"
+        schemax_version: "0.2.11"
       environments:
         - environment_key: schemax
           spec:
             environment_version: "2"
             dependencies:
-              - schemaxpy>=0.2.10
+              - schemaxpy>=0.2.11
       tasks:
         - task_key: schemax_apply
           environment_key: schemax
@@ -228,7 +228,7 @@ When the DAB job runs, the following happens:
 1. **File sync** -- `databricks bundle deploy` uploads your `.schemax/` project files and `resources/schemax_deploy.py` to the workspace.
 2. **Job creation** -- The DAB CLI creates (or updates) the job defined in `resources/schemax.yml`.
 3. **Job execution** -- When the job runs (either via `databricks bundle run` or a manual trigger), it:
-   - Spins up a serverless Python environment (version 2) with `schemaxpy>=0.2.10` installed.
+   - Spins up a serverless Python environment (version 2) with `schemaxpy>=0.2.11` installed.
    - Executes `resources/schemax_deploy.py` as a `spark_python_task`.
    - The deploy script locates the `.schemax/` project root (one level up from `resources/`) and invokes `schemax apply` **in-process** to inherit Databricks runtime authentication.
    - The target environment, warehouse ID, and auto-rollback flag are passed as `parameters` via `sys.argv`.

diff --git a/docs/schemax/docs/guide/setup.mdx b/docs/schemax/docs/guide/setup.mdx
@@ -32,6 +32,28 @@ Verify:
 schemax --help
 ```
 
+:::tip Using a virtual environment
+
+We recommend installing `schemaxpy` inside a virtual environment so it doesn't interfere with other Python projects.
+
+```bash
+# uv (fastest)
+uv venv .venv && source .venv/bin/activate
+uv pip install schemaxpy
+
+# conda / mamba
+conda create -n schemax python=3.11 && conda activate schemax
+pip install schemaxpy
+
+# standard venv
+python3 -m venv .venv && source .venv/bin/activate
+pip install schemaxpy
+```
+
+If your IDE can't find the `schemax` command after installing, select the correct Python interpreter: in VS Code / Cursor, open the Command Palette (`Cmd+Shift+P`) → **Python: Select Interpreter** → choose the interpreter inside your virtual environment.
+
+:::
+
 ## 3. Open a project
 
 1. In VS Code, Cursor, or your editor, **File → Open Folder**

diff --git a/docs/schemax/docs/reference/faq.mdx b/docs/schemax/docs/reference/faq.mdx
@@ -40,6 +40,23 @@ Yes. All changes are stored as **operations** in `.schemax/changelog.json`, and
 
 Yes. In the VS Code designer, select a **catalog** or **schema** in the tree, then click **Bulk operations** in the detail panel. You can add the same grant (principal + privileges) or tag (name + value) to all objects in that scope—e.g. all tables and views in a schema, or all schemas, tables, and views in a catalog. The generated operations are the same as adding them one by one; they are just batched for convenience. See [Unity Catalog grants — Bulk grants and tags](/docs/guide/unity-catalog-grants/#bulk-grants-and-tags).
 
+## `schemax` command not found / IDE can't resolve imports
+
+This usually means the CLI is installed in a virtual environment that isn't active, or your IDE is pointing at the wrong Python interpreter.
+
+1. **Activate your virtual environment** before running `schemax`:
+   ```bash
+   # uv / standard venv
+   source .venv/bin/activate
+
+   # conda / mamba
+   conda activate schemax
+   ```
+2. **Select the correct interpreter in your IDE** — In VS Code / Cursor, open the Command Palette (`Cmd+Shift+P`) → **Python: Select Interpreter** → choose the interpreter inside your virtual environment (e.g. `.venv/bin/python` or the conda env path).
+3. **uv venv path** — If you used `uv venv`, the default location is `.venv/` in your project directory. Make sure your IDE points to `.venv/bin/python`.
+
+After selecting the right interpreter, restart the terminal in your IDE and try `schemax --help` again.
+
 ## Can I use the CLI from my own scripts or automation?
 
 Yes. The CLI is a standard Python CLI; you can call it from scripts, cron, or other automation. For example: `schemax sql --target dev --output migration.sql` then run the SQL with your own runner, or `schemax apply --target dev --no-interaction` from a pipeline. See [Git and CI/CD setup](/docs/guide/git-and-cicd-setup/).
diff --git a/docs/schemax/docs/reference/release-notes.mdx b/docs/schemax/docs/reference/release-notes.mdx
@@ -6,6 +6,26 @@ This page summarizes coordinated SchemaX releases across:
 - VS Code extension (`schemax-vscode`)
 - Documentation site (`docs/schemax`)
 
+## 0.2.11 (2026-03-11)
+
+### Highlights
+
+- **v5 multi-target architecture** — Projects now support multiple provider targets (e.g., multiple Unity Catalog catalogs or mixed providers) via a `targets` dict in `project.json`. Existing v4 projects auto-migrate on first load.
+- **`--scope` CLI parameter** — New flag on `sql`, `validate`, `apply`, and `workspace-state`. Currently plumbed through CLI and interfaces; target-scoped state loading will be enabled in a follow-up release.
+- **Provider-specific settings UI** — Project Settings in the VS Code extension now renders per-provider configuration with target tabs for multi-target projects.
+- **Renamed `target_name` to `scope`** — Eliminated naming confusion between environment target (`--target dev`) and provider scope (`--scope analytics`).
+
+### Package versions
+
+- Python SDK/CLI: `0.2.11`
+- VS Code extension: `0.2.11`
+- Docs site package: `0.2.11`
+
+### Changelogs
+
+- [Python SDK changelog](https://github.com/vb-dbrks/schemax-vscode/blob/main/packages/python-sdk/CHANGELOG.md)
+- [VS Code extension changelog](https://github.com/vb-dbrks/schemax-vscode/blob/main/packages/vscode-extension/CHANGELOG.md)
+
 ## 0.2.10 (2026-03-10)
 
 ### Highlights

diff --git a/docs/schemax/package.json b/docs/schemax/package.json
@@ -1,6 +1,6 @@
 {
   "name": "schemax-docs",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "schemax",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "private": true,
   "description": "SchemaX - Databricks Unity Catalog schema management with version control",
   "repository": {

diff --git a/packages/python-sdk/CHANGELOG.md b/packages/python-sdk/CHANGELOG.md
@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.2.11] - 2026-03-11
+
+### Added
+
+- **v5 multi-target project schema** — Projects now use a `targets` dict instead of a single `provider` object, enabling multiple provider instances (e.g., multiple Unity Catalog catalogs or mixed providers) in one project. Existing v4 projects auto-migrate to v5 on first load.
+- **`--scope` CLI parameter** — New `--scope` flag on `sql`, `validate`, `apply`, and `workspace-state` commands. Currently plumbed through CLI and interfaces; target-scoped state loading will be enabled in a follow-up release.
+- **`Operation.scope` field** — Operations now carry a `scope` field to associate them with a specific target in multi-target projects.
+- **Provider-specific settings UI** — Project Settings panel renders target-specific configuration per provider type, with tabs for each target in multi-target projects.
+
+### Changed
+
+- **Renamed `target_name` to `scope`** — All internal parameters, CLI flags, and Operation fields renamed from `target_name` to `scope` to avoid confusion with `target` (environment). Breaking change for any code using `--target-name` CLI flag or `Operation.target_name` field.
+- **New projects created as v5** — `ensure_project_file()` and extension "New Project" flow now emit v5 project schema directly.
+
+### Fixed
+
+- **Apply command `target_name` kwarg error** — Fixed `TypeError` where `_build_apply_request()` passed `target_name` to `apply_to_environment()` which didn't accept it, causing `UNEXPECTED_ERROR` instead of proper error codes.
+- **Integration tests updated for v5** — All test files updated to use v5 project schema (`project["targets"][scope]` instead of `project["provider"]`).
+
 ## [0.2.10] - 2026-03-10
 
 ### Added

diff --git a/packages/python-sdk/pyproject.toml b/packages/python-sdk/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "schemaxpy"
-version = "0.2.10"
+version = "0.2.11"
 description = "Declarative schema management, governance, and migration for Databricks Unity Catalog. Version control schemas, generate SQL, deploy across environments."
 readme = "README.md"
 requires-python = ">=3.11"

diff --git a/packages/python-sdk/src/schemax/__init__.py b/packages/python-sdk/src/schemax/__init__.py
@@ -14,8 +14,10 @@
 # Provider system exports
 # Storage V4 exports (latest)
 from .core.storage import (
+    _get_provider_from_target,
     create_snapshot,
     ensure_project_file,
+    get_target_config,
     load_current_state,
     read_changelog,
     read_project,
@@ -68,12 +70,14 @@ def generate_diff_operations(
     old_snap = read_snapshot(workspace_path, from_version)
     new_snap = read_snapshot(workspace_path, to_version)
 
-    # Get provider
+    # Get provider from default target
     project = read_project(workspace_path)
-    provider = ProviderRegistry.get(project["provider"]["type"])
+    target_cfg = get_target_config(project)
+    provider_type = _get_provider_from_target(target_cfg)
+    provider = ProviderRegistry.get(provider_type)
 
     if not provider:
-        raise ValueError(f"Provider '{project['provider']['type']}' not found")
+        raise ValueError(f"Provider '{provider_type}' not found")
 
     # Generate diff
     differ = provider.get_state_differ(

diff --git a/packages/python-sdk/src/schemax/application/services.py b/packages/python-sdk/src/schemax/application/services.py
@@ -55,8 +55,14 @@ def run(self, *, workspace: Path, provider_id: str) -> CommandResult:
 class ValidateService:
     """Validate workspace project state."""
 
-    def run(self, *, workspace: Path, json_output: bool = False) -> CommandResult:
-        valid = validate_project(workspace, json_output=json_output)
+    def run(
+        self,
+        *,
+        workspace: Path,
+        json_output: bool = False,
+        scope: str | None = None,
+    ) -> CommandResult:
+        valid = validate_project(workspace, json_output=json_output, scope=scope)
         code = "valid" if valid else "invalid"
         return CommandResult(success=valid, code=code, message="Validation completed")
 
@@ -74,6 +80,7 @@ def run(
         from_version: str | None,
         to_version: str | None,
         target_env: str | None,
+        scope: str | None = None,
     ) -> CommandResult:
         sql = generate_sql_migration(
             workspace=workspace,
@@ -82,6 +89,7 @@ def run(
             _from_version=from_version,
             _to_version=to_version,
             target_env=target_env,
+            scope=scope,
         )
         return CommandResult(
             success=True,
@@ -201,6 +209,7 @@ def run(
         no_interaction: bool,
         auto_rollback: bool,
         execution_mode: str = "remote",
+        scope: str | None = None,
     ) -> CommandResult:
         request = _build_apply_request(
             workspace,
@@ -211,6 +220,7 @@ def run(
             no_interaction,
             auto_rollback,
             execution_mode,
+            scope=scope,
         )
         result = apply_to_environment(**request)
         return CommandResult(
@@ -417,6 +427,8 @@ def _build_apply_request(
     no_interaction: bool,
     auto_rollback: bool,
     execution_mode: str = "remote",
+    *,
+    scope: str | None = None,
 ) -> dict[str, Any]:
     """Build kwargs for apply command boundary calls."""
     keys = (
@@ -428,6 +440,7 @@ def _build_apply_request(
         "no_interaction",
         "auto_rollback",
         "execution_mode",
+        "scope",
     )
     values = (
         workspace,
@@ -438,6 +451,7 @@ def _build_apply_request(
         no_interaction,
         auto_rollback,
         execution_mode,
+        scope,
     )
     return dict(zip(keys, values, strict=True))