quantikmind-cli 0.1.0__py3-none-any.whl

quantikmind_cli/cli.py

@@ -0,0 +1,1672 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import time
+from typing import Literal
+
+import click
+from rich.console import Console
+from rich.table import Table
+import yaml
+
+from .api import AgentMetricsEndpointUnavailable, ApiError, AuthenticationError, NetworkError, QuantikMindApiClient
+from .agent.prometheus import PrometheusClient, PrometheusError
+from .config import (
+    DEFAULT_BASE_URL,
+    ConfigError,
+    agent_state_path,
+    load_agent_state,
+    credentials_path,
+    load_repo_config,
+    load_credentials,
+    resolve_base_url,
+    write_agent_state,
+    write_credentials,
+    write_repo_config,
+)
+from .git import BuildMetadata, GitError, get_current_build_metadata
+from .manifest import ManifestImportError, load_manifest_payload
+from .record_tests import ResultsImportError, collect_junit_records
+from .scanner import LibraryScanError, SYNC_LIBRARY_FRAMEWORKS, scan_functional_library
+from .subset import (
+    SUBSET_FRAMEWORKS,
+    SubsetError,
+    format_test_selectors,
+    machine_readable_selection_payload,
+    selected_test_selectors,
+    selection_stats,
+)
+
+
+console = Console(width=120)
+
+SUPPORTED_FRAMEWORKS = (
+    "pytest",
+    "jest",
+    "maven",
+    "gradle",
+    "cypress",
+    "playwright",
+    "rspec",
+    "cucumber",
+    "robot",
+    "other",
+)
+
+SelectionReadiness = Literal["ready", "partial", "not_ready", "unknown"]
+READY_SIGNAL_STATES = {"ready", "healthy", "ok", "full"}
+NOT_READY_SIGNAL_STATES = {"insufficient_signal", "not_ready", "unhealthy", "error", "failed"}
+
+DEFAULT_PATHS = {
+    "pytest": ("tests", "test-results"),
+    "jest": ("tests", "coverage"),
+    "maven": ("src/test", "target/surefire-reports"),
+    "gradle": ("src/test", "build/test-results"),
+    "cypress": ("cypress", "cypress/results"),
+    "playwright": ("tests", "test-results"),
+    "rspec": ("spec", "tmp/qmind-results"),
+    "cucumber": ("features", "reports/cucumber"),
+    "robot": ("tests", "results"),
+    "other": ("tests", "qmind-results"),
+}
+
+DEFAULT_PROMETHEUS_URL = "http://localhost:9090"
+DEFAULT_AGENT_PUSH_INTERVAL_SECONDS = 30
+AGENT_REQUIRED_METRICS = (
+    "service_cpu_load",
+    "service_errors_total",
+    "service_requests_total",
+    "service_response_time_seconds_bucket",
+)
+MAX_AGENT_PUSH_BACKOFF_SECONDS = 300
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(package_name="quantikmind-cli")
+def cli() -> None:
+    """Quantik Mind command line tools."""
+
+
+@cli.command()
+@click.option("--api-key", envvar="QMIND_API_KEY", help="Quantik Mind API key.")
+@click.option(
+    "--api-url",
+    envvar="QMIND_API_URL",
+    default=DEFAULT_BASE_URL,
+    show_default=True,
+    help="Quantik Mind API base URL.",
+)
+@click.option("--project-name", envvar="QMIND_PROJECT_NAME", help="Existing project name.")
+@click.option("--project-id", envvar="QMIND_PROJECT_ID", help="Existing internal project UUID.")
+@click.option(
+    "--framework",
+    envvar="QMIND_FRAMEWORK",
+    type=click.Choice(SUPPORTED_FRAMEWORKS),
+    help="Primary test framework.",
+)
+@click.option("--test-dir", envvar="QMIND_TEST_DIR", help="Test directory to record in qmind.yaml.")
+@click.option("--results-dir", envvar="QMIND_RESULTS_DIR", help="Test results directory.")
+@click.option("--non-interactive", is_flag=True, help="Fail instead of prompting for missing values.")
+def init(
+    api_key: str | None,
+    api_url: str,
+    project_name: str | None,
+    project_id: str | None,
+    framework: str | None,
+    test_dir: str | None,
+    results_dir: str | None,
+    non_interactive: bool,
+) -> None:
+    """Create qmind.yaml and connect local credentials."""
+    non_interactive = non_interactive or _is_ci()
+    api_url = api_url.rstrip("/")
+    existing_credentials = _load_existing_credentials()
+    api_key = api_key or existing_credentials.get("api_key")
+
+    if not api_key and non_interactive:
+        raise click.ClickException(
+            "Missing API key. Set QMIND_API_KEY or pass --api-key in CI/non-interactive mode."
+        )
+    if not api_key:
+        api_key = click.prompt("Quantik Mind API key", hide_input=True).strip()
+
+    client = QuantikMindApiClient(base_url=api_url, api_key=api_key)
+    identity: dict | None = None
+    try:
+        identity = client.get_auth_identity()
+    except (AuthenticationError, ApiError):
+        try:
+            client.validate_credentials()
+        except (AuthenticationError, NetworkError, ApiError) as exc:
+            raise click.ClickException(str(exc)) from exc
+    except NetworkError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    cwd = Path.cwd()
+    if not project_name and not project_id:
+        if non_interactive:
+            raise click.ClickException(
+                "Missing project. Pass --project-id or --project-name in CI/non-interactive mode."
+            )
+        project_name = click.prompt("Project name", default=cwd.name).strip()
+
+    selected_project = None
+    if project_id:
+        selected_project = _resolve_existing_project(client, project_id=project_id, project_name=project_name)
+    if not selected_project:
+        try:
+            projects = client.list_projects()
+        except (AuthenticationError, NetworkError, ApiError) as exc:
+            raise click.ClickException(str(exc)) from exc
+
+        selected_project = _select_project(
+            projects,
+            project_id=project_id,
+            project_name=project_name,
+        )
+    if not selected_project:
+        if project_name and not project_id and _identity_can_create_project(identity):
+            try:
+                selected_project = client.create_project(project_name)
+            except AuthenticationError as exc:
+                raise click.ClickException(
+                    "This API key cannot create projects. Create the project in the UI or use an "
+                    "organization-scoped API key with project creation permission."
+                ) from exc
+            except (NetworkError, ApiError) as exc:
+                raise click.ClickException(str(exc)) from exc
+        else:
+            raise click.ClickException(
+                "This API key cannot create projects. Create the project in the UI or use an "
+                "organization-scoped API key with project creation permission."
+            )
+
+    project_id = str(selected_project.get("id") or selected_project.get("project_id") or "")
+    project_name_value = selected_project.get("name") or project_name
+    project_name = str(project_name_value).strip() if project_name_value else ""
+    if project_name == project_id:
+        project_name = ""
+    if not project_id:
+        raise click.ClickException("The selected project response did not include a usable project id.")
+
+    if not framework:
+        if non_interactive:
+            raise click.ClickException(
+                "Missing framework. Pass --framework or set QMIND_FRAMEWORK in CI/non-interactive mode."
+            )
+        framework = click.prompt(
+            "Test framework",
+            type=click.Choice(SUPPORTED_FRAMEWORKS),
+            default="pytest",
+            show_choices=True,
+        )
+
+    default_test_dir, default_results_dir = DEFAULT_PATHS[framework]
+    if not test_dir:
+        if non_interactive:
+            test_dir = default_test_dir
+        else:
+            test_dir = click.prompt("Test directory", default=default_test_dir).strip()
+    if not results_dir:
+        if non_interactive:
+            results_dir = default_results_dir
+        else:
+            results_dir = click.prompt("Results directory", default=default_results_dir).strip()
+
+    repo_config = {
+        "project_id": project_id,
+        "framework": framework,
+        "test_dir": test_dir,
+        "results_dir": results_dir,
+        "api_url": api_url,
+        "agent": {
+            "prometheus_url": "",
+            "push_interval_seconds": 60,
+        },
+    }
+    if project_name:
+        repo_config["project_name"] = project_name
+    repo_config_path = write_repo_config(repo_config, root=cwd)
+    credentials_file = write_credentials(
+        {"api_key": api_key, "auth_mode": _auth_mode_for_api_key(api_key, existing_credentials)},
+        path=credentials_path(),
+    )
+
+    table = Table(title="Quantik Mind setup")
+    table.add_column("Setting")
+    table.add_column("Value")
+    table.add_row("Project", _project_display(project_id=project_id, project_name=project_name))
+    table.add_row("Framework", framework)
+    table.add_row("Test directory", test_dir)
+    table.add_row("Results directory", results_dir)
+    table.add_row("API URL", api_url)
+    table.add_row("Repo config", str(repo_config_path))
+    table.add_row("Credentials", str(credentials_file))
+    console.print(table)
+    _print_next_steps(
+        [
+            ("Preview detected library", "qmind sync library --dry-run"),
+            ("Upload library", "qmind sync library"),
+            ("Check readiness", "qmind status"),
+        ]
+    )
+
+
+@cli.group()
+def record() -> None:
+    """Record build and test execution metadata."""
+
+
+@record.command()
+@click.option("--commit", "commit_hash", help="Commit SHA or build identifier to record.")
+@click.option("--branch", help="Branch name to record with --commit.")
+@click.option("--message", help="Commit/build message to record with --commit.")
+@click.option("--author", help="Author to record with --commit.")
+def build(
+    commit_hash: str | None,
+    branch: str | None,
+    message: str | None,
+    author: str | None,
+) -> None:
+    """Record build metadata."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client.validate_credentials()
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    if commit_hash:
+        metadata = BuildMetadata(
+            commit_hash=commit_hash.strip(),
+            message=(message or commit_hash).strip(),
+            author=(author or "").strip(),
+            timestamp=_utc_timestamp(),
+            branch=branch.strip() if branch else None,
+            files_changed=[],
+        )
+    else:
+        try:
+            metadata = get_current_build_metadata()
+        except GitError as exc:
+            raise click.ClickException(
+                f"{exc}. Run this command inside a git repository with at least one commit, "
+                "or pass --commit <sha-or-id> and optionally --branch <branch>."
+            ) from exc
+
+    try:
+        response = client.record_build_commit(
+            project_id=project_id,
+            commit_hash=metadata.commit_hash,
+            message=metadata.message,
+            author=metadata.author,
+            branch=metadata.branch,
+            files_changed=metadata.files_changed,
+        )
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not record build: {exc}") from exc
+
+    if response.get("status") == "duplicate":
+        console.print(f"[bold green]✓ Build already recorded:[/bold green] {metadata.short_hash}")
+    else:
+        console.print(
+            f"[bold green]✓ Build recorded:[/bold green] {metadata.short_hash} "
+            f"({len(metadata.files_changed)} files changed)"
+        )
+
+
+@record.command("tests")
+@click.option("--results-dir", type=click.Path(path_type=Path), help="Override the qmind.yaml results directory.")
+def record_tests(results_dir: Path | None) -> None:
+    """Record test execution metadata."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    configured_results_dir = results_dir or str(repo_config.get("results_dir") or "").strip()
+    if not configured_results_dir:
+        raise click.ClickException("Missing results_dir in qmind.yaml. Run `qmind init` or pass --results-dir.")
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client.validate_credentials()
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    try:
+        parse_result = collect_junit_records(configured_results_dir)
+    except ResultsImportError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    for warning in parse_result.warnings:
+        click.echo(f"Warning: {warning}", err=True)
+
+    if not parse_result.records:
+        raise click.ClickException("No usable test result records found.")
+
+    try:
+        response = client.import_functional_history(project_id=project_id, records=parse_result.records)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not record test results: {exc}") from exc
+
+    counts = _status_counts(parse_result.records)
+    if response.get("status") == "already_imported":
+        console.print("[bold green]✓ Results already imported[/bold green]")
+    else:
+        console.print(
+            "[bold green]✓ Results recorded:[/bold green] "
+            f"{len(parse_result.records)} tests "
+            f"({counts.get('passed', 0)} passed, {counts.get('failed', 0)} failed"
+            f"{_skipped_summary(counts)})"
+        )
+
+
+@cli.command()
+@click.option(
+    "--framework",
+    type=click.Choice(SUBSET_FRAMEWORKS),
+    help="Override the framework configured in qmind.yaml.",
+)
+@click.option(
+    "--internal-ids",
+    is_flag=True,
+    help="Print backend internal numeric test IDs instead of canonical test_id values.",
+)
+@click.option(
+    "--changed-file",
+    "changed_files",
+    multiple=True,
+    help="Changed source file to use for selection. Repeat for multiple files.",
+)
+@click.option(
+    "--changed-files-file",
+    type=click.Path(path_type=Path, dir_okay=False),
+    help="JSON file containing an array of changed source files.",
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Print the complete selection payload as machine-readable JSON.",
+)
+def subset(
+    framework: str | None,
+    internal_ids: bool,
+    changed_files: tuple[str, ...],
+    changed_files_file: Path | None,
+    json_output: bool,
+) -> None:
+    """Request or inspect selected test subsets."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    selected_framework = framework or str(repo_config.get("framework") or "").strip()
+    if selected_framework not in SUBSET_FRAMEWORKS:
+        raise click.ClickException(
+            "Missing or unsupported framework for qmind subset. "
+            "Set framework in qmind.yaml or pass --framework."
+        )
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        explicit_changed_files = _resolve_subset_changed_files(
+            changed_files=changed_files,
+            changed_files_file=changed_files_file,
+        )
+        response = client.select_functional_tests(
+            project_id,
+            changed_files=explicit_changed_files,
+        )
+        selectors = selected_test_selectors(response, use_internal_ids=internal_ids)
+        if json_output:
+            formatted = json.dumps(
+                machine_readable_selection_payload(response, selected_tests=selectors),
+                indent=2,
+                sort_keys=True,
+            )
+        else:
+            formatted = format_test_selectors(selected_framework, selectors)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not select tests: {exc}") from exc
+    except SubsetError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    stats = selection_stats(response)
+    if stats and not json_output:
+        click.echo(stats, err=True)
+    click.echo(formatted)
+
+
+@cli.group()
+def sync() -> None:
+    """Sync local Quantik Mind resources."""
+
+
+@sync.command("library")
+@click.option(
+    "--framework",
+    type=click.Choice(SYNC_LIBRARY_FRAMEWORKS),
+    help="Override the framework configured in qmind.yaml.",
+)
+@click.option("--test-dir", type=click.Path(path_type=Path), help="Override the qmind.yaml test directory.")
+@click.option(
+    "--manifest",
+    type=click.Path(path_type=Path),
+    help="Import an explicit YAML or JSON enterprise test inventory manifest.",
+)
+@click.option(
+    "--file",
+    "library_file",
+    type=click.Path(path_type=Path),
+    help="Import an explicit YAML or JSON test library file.",
+)
+@click.option("--dry-run", is_flag=True, help="Generate and validate the library without uploading it.")
+@click.option(
+    "--output",
+    type=click.Path(path_type=Path, dir_okay=False),
+    help="Write the generated library payload to a JSON file.",
+)
+def sync_library(
+    framework: str | None,
+    test_dir: Path | None,
+    manifest: Path | None,
+    library_file: Path | None,
+    dry_run: bool,
+    output: Path | None,
+) -> None:
+    """Generate and upload a functional test library from local tests."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    explicit_library_file = library_file or manifest
+    if manifest and library_file:
+        raise click.ClickException("Pass only one explicit library input: --file or --manifest.")
+
+    if explicit_library_file:
+        try:
+            payload = load_manifest_payload(explicit_library_file)
+        except ManifestImportError as exc:
+            raise click.ClickException(str(exc)) from exc
+        if not payload:
+            raise click.ClickException(f"No tests found in library file: {explicit_library_file}.")
+    else:
+        selected_framework = framework or str(repo_config.get("framework") or "").strip()
+        if selected_framework not in SYNC_LIBRARY_FRAMEWORKS:
+            raise click.ClickException(
+                "Missing or unsupported framework for qmind sync library. "
+                "Set framework in qmind.yaml or pass --framework."
+            )
+
+        selected_test_dir = test_dir or str(repo_config.get("test_dir") or "").strip()
+        if not selected_test_dir:
+            raise click.ClickException("Missing test_dir in qmind.yaml. Run `qmind init` or pass --test-dir.")
+
+    client = None
+    if not dry_run:
+        try:
+            credentials = load_credentials(path=credentials_path())
+        except ConfigError as exc:
+            raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+        client = QuantikMindApiClient.from_config(repo_config, credentials)
+        try:
+            client.validate_credentials()
+        except AuthenticationError as exc:
+            raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+        except (NetworkError, ApiError) as exc:
+            raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    if not explicit_library_file:
+        try:
+            scan_result = scan_functional_library(selected_framework, selected_test_dir, root=Path.cwd())
+        except LibraryScanError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+        for warning in scan_result.warnings:
+            click.echo(f"Warning: {warning}", err=True)
+
+        if not scan_result.tests:
+            raise click.ClickException(f"No tests found for {selected_framework} in {selected_test_dir}.")
+
+        payload = scan_result.payload(Path.cwd())
+    _validate_library_payload(payload)
+
+    if output:
+        _write_library_payload(output, payload)
+
+    if dry_run:
+        console.print(f"[bold green]✓ Test library dry run complete:[/bold green] {len(payload)} tests discovered")
+        breakdown = _library_breakdown(payload, include_criticality=True)
+        if breakdown:
+            console.print(breakdown)
+        if output:
+            click.echo(f"Output written to {output}")
+        console.print("Upload skipped because --dry-run is enabled.")
+        next_steps = [("Upload this library", "qmind sync library")]
+        if not output:
+            next_steps.append(("Export preview", "qmind sync library --dry-run --output qmind-library.preview.json"))
+        _print_next_steps(next_steps)
+        return
+
+    try:
+        if client is None:
+            raise click.ClickException("Could not sync test library: API client was not initialized.")
+        response = client.upload_functional_library(project_id, payload)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not sync test library: {exc}") from exc
+
+    errors = response.get("errors") or []
+    if errors:
+        raise click.ClickException(_library_upload_error_summary(response))
+
+    uploaded = _uploaded_library_count(response, len(payload))
+    if uploaded == 0 and response.get("skipped"):
+        console.print("[bold green]✓ Test library already up to date[/bold green]")
+    elif explicit_library_file:
+        console.print(f"[bold green]✓ Test library synced from file:[/bold green] {uploaded} tests uploaded")
+    else:
+        console.print(f"[bold green]✓ Test library synced:[/bold green] {uploaded} tests uploaded")
+    breakdown = _library_breakdown(payload)
+    if breakdown:
+        console.print(breakdown)
+    _print_duration_estimation_warning(response)
+    _print_next_steps(
+        [
+            ("Record a build", "qmind record build"),
+            ("Ask for a subset", "qmind subset"),
+            ("Import test results after running tests", "qmind record tests --results-dir <path>"),
+        ]
+    )
+
+
+@cli.group()
+def agent() -> None:
+    """Manage the local Quantik Mind agent."""
+
+
+@agent.command("init")
+@click.option("--prometheus-url", help="Prometheus base URL.")
+@click.option(
+    "--push-interval",
+    type=click.IntRange(min=1),
+    default=DEFAULT_AGENT_PUSH_INTERVAL_SECONDS,
+    show_default=True,
+    help="Metric push interval in seconds.",
+)
+def agent_init(prometheus_url: str | None, push_interval: int) -> None:
+    """Initialize local agent configuration."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client.validate_credentials()
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    if not prometheus_url and _is_ci():
+        raise click.ClickException("Missing Prometheus URL. Pass --prometheus-url in CI/non-interactive mode.")
+    if not prometheus_url:
+        prometheus_url = click.prompt("Prometheus URL", default=DEFAULT_PROMETHEUS_URL).strip()
+
+    try:
+        prometheus = PrometheusClient(prometheus_url)
+        prometheus.check_connectivity()
+    except PrometheusError as exc:
+        raise click.ClickException(f"Could not connect to Prometheus: {exc}") from exc
+
+    console.print(f"[green]Prometheus connectivity ok:[/green] {prometheus.base_url}")
+    for metric_name in AGENT_REQUIRED_METRICS:
+        check = prometheus.check_metric(metric_name)
+        if check.warning:
+            console.print(f"[yellow]Warning:[/yellow] {metric_name}: not found ({check.warning})")
+        elif check.found:
+            console.print(f"[green]found[/green] {metric_name}")
+        else:
+            console.print(f"[yellow]not found[/yellow] {metric_name}")
+
+    agent_config = dict(repo_config.get("agent") or {})
+    agent_config.update(
+        {
+            "prometheus_url": prometheus.base_url,
+            "push_interval_seconds": push_interval,
+        }
+    )
+    repo_config["agent"] = agent_config
+    repo_config_path = write_repo_config(repo_config, root=Path.cwd())
+
+    console.print(f"[bold green]✓ Agent configuration saved:[/bold green] {repo_config_path}")
+    console.print("Agent pushes metrics outbound; no inbound firewall rule is required.")
+    _print_next_steps([("Start the agent", "qmind agent start")])
+
+
+@agent.command("start")
+@click.option("--once", is_flag=True, help="Run one collect-and-push cycle and exit.")
+@click.option("--interval", type=click.IntRange(min=1), help="Override qmind.yaml push interval in seconds.")
+def agent_start(once: bool, interval: int | None) -> None:
+    """Start the local agent."""
+    repo_config, project_id, client = _load_agent_runtime()
+    agent_config = _agent_config(repo_config)
+    prometheus_url = str(agent_config.get("prometheus_url") or "").strip()
+    if not prometheus_url:
+        raise click.ClickException("Missing agent.prometheus_url in qmind.yaml. Run `qmind agent init` first.")
+
+    configured_interval = interval or int(agent_config.get("push_interval_seconds") or 0)
+    if configured_interval < 1:
+        raise click.ClickException("Missing agent.push_interval_seconds in qmind.yaml. Run `qmind agent init` first.")
+
+    prometheus = PrometheusClient(prometheus_url)
+    push_failures = 0
+    console.print(f"Starting qmind agent for project {project_id}. Press Ctrl+C to stop.")
+
+    try:
+        while True:
+            pushed, push_failed = _run_agent_cycle(
+                project_id=project_id,
+                prometheus=prometheus,
+                client=client,
+            )
+            push_failures = push_failures + 1 if push_failed else 0
+            if once:
+                break
+            sleep_seconds = _agent_sleep_seconds(configured_interval, push_failures)
+            time.sleep(sleep_seconds)
+    except KeyboardInterrupt:
+        console.print(f"{_agent_log_prefix()} Agent stopped.")
+
+
+@agent.command("status")
+def agent_status() -> None:
+    """Show local agent status."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    agent_config = repo_config.get("agent")
+    if not isinstance(agent_config, dict):
+        raise click.ClickException("Missing agent config in qmind.yaml. Run `qmind agent init` first.")
+
+    state = load_agent_state(path=agent_state_path())
+    table = Table(title="Quantik Mind agent status")
+    table.add_column("Setting")
+    table.add_column("Value")
+    table.add_row("Prometheus URL", str(agent_config.get("prometheus_url") or "not configured"))
+    table.add_row("Push interval", str(agent_config.get("push_interval_seconds") or "not configured"))
+    table.add_row("Last push at", str(state.get("last_push_at") or "never"))
+    table.add_row("Last services count", str(state.get("last_services_count") or "0"))
+    console.print(table)
+
+
+@agent.command("stop")
+def agent_stop() -> None:
+    """Stop the local agent."""
+    console.print("qmind agent stop is not implemented yet.")
+
+
+@cli.group()
+def observability() -> None:
+    """Configure project observability."""
+
+
+@observability.group()
+def configure() -> None:
+    """Configure an observability provider."""
+
+
+@configure.command("prometheus")
+@click.option("--url", "prometheus_url", help="Prometheus base URL.")
+@click.option("--file", "config_file", type=click.Path(path_type=Path), help="YAML Prometheus signal mapping.")
+@click.option("--service-label", help="Prometheus label that identifies services.")
+def observability_configure_prometheus(
+    prometheus_url: str | None,
+    config_file: Path | None,
+    service_label: str | None,
+) -> None:
+    """Configure project-scoped Prometheus observability."""
+    if not prometheus_url and not config_file:
+        raise click.ClickException("Pass --url or --file.")
+    if prometheus_url and config_file:
+        raise click.ClickException("Pass only one Prometheus input: --url or --file.")
+
+    repo_config, project_id, client = _load_agent_runtime()
+    payload = (
+        _load_prometheus_observability_file(config_file)
+        if config_file
+        else {"url": prometheus_url}
+    )
+    payload["project_id"] = project_id
+    if service_label:
+        payload["service_label"] = service_label
+
+    try:
+        response = client.configure_prometheus_observability(payload)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not configure Prometheus observability: {exc}") from exc
+
+    observability_config = dict(repo_config.get("observability") or {})
+    observability_config.update(
+        {
+            "provider": "prometheus",
+            "service_label": response.get("service_label") or payload.get("service_label") or "service",
+            "mode": response.get("mode") or payload.get("mode"),
+            "selected_job": response.get("selected_job") or response.get("effective_job"),
+            "profile_ready": response.get("profile_ready"),
+        }
+    )
+    repo_config["observability"] = observability_config
+    write_repo_config(repo_config, root=Path.cwd())
+
+    signals = response.get("configured_signals") or []
+    console.print("[bold green]✓ Prometheus observability configured[/bold green]")
+    if response.get("preset"):
+        console.print(f"Preset: {response.get('preset')}")
+    if response.get("mode"):
+        console.print(f"Mode: {response.get('mode')}")
+    if response.get("effective_job"):
+        console.print(f"Effective job: {response.get('effective_job')}")
+    if response.get("job_ambiguous"):
+        console.print("[yellow]Prometheus job is ambiguous; no job was selected.[/yellow]")
+    valid_jobs = response.get("valid_jobs") or []
+    if valid_jobs:
+        console.print("Valid jobs: " + ", ".join(str(job) for job in valid_jobs))
+    profile_state = str(response.get("profile_state") or "ready")
+    console.print(f"Detected profile: {profile_state}")
+    detected_signals = response.get("detected_signals") or []
+    missing_signals = response.get("missing_signals") or []
+    invalid_signals = response.get("invalid_signals") or []
+    if detected_signals:
+        console.print("Validated signals: " + ", ".join(str(signal) for signal in detected_signals))
+    missing_or_invalid = _dedupe_display_values(list(missing_signals) + list(invalid_signals))
+    if missing_or_invalid:
+        console.print(
+            "[yellow]Missing/invalid signals:[/yellow] "
+            + ", ".join(str(signal) for signal in missing_or_invalid)
+        )
+    details = str(response.get("details") or "").strip()
+    if details:
+        console.print(f"Reason: {details}")
+    if signals:
+        console.print("Signals: " + ", ".join(str(signal) for signal in signals))
+    _print_next_steps([("Check observability", "qmind observability status"), ("Check readiness", "qmind status")])
+
+
+@observability.command("status")
+def observability_status() -> None:
+    """Show project observability status."""
+    _repo_config, project_id, client = _load_agent_runtime()
+    try:
+        status = client.get_observability_status(project_id)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not load observability status: {exc}") from exc
+
+    table = Table(title="Quantik Mind observability")
+    table.add_column("Check")
+    table.add_column("Value")
+    table.add_row("Enabled", _plain_bool(status.get("observability_enabled", True)))
+    table.add_row("Provider", str(status.get("provider") or "not configured"))
+    table.add_row("Runtime/observability readiness", str(status.get("readiness") or status.get("status") or "unknown"))
+    table.add_row("Service label", str(status.get("service_label") or "not configured"))
+    table.add_row("Mode", str(status.get("mode") or "unknown"))
+    table.add_row("Profile source", str(status.get("profile_source") or "unknown"))
+    table.add_row("Effective job", str(status.get("effective_job") or "none"))
+    table.add_row("Effective job regex", str(status.get("effective_job_regex") or "none"))
+    table.add_row("Signals", ", ".join(status.get("configured_signals") or []) or "none")
+    table.add_row("Validated signals", ", ".join(status.get("detected_signals") or []) or "none")
+    missing_or_invalid = _dedupe_display_values(
+        list(status.get("missing_signals") or []) + list(status.get("invalid_signals") or [])
+    )
+    table.add_row("Missing/invalid signals", ", ".join(missing_or_invalid) or "none")
+    table.add_row("Details", str(status.get("details") or ""))
+    console.print(table)
+
+
+def _dedupe_display_values(values: list) -> list[str]:
+    seen = set()
+    out = []
+    for value in values:
+        text = str(value)
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        out.append(text)
+    return out
+
+
+def _load_agent_runtime() -> tuple[dict, str, QuantikMindApiClient]:
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` from the repository root first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client.validate_credentials()
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    return repo_config, project_id, client
+
+
+def _load_prometheus_observability_file(path: Path) -> dict:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as exc:
+        raise click.ClickException(f"Could not read Prometheus config file {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise click.ClickException(f"Prometheus config file must contain a YAML mapping: {path}")
+
+    observability_config = data.get("observability", data)
+    if not isinstance(observability_config, dict):
+        raise click.ClickException("observability must be a mapping.")
+    if str(observability_config.get("provider") or "prometheus") != "prometheus":
+        raise click.ClickException("Only provider: prometheus is supported by this command.")
+
+    url = str(observability_config.get("url") or "").strip()
+    if not url:
+        raise click.ClickException("Prometheus config file is missing observability.url.")
+
+    signals_input = observability_config.get("signals") or {}
+    if not isinstance(signals_input, dict):
+        raise click.ClickException("observability.signals must be a mapping.")
+
+    signals: dict[str, dict] = {}
+    for name, config in signals_input.items():
+        if not isinstance(config, dict):
+            raise click.ClickException(f"observability.signals.{name} must be a mapping.")
+        query = str(config.get("query") or config.get("query_template") or "").strip()
+        if not query:
+            raise click.ClickException(f"observability.signals.{name}.query is required.")
+        signals[str(name)] = {
+            "query": query,
+            "unit": config.get("unit") or "value",
+            "direction": config.get("direction") or "higher_is_riskier",
+            "weight": config.get("weight") or 0.0,
+        }
+
+    services_input = observability_config.get("services") or {}
+    if not isinstance(services_input, dict):
+        raise click.ClickException("observability.services must be a mapping.")
+    services: dict[str, dict] = {}
+    for service_name, service_config in services_input.items():
+        if not isinstance(service_config, dict):
+            raise click.ClickException(f"observability.services.{service_name} must be a mapping.")
+        query_input = service_config.get("queries") or service_config.get("signals") or {}
+        if not isinstance(query_input, dict):
+            raise click.ClickException(f"observability.services.{service_name}.queries must be a mapping.")
+        queries = {}
+        for name, config in query_input.items():
+            if isinstance(config, str):
+                config = {"query": config}
+            if not isinstance(config, dict):
+                raise click.ClickException(
+                    f"observability.services.{service_name}.queries.{name} must be a mapping or query string."
+                )
+            query = str(config.get("query") or config.get("query_template") or "").strip()
+            if not query:
+                raise click.ClickException(
+                    f"observability.services.{service_name}.queries.{name}.query is required."
+                )
+            queries[str(name)] = {
+                "query": query,
+                "unit": config.get("unit") or "value",
+                "direction": config.get("direction") or "higher_is_riskier",
+                "weight": config.get("weight") or 0.0,
+            }
+        services[str(service_name)] = {"queries": queries}
+
+    return {
+        "url": url,
+        "service_label": observability_config.get("service_label") or "service",
+        "lookback": observability_config.get("lookback") or "5m",
+        "signals": signals,
+        "services": services,
+        "mode": "file",
+    }
+
+
+def _agent_config(repo_config: dict) -> dict:
+    agent_config = repo_config.get("agent")
+    if not isinstance(agent_config, dict):
+        raise click.ClickException("Missing agent config in qmind.yaml. Run `qmind agent init` first.")
+    return agent_config
+
+
+def _run_agent_cycle(
+    *,
+    project_id: str,
+    prometheus: PrometheusClient,
+    client: QuantikMindApiClient,
+) -> tuple[bool, bool]:
+    try:
+        metrics = prometheus.collect_service_metrics()
+    except PrometheusError as exc:
+        console.print(f"{_agent_log_prefix()} [yellow]⚠ Prometheus unavailable:[/yellow] {exc}")
+        return False, False
+
+    if not metrics:
+        console.print(f"{_agent_log_prefix()} [yellow]⚠ No service metrics found.[/yellow]")
+        return False, False
+
+    timestamp = _utc_timestamp()
+    payload = {
+        "project_id": project_id,
+        "timestamp": timestamp,
+        "metrics": metrics,
+    }
+    try:
+        client.push_agent_metrics(payload)
+    except AgentMetricsEndpointUnavailable as exc:
+        console.print(f"{_agent_log_prefix()} [yellow]⚠ Agent metrics endpoint unavailable:[/yellow] {exc}")
+        return False, True
+    except (AuthenticationError, NetworkError, ApiError) as exc:
+        console.print(f"{_agent_log_prefix()} [yellow]⚠ Could not push agent metrics:[/yellow] {exc}")
+        return False, True
+
+    services_count = len(metrics)
+    write_agent_state(
+        {
+            "last_push_at": timestamp,
+            "last_services_count": services_count,
+            "prometheus_url": prometheus.base_url,
+        },
+        path=agent_state_path(),
+    )
+    console.print(f"{_agent_log_prefix(timestamp)} [green]✓ Pushed metrics for {services_count} services[/green]")
+    return True, False
+
+
+def _agent_sleep_seconds(interval: int, push_failures: int) -> int:
+    if push_failures <= 0:
+        return interval
+    backoff = interval * (2 ** min(push_failures - 1, 6))
+    return min(backoff, MAX_AGENT_PUSH_BACKOFF_SECONDS)
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _agent_log_prefix(timestamp: str | None = None) -> str:
+    return f"[{timestamp or _utc_timestamp()}]"
+
+
+def _is_ci() -> bool:
+    return os.getenv("CI", "").strip().lower() == "true"
+
+
+def _load_existing_credentials() -> dict[str, str]:
+    try:
+        return load_credentials(path=credentials_path())
+    except ConfigError:
+        return {}
+
+
+def _resolve_existing_project(
+    client: QuantikMindApiClient,
+    *,
+    project_id: str,
+    project_name: str | None,
+) -> dict:
+    project_id = project_id.strip()
+    if not project_id:
+        return {}
+
+    get_project = getattr(client, "get_project", None)
+    if callable(get_project):
+        try:
+            project = get_project(project_id)
+        except (AuthenticationError, NetworkError, ApiError):
+            project = None
+        if isinstance(project, dict):
+            resolved_id = str(project.get("id") or project.get("project_id") or project_id)
+            return {**project, "id": resolved_id}
+
+    project: dict = {"id": project_id}
+    if project_name:
+        project["name"] = project_name
+    return project
+
+
+def _auth_mode_for_api_key(api_key: str, existing_credentials: dict) -> str:
+    if _looks_like_quantikmind_api_key(api_key):
+        return "api_key"
+    existing_auth_mode = str(existing_credentials.get("auth_mode") or "").strip()
+    return existing_auth_mode or "bearer"
+
+
+def _looks_like_quantikmind_api_key(value: str) -> bool:
+    return value.startswith(("qm_dev_", "qm_live_"))
+
+
+def _project_display(*, project_id: str, project_name: str | None) -> str:
+    name = str(project_name or "").strip()
+    if name and name != project_id:
+        return f"{name} ({project_id})"
+    return project_id
+
+
+def _select_project(
+    projects: list[dict],
+    *,
+    project_id: str | None,
+    project_name: str | None,
+) -> dict | None:
+    if project_id:
+        for project in projects:
+            candidate_ids = {
+                str(project.get("id") or ""),
+                str(project.get("project_id") or ""),
+            }
+            if project_id in candidate_ids:
+                return project
+        return None
+
+    if project_name:
+        normalized_name = project_name.strip().lower()
+        for project in projects:
+            if str(project.get("name", "")).strip().lower() == normalized_name:
+                return project
+    return None
+
+
+def _identity_can_create_project(identity: dict | None) -> bool:
+    if not identity:
+        return False
+    return bool(identity.get("user_id")) and identity.get("principal_type") != "service_account"
+
+
+def _status_counts(records: list[dict]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for record in records:
+        status = str(record.get("status") or "unknown")
+        counts[status] = counts.get(status, 0) + 1
+    return counts
+
+
+def _skipped_summary(counts: dict[str, int]) -> str:
+    skipped = counts.get("skipped", 0)
+    return f", {skipped} skipped" if skipped else ""
+
+
+def _uploaded_library_count(response: dict, fallback: int) -> int:
+    added = response.get("added")
+    updated = response.get("updated")
+    if isinstance(added, int) and isinstance(updated, int):
+        return added + updated
+    return fallback
+
+
+def _library_upload_error_summary(response: dict) -> str:
+    rejected = response.get("skipped")
+    errors = response.get("errors") or []
+    reasons: list[str] = []
+    for error in errors:
+        if isinstance(error, dict):
+            reason = str(error.get("error") or "").strip()
+        else:
+            reason = str(error).strip()
+        if reason and reason not in reasons:
+            reasons.append(reason)
+    reason_text = "\n".join(reasons) if reasons else "Backend rejected the library payload."
+    parts = ["Test library upload failed"]
+    if isinstance(rejected, int):
+        parts.append(f"Rejected tests: {rejected}")
+    parts.append(f"Reason:\n{reason_text}")
+    return "\n\n".join(parts)
+
+
+def _print_duration_estimation_warning(response: dict) -> None:
+    estimated = response.get("estimated_durations")
+    if not isinstance(estimated, int) or estimated <= 0:
+        return
+    source = str(response.get("duration_estimation_source") or "framework_default")
+    strategy = (
+        "framework-based estimated durations"
+        if source == "framework_default"
+        else f"{source} estimated durations"
+    )
+    plural = "test" if estimated == 1 else "tests"
+    console.print(f"[yellow]Warning:[/yellow] {estimated} {plural} had no duration information.")
+    console.print(
+        f"Quantik Mind assigned {strategy} to bootstrap time-saving calculations."
+    )
+    console.print(
+        "Savings metrics are approximate until real execution history is recorded."
+    )
+
+
+def _validate_library_payload(payload: list[dict]) -> None:
+    required_fields = ("test_id", "name", "framework", "service")
+    for index, item in enumerate(payload, start=1):
+        missing = [field for field in required_fields if not item.get(field)]
+        if missing:
+            raise click.ClickException(f"Generated library payload item {index} is missing: {', '.join(missing)}.")
+
+
+def _write_library_payload(path: Path, payload: list[dict]) -> None:
+    try:
+        if path.exists() and path.is_dir():
+            raise OSError(f"Output path is a directory: {path}")
+        if path.parent and path.parent != Path("."):
+            path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise click.ClickException(f"Could not write library payload to {path}: {exc}") from exc
+
+
+def _resolve_subset_changed_files(
+    *,
+    changed_files: tuple[str, ...],
+    changed_files_file: Path | None,
+) -> list[str] | None:
+    values = [item.strip() for item in changed_files if item.strip()]
+    if changed_files_file is not None:
+        values.extend(_load_changed_files_file(changed_files_file))
+    return values or None
+
+
+def _load_changed_files_file(path: Path) -> list[str]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise click.ClickException(f"Could not read changed files file {path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"Changed files file must be valid JSON: {exc}") from exc
+
+    if not isinstance(payload, list):
+        raise click.ClickException("Changed files file must contain a JSON array of paths.")
+
+    if not all(isinstance(item, str) and item.strip() for item in payload):
+        raise click.ClickException("Changed files file entries must be non-empty path values.")
+    return [item.strip() for item in payload]
+
+
+def _library_breakdown(payload: list[dict], *, include_criticality: bool = False) -> str:
+    by_framework: dict[str, int] = {}
+    by_service: dict[str, int] = {}
+    by_criticality: dict[str, int] = {}
+    for item in payload:
+        framework = str(item.get("framework") or "unknown")
+        service = str(item.get("service") or "default")
+        by_framework[framework] = by_framework.get(framework, 0) + 1
+        by_service[service] = by_service.get(service, 0) + 1
+        if include_criticality:
+            criticality = str(item.get("business_criticality") or "unknown")
+            by_criticality[criticality] = by_criticality.get(criticality, 0) + 1
+
+    parts: list[str] = []
+    if by_framework:
+        parts.append("frameworks: " + _format_counts(by_framework))
+    if by_service:
+        parts.append("services: " + _format_counts(by_service))
+    if by_criticality:
+        parts.append("criticality: " + _format_counts(by_criticality))
+    return "; ".join(parts)
+
+
+def _format_counts(counts: dict[str, int]) -> str:
+    return ", ".join(f"{name}={count}" for name, count in sorted(counts.items()))
+
+
+def _print_next_steps(steps: list[tuple[str, str]]) -> None:
+    console.print("[bold]Next steps:[/bold]")
+    for label, command in steps:
+        console.print(f"  {label}: [cyan]{command}[/cyan]")
+
+
+@cli.command()
+def status() -> None:
+    """Show qmind configuration status."""
+    try:
+        repo_config = load_repo_config(root=Path.cwd())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run qmind init first.") from exc
+
+    project_id = str(repo_config.get("project_id") or "").strip()
+    if not project_id:
+        raise click.ClickException("Missing project_id in qmind.yaml. Run `qmind init` to configure this repo.")
+
+    try:
+        credentials = load_credentials(path=credentials_path())
+    except ConfigError as exc:
+        raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
+
+    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client.validate_credentials()
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not validate Quantik Mind credentials: {exc}") from exc
+
+    try:
+        readiness = client.get_signal_readiness(project_id)
+    except AuthenticationError as exc:
+        raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
+    except (NetworkError, ApiError) as exc:
+        raise click.ClickException(f"Could not load signal readiness: {exc}") from exc
+
+    subscription: dict | None = None
+    subscription_warning: str | None = None
+    observability_status_payload: dict | None = None
+    observability_warning: str | None = None
+    get_observability_status = getattr(client, "get_observability_status", None)
+    if callable(get_observability_status):
+        try:
+            observability_status_payload = get_observability_status(project_id)
+        except (AuthenticationError, NetworkError, ApiError) as exc:
+            observability_warning = str(exc)
+
+    try:
+        subscription = client.get_subscription()
+    except (AuthenticationError, NetworkError, ApiError) as exc:
+        subscription_warning = str(exc)
+
+    console.print(_status_table(repo_config, readiness, subscription, observability_status_payload))
+    if observability_warning:
+        console.print(f"[yellow]Warning:[/yellow] Observability status unavailable: {observability_warning}")
+    if subscription_warning:
+        console.print(f"[yellow]Warning:[/yellow] Subscription usage unavailable: {subscription_warning}")
+    _print_status_guidance(readiness)
+
+
+def _status_table(
+    repo_config: dict,
+    readiness: dict,
+    subscription: dict | None,
+    observability_status_payload: dict | None = None,
+) -> Table:
+    table = Table(title="Quantik Mind status")
+    table.add_column("Check", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Details")
+
+    project_name = str(repo_config.get("project_name") or "unknown")
+    project_id = str(repo_config.get("project_id") or "unknown")
+    table.add_row("Project name", project_name, "")
+    table.add_row("Project ID", project_id, "")
+    table.add_row("API URL", resolve_base_url(repo_config), "")
+    table.add_row("API connectivity/auth", "[green]ok[/green]", "Credentials validated")
+    table.add_row(
+        "Test library readiness",
+        _bool_status(readiness.get("has_test_library")),
+        _library_details(readiness),
+    )
+    table.add_row(
+        "Historical data readiness",
+        _bool_status(readiness.get("has_historical_signal")),
+        "",
+    )
+    table.add_row(
+        "Observability configuration",
+        _runtime_status(readiness, observability_status_payload),
+        _runtime_details(readiness, observability_status_payload),
+    )
+    table.add_row(
+        "Runtime signal usability",
+        _bool_status(readiness.get("has_runtime_signal")),
+        "usable by selection" if readiness.get("has_runtime_signal") is True else "not usable by selection",
+    )
+    table.add_row(
+        "Selection readiness",
+        _selection_readiness_status(readiness),
+        _readiness_details(readiness),
+    )
+    table.add_row("Subscription/free-tier usage", _subscription_status(subscription), _subscription_details(subscription))
+    return table
+
+
+def _print_status_guidance(readiness: dict) -> None:
+    selection_readiness = derive_selection_readiness(readiness)
+    if selection_readiness == "ready":
+        console.print(
+            "[green]Ready:[/green] library, history, and runtime signal are all available."
+        )
+        console.print("Next step: [cyan]qmind subset[/cyan]")
+        return
+
+    if selection_readiness == "not_ready":
+        missing = _missing_readiness_dimensions(readiness)
+        if missing:
+            console.print(f"[yellow]Not ready:[/yellow] {', '.join(missing)}.")
+        else:
+            console.print("[yellow]Not ready:[/yellow] qmind subset needs an uploaded library and enough signal.")
+        command = _next_status_command(readiness)
+        if command:
+            console.print(f"Next step: [cyan]{command}[/cyan]")
+        return
+
+    if selection_readiness == "partial":
+        console.print(
+            "[yellow]Partially ready:[/yellow] qmind subset may work, but selections improve with more history or runtime signal."
+        )
+        command = _next_status_command(readiness)
+        if command:
+            console.print(f"Next step: [cyan]{command}[/cyan]")
+        return
+
+    if selection_readiness == "unknown":
+        console.print(
+            "Readiness is unknown. Check qmind.yaml, credentials, and the backend readiness endpoint before relying on qmind subset."
+        )
+
+
+def _missing_readiness_dimensions(readiness: dict) -> list[str]:
+    missing = []
+    if readiness.get("has_test_library") is False:
+        missing.append(
+            "test library disabled"
+            if readiness.get("test_library_enabled") is False
+            else "missing library"
+        )
+    if readiness.get("has_historical_signal") is False:
+        missing.append(
+            "historical data disabled"
+            if readiness.get("historical_data_enabled") is False
+            else "missing history"
+        )
+    if readiness.get("has_runtime_signal") is False:
+        missing.append(
+            "observability disabled"
+            if readiness.get("observability_enabled") is False
+            else "missing runtime signal"
+        )
+    if readiness.get("sample_limit_reached") is True:
+        missing.append("sample limit reached")
+    return missing
+
+
+def _next_status_command(readiness: dict) -> str:
+    if readiness.get("has_test_library") is False or readiness.get("sample_limit_reached") is True:
+        if readiness.get("test_library_enabled") is False:
+            return "enable test library in Settings"
+        return "qmind sync library"
+    if readiness.get("has_historical_signal") is False:
+        if readiness.get("historical_data_enabled") is False:
+            return "enable historical data in Settings"
+        return "qmind record tests --results-dir <path>"
+    if readiness.get("has_runtime_signal") is False:
+        if readiness.get("observability_enabled") is False:
+            return "enable observability in Settings"
+        return "qmind observability configure prometheus --url <url>"
+    return ""
+
+
+def _bool_status(value: object) -> str:
+    if value is True:
+        return "[green]ready[/green]"
+    if value is False:
+        return "[yellow]not ready[/yellow]"
+    return "unknown"
+
+
+def _runtime_status(readiness: dict, observability_status_payload: dict | None) -> str:
+    status = str((observability_status_payload or {}).get("status") or "").strip()
+    readiness_label = str((observability_status_payload or {}).get("readiness") or "").strip()
+    if (observability_status_payload or {}).get("observability_enabled") is False or readiness.get("observability_enabled") is False:
+        return "[yellow]disabled[/yellow]"
+    if status == "not_configured" or readiness_label == "not configured":
+        return "[yellow]not configured[/yellow]"
+    if status == "error" or readiness_label == "error":
+        return "[yellow]error[/yellow]"
+    if status == "partial" or readiness_label == "partial":
+        return "[yellow]partial[/yellow]"
+    if status in {"configured", "ready"}:
+        return "[green]ready[/green]" if status == "ready" else "[yellow]configured[/yellow]"
+    return _bool_status(readiness.get("has_runtime_signal"))
+
+
+def _runtime_details(readiness: dict, observability_status_payload: dict | None) -> str:
+    if readiness.get("observability_enabled") is False and not observability_status_payload:
+        return "disabled in project settings"
+    if not observability_status_payload:
+        return ""
+    parts = []
+    if observability_status_payload.get("observability_enabled") is False:
+        parts.append("disabled in project settings")
+    provider = observability_status_payload.get("provider")
+    service_label = observability_status_payload.get("service_label")
+    signals = observability_status_payload.get("configured_signals") or []
+    details = observability_status_payload.get("details")
+    mode = observability_status_payload.get("mode")
+    profile_source = observability_status_payload.get("profile_source")
+    effective_job = observability_status_payload.get("effective_job")
+    effective_job_regex = observability_status_payload.get("effective_job_regex")
+    if provider:
+        parts.append(f"provider={provider}")
+    if service_label:
+        parts.append(f"service_label={service_label}")
+    if mode:
+        parts.append(f"mode={mode}")
+    if profile_source:
+        parts.append(f"profile_source={profile_source}")
+    if effective_job:
+        parts.append(f"effective_job={effective_job}")
+    if effective_job_regex:
+        parts.append(f"effective_job_regex={effective_job_regex}")
+    if signals:
+        parts.append("signals=" + ",".join(str(signal) for signal in signals))
+    if details:
+        parts.append(str(details))
+    configured = str(observability_status_payload.get("status") or "").strip() in {"configured", "ready"}
+    if configured and readiness.get("has_runtime_signal") is False:
+        parts.append("Prometheus configured, but no usable runtime metrics extracted for selection.")
+    return ", ".join(parts)
+
+
+def _library_details(readiness: dict) -> str:
+    parts = []
+    if readiness.get("test_library_enabled") is False:
+        parts.append("disabled in project settings")
+    if "has_real_library" in readiness:
+        parts.append(f"real={_plain_bool(readiness.get('has_real_library'))}")
+    if "has_sample_library" in readiness:
+        parts.append(f"sample={_plain_bool(readiness.get('has_sample_library'))}")
+    return ", ".join(parts)
+
+
+def _readiness_details(readiness: dict) -> str:
+    parts = ["derived from signal readiness"]
+    for key in (
+        "state",
+        "signal_state",
+        "effective_mode",
+        "signal_override",
+        "test_library_enabled",
+        "historical_data_enabled",
+        "observability_enabled",
+    ):
+        if key in readiness:
+            parts.append(f"{key}={readiness.get(key)}")
+    if "sample_selection_count" in readiness or "sample_selection_limit" in readiness:
+        count = readiness.get("sample_selection_count", "unknown")
+        limit = readiness.get("sample_selection_limit", "unknown")
+        parts.append(f"sample_usage={count}/{limit}")
+    if readiness.get("sample_limit_reached") is True:
+        parts.append("sample_limit_reached=true")
+    return ", ".join(parts)
+
+
+def derive_selection_readiness(readiness: dict) -> SelectionReadiness:
+    if readiness.get("sample_limit_reached") is True:
+        return "not_ready"
+
+    has_test_library = readiness.get("has_test_library")
+    if has_test_library is False:
+        return "not_ready"
+    if has_test_library is not True:
+        return "unknown"
+
+    historical = readiness.get("has_historical_signal")
+    runtime = readiness.get("has_runtime_signal")
+    has_known_signal = historical is True or runtime is True
+    has_incomplete_signal = historical is False or runtime is False
+    state = _normalized_readiness_state(readiness)
+
+    if state in READY_SIGNAL_STATES:
+        if has_known_signal:
+            return "ready"
+        if historical is False and runtime is False:
+            return "partial"
+        return "unknown"
+
+    if state in {"historical_only", "runtime_only"}:
+        return "partial" if has_known_signal else "unknown"
+
+    if state in NOT_READY_SIGNAL_STATES:
+        return "partial" if has_incomplete_signal else "not_ready"
+
+    if has_known_signal or has_incomplete_signal:
+        return "partial"
+    return "unknown"
+
+
+def _normalized_readiness_state(readiness: dict) -> str:
+    for key in ("state", "signal_state"):
+        value = readiness.get(key)
+        if value is not None:
+            return str(value).strip().lower()
+    return ""
+
+
+def _selection_readiness_status(readiness: dict) -> str:
+    status = derive_selection_readiness(readiness)
+    labels = {
+        "ready": "[green]Ready[/green]",
+        "partial": "[yellow]Partially ready[/yellow]",
+        "not_ready": "[yellow]Not ready[/yellow]",
+        "unknown": "Unknown",
+    }
+    return labels[status]
+
+
+def _plain_bool(value: object) -> str:
+    if value is True:
+        return "yes"
+    if value is False:
+        return "no"
+    return "unknown"
+
+
+def _subscription_status(subscription: dict | None) -> str:
+    if not subscription:
+        return "unknown"
+    label = subscription.get("plan_label") or subscription.get("public_plan_code") or subscription.get("plan_code")
+    status = subscription.get("status")
+    if label and status:
+        return f"{label} ({status})"
+    if label:
+        return str(label)
+    return "unknown"
+
+
+def _subscription_details(subscription: dict | None) -> str:
+    if not subscription:
+        return "unknown"
+
+    parts = []
+    current = subscription.get("test_selections_current")
+    limit = subscription.get("test_selections_limit")
+    remaining = subscription.get("remaining_test_selections")
+    usage_percent = subscription.get("usage_percent")
+    if current is not None or limit is not None:
+        parts.append(f"test_selections={_display_value(current)}/{_display_value(limit)}")
+    if remaining is not None:
+        parts.append(f"remaining={remaining}")
+    if usage_percent is not None:
+        parts.append(f"usage={usage_percent}%")
+    if subscription.get("usage_warning"):
+        parts.append(f"warning={subscription.get('usage_warning')}")
+    return ", ".join(parts) if parts else "unknown"
+
+
+def _display_value(value: object) -> str:
+    return "unknown" if value is None else str(value)
+
+
+if __name__ == "__main__":
+    cli()