[DSPX-3302] (3/5) otdf-local multi-instance refactor

.gitignore

@@ -28,6 +28,14 @@ xtest/sdk/java/cmdline.jar
 /xtest/platform/
 /xtest/java-sdk/
 /xtest/sdk/go/otdfctl
+/xtest/sdk/go/platform-src/
 /xtest/otdfctl/
 
 /tmp/
+
+# Multi-instance test harness state (DSPX-3302). Per-instance config, logs, and
+# keys live under tests/instances/; otdf-sdk-mgr install scenario writes
+# .installed.json next to each scenarios.yaml.
+/instances/
+xtest/scenarios/*.installed.json
+.claude/tmp/

AGENTS.md

@@ -7,10 +7,11 @@ This guide provides essential knowledge for AI agents performing updates, refact
 | Path | Purpose | Has its own AGENTS.md? |
 |------|---------|------------------------|
 | `xtest/` | pytest integration tests (the main test suite) | yes |
-| `otdf-sdk-mgr/` | Python CLI that installs SDK CLIs from releases or source (see `otdf-sdk-mgr/README.md`) | no |
+| `otdf-sdk-mgr/` | Python CLI that installs SDK CLIs and the platform service from releases or source | yes |
 | `otdf-local/` | Python CLI that runs/stops the platform + KAS instances locally | yes |
 | `vulnerability/` | Playwright UI test suite (run with `npx playwright test`) | no |
-| `xtest/sdk/{go,java,js}/dist/` | Built SDK CLI wrappers, produced by `otdf-sdk-mgr install` (or by `cd xtest/sdk && make` for source builds) | n/a |
+| `platform/` | Platform service source — **installed by `otdf-sdk-mgr install platform`**, not committed. Edits here may be wiped by a reinstall. |  |
+| `xtest/sdk/{go,java,js}/dist/` | Built SDK CLI wrappers, produced by `otdf-sdk-mgr install` (or by `cd xtest/sdk && make` for source builds) |  |
 
 ## Test Framework Overview
 
@@ -234,7 +235,4 @@ yq e '.services.kas.root_key' platform/opentdf-dev.yaml
 
 ## Closing Note
 
-Test failures are usually configuration mismatches, not SDK bugs. Check
-the local environment against what the tests expect before suspecting the
-code. Per-subsystem details live in `xtest/AGENTS.md`,
-`otdf-local/AGENTS.md`, and `otdf-sdk-mgr/README.md`.
+The test failures are usually symptoms of configuration mismatches, not SDK bugs. Focus on ensuring the local environment matches what the tests expect. See the per-package guides in `xtest/`, `otdf-sdk-mgr/`, and `otdf-local/` for sub-system specifics.

otdf-local/AGENTS.md

@@ -2,6 +2,8 @@
 
 This guide covers operational procedures for managing the test environment with `otdf-local`. For command reference, see [README.md](README.md).
 
+**Depends on `otdf-sdk-mgr`.** `otdf-local` launches binaries that `otdf-sdk-mgr install platform` (or `otdf-sdk-mgr install scenario`) writes into `xtest/platform/dist/`. If `otdf-local up` complains that a binary is missing, run the installer first.
+
 ## Environment Setup for pytest
 
 ```bash

otdf-local/pyproject.toml

@@ -6,12 +6,16 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.27.0",
+    "otdf-sdk-mgr",
     "pydantic-settings>=2.2.0",
     "rich>=13.7.0",
     "ruamel.yaml>=0.18.0",
     "typer>=0.12.0",
 ]
 
+[tool.uv.sources]
+otdf-sdk-mgr = { path = "../otdf-sdk-mgr", editable = true }
+
 [dependency-groups]
 dev = [
     "pyright>=1.1.408",

otdf-local/src/otdf_local/cli.py

@@ -1,10 +1,12 @@
 """Typer CLI for otdf_local - OpenTDF test environment management."""
 
 import json
+import os
 import shutil
 import sys
 import time
-from typing import Annotated
+from pathlib import Path
+from typing import Annotated, Optional
 
 import httpx
 import typer
@@ -44,6 +46,18 @@
 )
 
 
+def _register_subapps() -> None:
+    """Defer imports so the schema dependency only loads when needed."""
+    from otdf_local.cli_instance import instance_app
+    from otdf_local.cli_scenario import scenario_app
+
+    app.add_typer(instance_app, name="instance")
+    app.add_typer(scenario_app, name="scenario")
+
+
+_register_subapps()
+
+
 def _show_provision_error(result: ProvisionResult, target: str) -> None:
     """Display provisioning error with stderr details."""
     print_error(f"{target} provisioning failed (exit code {result.return_code})")
@@ -75,9 +89,19 @@ def main(
             is_eager=True,
         ),
     ] = False,
+    instance: Annotated[
+        Optional[str],
+        typer.Option(
+            "--instance",
+            help='Named instance under tests/instances/. Defaults to "default" (or $OTDF_LOCAL_INSTANCE_NAME).',
+        ),
+    ] = None,
 ) -> None:
     """OpenTDF test environment management CLI."""
-    pass
+    if instance is not None:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance
+        # Invalidate the cached Settings so subsequent commands see the new value
+        get_settings.cache_clear()
 
 
 @app.command()