docs: add v2 migration guide and dual-package install instructions [PYSDK-142]

docs/partials/CLI_REFERENCE_header.md

@@ -0,0 +1,141 @@
+# CLI Reference
+
+The Aignostics Python SDK provides two CLI entry points:
+
+- **`aignostics`** — Full SDK (installed with `pip install aignostics`). Includes all commands
+  for application runs, WSI processing, dataset downloads, cloud storage, and the Launchpad.
+- **`aignostics-sdk`** — Slim API client (installed with `pip install aignostics-sdk`). Includes
+  only user authentication and SDK metadata schema commands.
+
+When the full `aignostics` package is installed both entry points are available.
+
+---
+
+## `aignostics-sdk` CLI Reference
+
+Command Line Interface of the slim `aignostics-sdk` distribution.
+
+**Usage**:
+
+```console
+$ aignostics-sdk [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `user`: User operations such as login, logout and whoami.
+* `sdk`: Platform operations such as dumping the SDK run and item metadata schemas.
+
+### `aignostics-sdk user`
+
+User operations such as login, logout and whoami.
+
+**Usage**:
+
+```console
+$ aignostics-sdk user [OPTIONS] COMMAND [ARGS]...
+```
+
+**Commands**:
+
+* `login`: Authenticate with the Aignostics Platform using OAuth 2.0 device flow.
+* `logout`: Remove cached authentication token.
+* `whoami`: Show the currently authenticated user.
+
+#### `aignostics-sdk user login`
+
+Authenticate with the Aignostics Platform using OAuth 2.0 device flow.
+
+**Usage**:
+
+```console
+$ aignostics-sdk user login [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+#### `aignostics-sdk user logout`
+
+Remove cached authentication token.
+
+**Usage**:
+
+```console
+$ aignostics-sdk user logout [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+#### `aignostics-sdk user whoami`
+
+Show the currently authenticated user.
+
+**Usage**:
+
+```console
+$ aignostics-sdk user whoami [OPTIONS]
+```
+
+**Options**:
+
+* `--mask-secrets / --no-mask-secrets`: Mask secrets in output.  [default: mask-secrets]
+* `--help`: Show this message and exit.
+
+### `aignostics-sdk sdk`
+
+Platform operations such as dumping the SDK run and item metadata schemas.
+
+**Usage**:
+
+```console
+$ aignostics-sdk sdk [OPTIONS] COMMAND [ARGS]...
+```
+
+**Commands**:
+
+* `run-metadata-schema`: Export the JSON Schema for SDK run custom metadata.
+* `item-metadata-schema`: Export the JSON Schema for SDK item custom metadata.
+
+#### `aignostics-sdk sdk run-metadata-schema`
+
+Export the JSON Schema for SDK run custom metadata.
+
+**Usage**:
+
+```console
+$ aignostics-sdk sdk run-metadata-schema [OPTIONS]
+```
+
+**Options**:
+
+* `--pretty / --no-pretty`: Pretty-print the JSON output.  [default: no-pretty]
+* `--help`: Show this message and exit.
+
+#### `aignostics-sdk sdk item-metadata-schema`
+
+Export the JSON Schema for SDK item custom metadata.
+
+**Usage**:
+
+```console
+$ aignostics-sdk sdk item-metadata-schema [OPTIONS]
+```
+
+**Options**:
+
+* `--pretty / --no-pretty`: Pretty-print the JSON output.  [default: no-pretty]
+* `--help`: Show this message and exit.
+
+---
+
+## `aignostics` CLI Reference

docs/partials/README_footer.md

@@ -1,5 +1,8 @@
 ## Further Reading
 
+1. **Upgrading from v1?** Read the
+   [v2 Migration Guide](https://aignostics.readthedocs.io/en/latest/migration.html)
+   for updated import paths and install instructions.
 1. Inspect our
    [security policy](https://aignostics.readthedocs.io/en/latest/security.html)
    with detailed documentation of checks, tools and principles.

docs/partials/README_main.md

@@ -24,6 +24,62 @@ more about how we achieve
 
 ## Installation
 
+> **v2 dual-package distribution**: The SDK is now published as two separate PyPI packages.
+> Use `aignostics-sdk` for the slim API client, or `aignostics` for the full SDK with GUI, WSI
+> processing, and dataset downloads. See the [v2 Migration Guide](#migrating-from-v1-to-v2)
+> if you are upgrading from v1.
+
+### API client only (slim)
+
+For users who only need the platform API client with minimal dependencies:
+
+```bash
+pip install aignostics-sdk
+```
+
+Python imports:
+
+```python
+from aignostics_sdk.platform import Client
+```
+
+CLI:
+
+```bash
+aignostics-sdk user login
+aignostics-sdk user whoami
+```
+
+### Full SDK
+
+For users who need WSI processing, dataset downloads, the desktop Launchpad, and all features:
+
+```bash
+pip install aignostics
+```
+
+Python imports (full SDK modules unchanged from v1):
+
+```python
+from aignostics.application import ...   # ML application orchestration
+from aignostics.wsi import ...           # Whole slide image processing
+from aignostics.dataset import ...       # IDC dataset downloads
+```
+
+Platform/utils imports (updated namespace in v2):
+
+```python
+from aignostics_sdk.platform import Client  # was: from aignostics.platform import Client
+from aignostics_sdk.utils import BaseService  # was: from aignostics.utils import BaseService
+```
+
+CLI (unchanged):
+
+```bash
+aignostics user login
+aignostics application list
+```
+
 The **Aignostics Python SDK** can be installed via the [uv package manager](https://docs.astral.sh/uv/). The installation process sets up the SDK along with the necessary dependencies, including the **uv** package manager itself if not already present.
 
 Before proceeding, ensure you have an **Aignostics Platform account**. You can get access either through your organization admin (if your organization has an Aignostics account) or directly from Aignostics. Check your email for an invitation before proceeding.
@@ -656,3 +712,41 @@ Now that you have an overview of the Aignostics Python SDK and its interfaces, h
 - **Review detailed documentation**: See the [CLI reference](https://aignostics.readthedocs.io/en/latest/cli_reference.html) and [Python Library reference](https://aignostics.readthedocs.io/en/latest/lib_reference.html)
 - **Explore QuPath integration**: Use the QuPath extension to visualize and interact with your results
 - **Get support**: Contact [[email protected]](mailto:[email protected]) or check the [full documentation](https://aignostics.readthedocs.io/en/latest/)
+- **Upgrading from v1?** See the [v2 Migration Guide](https://aignostics.readthedocs.io/en/latest/migration.html) for updated import paths and install instructions
+
+## Migrating from v1 to v2
+
+v2 introduces `aignostics-sdk`, a slim distribution containing only the platform API client.
+The full `aignostics` package now depends on `aignostics-sdk`.
+
+### Import path changes
+
+| v1 | v2 |
+|----|----|
+| `from aignostics.platform import Client` | `from aignostics_sdk.platform import Client` |
+| `from aignostics.utils import BaseService` | `from aignostics_sdk.utils import BaseService` |
+| `from aignostics.constants import INTERNAL_ORGS` | `from aignostics_sdk.constants import INTERNAL_ORGS` |
+
+All other modules (`application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`,
+`system`) remain under the `aignostics.*` namespace and are unchanged.
+
+### CLI changes
+
+The `aignostics` CLI is unchanged. A new `aignostics-sdk` CLI is available when only the slim
+package is installed:
+
+```bash
+# slim install
+aignostics-sdk user login
+aignostics-sdk user whoami
+
+# full install (unchanged)
+aignostics user login
+aignostics application list
+```
+
+### If you only use the API client
+
+Replace `pip install aignostics` with `pip install aignostics-sdk` for a significantly smaller
+install footprint. See the [full migration guide](https://aignostics.readthedocs.io/en/latest/migration.html)
+for a complete checklist.

docs/source/index.rst

@@ -12,6 +12,7 @@
    :hidden:
 
    main
+   migration
    platform_overview
    cli_reference
    lib_reference

docs/source/migration.md

@@ -0,0 +1,112 @@
+# Migrating from v1 to v2
+
+v2 of the Aignostics Python SDK introduces `aignostics-sdk`, a slim distribution that contains
+only the platform API client and core utilities. The full `aignostics` package now depends on
+`aignostics-sdk` and delegates platform/utils functionality to it.
+
+This is a **breaking change** for anyone importing `aignostics.platform` or `aignostics.utils`
+directly.
+
+## What changed
+
+The `platform` and `utils` modules (and `constants`) have moved to a separate PyPI package called
+`aignostics-sdk`. Their Python namespace has changed from `aignostics.*` to `aignostics_sdk.*`.
+
+| v1 (Python namespace) | v2 (Python namespace) |
+|-----------------------|-----------------------|
+| `aignostics.platform` | `aignostics_sdk.platform` |
+| `aignostics.utils` | `aignostics_sdk.utils` |
+| `aignostics.constants` | `aignostics_sdk.constants` |
+
+All other modules (`application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`,
+`system`) remain under the `aignostics.*` namespace and are only available in the full package.
+
+## Import path changes
+
+Update your Python imports as follows:
+
+| v1 import | v2 import |
+|-----------|-----------|
+| `from aignostics.platform import Client` | `from aignostics_sdk.platform import Client` |
+| `from aignostics.platform import InputItem, InputArtifact` | `from aignostics_sdk.platform import InputItem, InputArtifact` |
+| `from aignostics.utils import BaseService` | `from aignostics_sdk.utils import BaseService` |
+| `from aignostics.utils import Health` | `from aignostics_sdk.utils import Health` |
+| `from aignostics.utils import locate_implementations` | `from aignostics_sdk.utils import locate_implementations` |
+| `from aignostics.constants import INTERNAL_ORGS` | `from aignostics_sdk.constants import INTERNAL_ORGS` |
+| `from aignostics import platform` | `from aignostics_sdk import platform` |
+
+## Installation changes
+
+### If you only use the API client
+
+Replace the full package with the slim package for a significantly smaller install footprint:
+
+```bash
+# v1
+pip install aignostics
+
+# v2 — slim install
+pip install aignostics-sdk
+```
+
+The slim `aignostics-sdk` package includes only `platform`, `utils`, and `constants`.
+It has no dependency on OpenSlide, wsidicom, boto3, Google Cloud Storage, or other heavy
+libraries required by the WSI and dataset modules.
+
+### If you use the full SDK
+
+The install command is **unchanged**:
+
+```bash
+pip install aignostics
+```
+
+The full package automatically pulls in `aignostics-sdk` as a dependency, so all
+`aignostics_sdk.*` imports work after installing `aignostics`.
+
+## CLI changes
+
+The `aignostics` CLI command is **unchanged**. A new `aignostics-sdk` CLI entry point is
+registered when the slim package is installed:
+
+```bash
+# Slim install — available commands
+aignostics-sdk user login
+aignostics-sdk user logout
+aignostics-sdk user whoami
+aignostics-sdk sdk run-metadata-schema
+aignostics-sdk sdk item-metadata-schema
+
+# Full install — unchanged command, full feature set
+aignostics user login
+aignostics application list
+aignostics wsi inspect slide.svs
+```
+
+## Health checks using the full SDK
+
+In v1, the health check import was:
+
+```python
+# v1
+from aignostics.system import Service as SystemService
+
+health = SystemService().health()
+```
+
+This is **unchanged** in v2 — `system` remains in the `aignostics` namespace:
+
+```python
+# v2 — same as v1
+from aignostics.system import Service as SystemService
+
+health = SystemService().health()
+```
+
+## Quick migration checklist
+
+1. Update `from aignostics.platform import ...` to `from aignostics_sdk.platform import ...`
+2. Update `from aignostics.utils import ...` to `from aignostics_sdk.utils import ...`
+3. Update `from aignostics.constants import ...` to `from aignostics_sdk.constants import ...`
+4. If you only need the API client, switch `pip install aignostics` to `pip install aignostics-sdk`
+5. If you use the full SDK, keep `pip install aignostics` — no pip change needed