clue2app-cli 0.2.7__py3-none-any.whl

clue2app_cli/sdk.py

@@ -0,0 +1,2993 @@
+"""
+SDK integration module for Clue2App CLI.
+
+This module provides integration with the clue2app-python-sdk and handles
+API communication with the Clue2App platform.
+"""
+
+import json
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+import platform
+
+import requests
+from rich.console import Console
+
+from .auth import get_access_token, parse_jwt_token
+from .config import get_config_value
+from .entrypoint_check import detect_entrypoint_issue
+
+from .version import __version__
+
+console = Console()
+
+
+def _resolve_ksvc_name(app_name: str) -> str:
+    """Convert a user-facing app name to the KSVC k8s name.
+
+    Coord's `/api/kn-service/{name}/...` and `/api/k8s-service/{name}/...`
+    endpoints identify the target Knative service by name — which is the
+    displayName the user typed (via Utils.identifyServiceName's fallback
+    chain: record.service.name → record.service.displayName → record.displayName).
+
+    The kpack Image resource for the same app has a k8s name shaped like
+    "{projectTsPrefix}-{name}-image" (e.g. "1770055311930-speakez-image").
+    That name is NEVER a valid ksvc name — passing it to a ksvc endpoint
+    returns 424 "not found" even while the app serves traffic.
+
+    Historic bug: several SDK methods used `get_app()` to resolve
+    displayName → k8s Image, then passed image.metadata.name to a
+    ksvc-side endpoint. This helper defends against that: strip the
+    "-image" suffix + drop the timestamp prefix if present, so both
+    accidental and intentional callers reach the right resource.
+    Reported by SpeakEZ agent 2026-08-02.
+    """
+    if not app_name:
+        return app_name
+    name = app_name.rstrip('/')
+    # Strip trailing "-image" (kpack Image naming convention)
+    if name.endswith("-image"):
+        name = name[:-len("-image")]
+    # Strip a leading "{projectTsPrefix}-" (14-15 digits, then a dash).
+    # Match the exact shape coord's personifyName() emits so we don't
+    # accidentally chew a legitimate name like "1234-my-app".
+    import re
+    m = re.match(r'^\d{13,16}-(.+)$', name)
+    if m:
+        return m.group(1)
+    return name
+
+
+class SDKClient:
+    """SDK client for Clue2App API."""
+
+    def __init__(self):
+        self.api_base_url = get_config_value("api.base_url", "https://coordinator.control.apps.clue2.app")
+        self.api_version = get_config_value("api.version", "v1")
+        self.api_timeout = get_config_value("api.timeout", 30)
+        self.headers = {
+            "User-Agent": f"Clue2App-CLI/{__version__} ({platform.system()} {platform.release()})",
+            "Accept": "application/json",
+            "Content-Type": "application/json"
+        }
+
+    def _make_api_request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
+        """Make a request to the API."""
+        # Don't add version prefix for /api/ endpoints
+        if endpoint.startswith("/api/"):
+            url = f"{self.api_base_url}{endpoint}"
+        else:
+            url = f"{self.api_base_url}/{self.api_version}/{endpoint.lstrip('/')}"
+
+        # Add default timeout
+        kwargs.setdefault('timeout', self.api_timeout)
+
+        # Add authentication header if available
+        token = get_access_token()
+        if token:
+            headers = kwargs.get('headers', {})
+            headers['Authorization'] = f"Bearer {token}"
+            kwargs['headers'] = headers
+
+        return requests.request(method, url, **kwargs)
+
+
+class Clue2AppSDK:
+    """
+    Main SDK client for interacting with the Clue2App platform.
+
+    This class provides a high-level interface to the Clue2App API,
+    wrapping the clue2app-python-sdk functionality.
+    """
+
+    def __init__(self):
+        self.api_client = SDKClient()
+        self.base_url = get_config_value("api.base_url", "https://coordinator.control.apps.clue2.app")
+        self.core_base_url = get_config_value("core.base_url", "https://core.control.apps.clue2.app")
+        self.api_version = get_config_value("api.version", "v1")
+
+    def audit_code(self, git_url: str, revision: str = "main",
+                   auth_username: str = "", auth_password: str = "",
+                   timeout: int = 60) -> Dict[str, Any]:
+        """Run the pre-build code-audit ruleset against a git ref.
+
+        Calls core's POST /api/v1/code/audit — no auth required (core's
+        public ksvc accepts the call; in-cluster URL also works).
+        Returns the full response: {gitUrl, revision, scannedAt,
+        findings: [...], criticalCount}.
+        """
+        url = f"{self.core_base_url}/api/v1/k8s/code/audit"
+        body = {"gitUrl": git_url, "revision": revision}
+        if auth_username:
+            body["authUsername"] = auth_username
+        if auth_password:
+            body["authPassword"] = auth_password
+        resp = requests.post(url, json=body, timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _make_authenticated_request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
+        """Make an authenticated request to the API."""
+        token = get_access_token()
+        if not token:
+            raise Exception("Not authenticated. Please login first.")
+
+        return self.api_client._make_api_request(method, endpoint, **kwargs)
+
+    # Application Management
+    def list_apps(self, project_id: str = None, use_context: bool = True, unlinked_only: bool = False, suppress_errors: bool = True) -> List[Dict[str, Any]]:
+        """List all applications (images) for the current user or project.
+
+        Args:
+            project_id: Filter by specific project ID
+            use_context: If True and project_id is None, use context project.
+                        If False, return all apps from all projects.
+            unlinked_only: If True, return only apps not linked to any project.
+            suppress_errors: If True, return empty list on error. If False, raise exception.
+        """
+        try:
+            # If unlinked_only, just return apps from base endpoint (those with nil appGroupId)
+            if unlinked_only:
+                response = self._make_authenticated_request("GET", "/api/k8s-image/")
+                response.raise_for_status()
+                data = response.json()
+                return data if isinstance(data, list) else []
+
+            # Get project ID from context if not provided and use_context is True
+            if project_id is None and use_context:
+                project_id = get_config_value("context.project.id")
+
+            if project_id:
+                # Filter by specific project
+                endpoint = f"/api/k8s-image/?appGroupId={project_id}"
+                response = self._make_authenticated_request("GET", endpoint)
+                response.raise_for_status()
+                data = response.json()
+                return data if isinstance(data, list) else data.get("images", [])
+            else:
+                # Get all apps from all projects
+                all_apps = []
+                seen_names = set()
+
+                # First get unlinked apps (appGroupId = 00000000...)
+                response = self._make_authenticated_request("GET", "/api/k8s-image/")
+                response.raise_for_status()
+                unlinked = response.json() if isinstance(response.json(), list) else []
+                for app in unlinked:
+                    name = app.get('metadata', {}).get('name')
+                    if name and name not in seen_names:
+                        all_apps.append(app)
+                        seen_names.add(name)
+
+                # Then get apps from each project
+                projects = self.list_projects()
+                for project in projects:
+                    pid = project.get('id')
+                    if pid:
+                        try:
+                            response = self._make_authenticated_request("GET", f"/api/k8s-image/?appGroupId={pid}")
+                            response.raise_for_status()
+                            project_apps = response.json() if isinstance(response.json(), list) else []
+                            for app in project_apps:
+                                name = app.get('metadata', {}).get('name')
+                                if name and name not in seen_names:
+                                    all_apps.append(app)
+                                    seen_names.add(name)
+                        except:
+                            pass  # Skip projects we can't access
+
+                return all_apps
+        except requests.exceptions.RequestException as e:
+            if suppress_errors:
+                console.print(f"[red]Error listing apps:[/red] {e}")
+                return []
+            raise Exception(f"Error listing apps: {e}")
+
+    def list_projects(self, suppress_errors: bool = True) -> List[Dict[str, Any]]:
+        """List all projects for the current user.
+
+        Args:
+            suppress_errors: If True, return empty list on error. If False, raise exception.
+        """
+        try:
+            response = self._make_authenticated_request("GET", "/api/k8s-project/")
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else data.get("projects", [])
+        except requests.exceptions.RequestException as e:
+            if suppress_errors:
+                console.print(f"[red]Error listing projects:[/red] {e}")
+                return []
+            raise Exception(f"Error listing projects: {e}")
+
+    def get_app(self, app_name: str) -> Optional[Dict[str, Any]]:
+        """Get details for a specific application by name or displayName."""
+        try:
+            # First try direct lookup by name
+            response = self._make_authenticated_request("GET", f"/api/k8s-image/{app_name}")
+            if response.status_code == 200:
+                return response.json()
+        except:
+            pass
+
+        # If direct lookup fails, search by displayName or partial match
+        try:
+            apps = self.list_apps(use_context=False)
+            for app in apps:
+                meta = app.get('metadata', {})
+                name = meta.get('name', '')
+                display_name = meta.get('displayName', '')
+                # Match by displayName or if name ends with the search term
+                # Also try with -image suffix since kpack images have that naming
+                if (display_name == app_name or
+                    display_name == f"{app_name}-image" or
+                    name == app_name or
+                    name.endswith(f"-{app_name}") or
+                    name.endswith(f"-{app_name}-image")):
+                    return app
+        except Exception as e:
+            console.print(f"[red]Error searching for app {app_name}:[/red] {e}")
+
+        return None
+
+    def delete_app(self, app_name: str) -> bool:
+        """Delete an application by name.
+
+        Note: Use the actual k8s name, not displayName. Use get_app() first to resolve.
+        """
+        try:
+            # Try to resolve the name first if it's a displayName
+            app = self.get_app(app_name)
+            if app:
+                actual_name = app.get('metadata', {}).get('name', app_name)
+            else:
+                actual_name = app_name
+
+            response = self._make_authenticated_request("DELETE", f"/api/k8s-image/{actual_name}")
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting app {app_name}:[/red] {e}")
+            return False
+
+    def rename_app(self, app_name: str, new_name: str) -> Optional[Dict[str, Any]]:
+        """Rename an application.
+
+        This creates a new application with the new name and deletes the old one,
+        since Kubernetes resource names are immutable.
+
+        Args:
+            app_name: Current application name (displayName used when creating the app)
+            new_name: New name for the application
+
+        Returns:
+            Dict with rename result on success, None on failure
+        """
+        try:
+            # Call the name-based rename endpoint
+            project_id = get_config_value("context.project.id")
+            endpoint = "/api/k8s/app/rename"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            payload = {"oldName": app_name, "newName": new_name}
+            response = self._make_authenticated_request("POST", endpoint, json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error renaming app {app_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def get_image_build_env(self, image_name: str) -> Dict[str, str]:
+        """Read the current spec.build.env off a kpack Image.
+
+        Returns a {name: value} dict. Empty if the Image has no build.env
+        block, or on any lookup failure (callers can then PATCH with just
+        the new vars).
+
+        image_name must be the k8s resource name (not the displayName).
+        Use get_app() to resolve first.
+        """
+        try:
+            response = self._make_authenticated_request("GET", f"/api/k8s-image/{image_name}")
+            if response.status_code != 200:
+                return {}
+            image = response.json()
+            env_list = image.get('spec', {}).get('build', {}).get('env', []) or []
+            return {e.get('name'): e.get('value', '') for e in env_list if e.get('name')}
+        except Exception:
+            return {}
+
+    def patch_image_build_env(self, image_name: str, build_env: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Set-and-replace the kpack Image's spec.build.env.
+
+        kpack watches spec.build.env and triggers a rebuild automatically
+        when it changes. Server-side endpoint added in coord PR #257
+        (SpeakEZ report finding #2).
+
+        Body is the FULL desired map — callers wanting to add one var
+        should GET the current, merge, then PATCH. See CLI's
+        `c2a env set --build` for the merge dance.
+        """
+        try:
+            response = self._make_authenticated_request(
+                "PATCH", f"/api/k8s-image/{image_name}/build-env",
+                json=build_env,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error patching build-env on {image_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def rebuild_app(self, app_name: str) -> Optional[Dict[str, Any]]:
+        """Trigger a rebuild for an application by name.
+
+        Args:
+            app_name: The application name (can be displayName or actual k8s name)
+
+        Returns:
+            Dict with status and buildNumber on success, None on failure
+        """
+        try:
+            # Try to resolve the name first if it's a displayName
+            app = self.get_app(app_name)
+            if app:
+                actual_name = app.get('metadata', {}).get('name', app_name)
+            else:
+                actual_name = app_name
+
+            response = self._make_authenticated_request("POST", f"/api/k8s-image/rebuild/{actual_name}")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            # Try to get more details from the response
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error rebuilding app {app_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def verify_rebuild_scheduled(self, app_name: str, rebuild_called_at,
+                                 timeout_seconds: int = 30) -> Dict[str, Any]:
+        """After rebuild_app, poll the Image's builds and check if a new
+        one was actually scheduled.
+
+        Background: kpack does NOT auto-reschedule when the latest Build
+        is in Succeeded=False. The rebuild API call returns 200 (sets
+        the kpack.io/rebuild annotation) but no new Build appears. The
+        Image is wedged; the operator's mental model says "I called
+        rebuild and it returned success" but reality is no kpack Build
+        was created. See heal_agent_wedged_kpack_plan for the full
+        incident retro.
+
+        Returns:
+            {
+                "took_effect": bool,
+                "latest_build_name": str | None,
+                "latest_build_age_seconds": float | None,
+                "build_count": int,
+            }
+        """
+        import time
+        from datetime import datetime, timezone
+
+        # Resolve to k8s name (rebuild_app accepts displayName too).
+        app = self.get_app(app_name)
+        actual_name = (app.get('metadata', {}).get('name', app_name)
+                       if app else app_name)
+        # Allow 5s clock skew between local + cluster.
+        threshold = rebuild_called_at - 5
+
+        deadline = time.time() + timeout_seconds
+        last_state = {"took_effect": False, "latest_build_name": None,
+                      "latest_build_age_seconds": None, "build_count": 0}
+        while time.time() < deadline:
+            try:
+                builds = self.get_builds(image_name=actual_name) or []
+            except Exception:
+                builds = []
+            newest = None
+            newest_ts = 0
+            for b in builds:
+                meta = b.get('metadata', {}) or {}
+                ts_str = meta.get('creationTimestamp', '')
+                if not ts_str:
+                    continue
+                try:
+                    # Parse RFC3339; tolerate the "Z" suffix.
+                    ts = datetime.strptime(ts_str.replace("Z", "+0000"),
+                                           "%Y-%m-%dT%H:%M:%S%z").timestamp()
+                except Exception:
+                    continue
+                if ts > newest_ts:
+                    newest_ts = ts
+                    newest = meta.get('name', '')
+            last_state["build_count"] = len(builds)
+            last_state["latest_build_name"] = newest
+            last_state["latest_build_age_seconds"] = (
+                time.time() - newest_ts if newest else None
+            )
+            if newest and newest_ts >= threshold:
+                last_state["took_effect"] = True
+                return last_state
+            time.sleep(3)
+        return last_state
+
+    # ---------------- Daari Secrets ----------------
+
+    def daari_secrets_list(self) -> List[Dict[str, Any]]:
+        """List Daari Secrets in the current project."""
+        try:
+            response = self._make_authenticated_request("GET", "/api/v1/daari/secrets/")
+            response.raise_for_status()
+            return response.json() or []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing Daari Secrets:[/red] {e}")
+            return []
+
+    def daari_secret_get(self, k8s_name: str) -> Optional[Dict[str, Any]]:
+        """Get one Daari Secret's metadata (keys + bindings; never values)."""
+        try:
+            response = self._make_authenticated_request("GET", f"/api/v1/daari/secrets/{k8s_name}")
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error fetching Daari Secret {k8s_name}:[/red] {e}")
+            return None
+
+    def daari_secret_create(self, display_name: str, data: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Create a new Daari Secret in the current project."""
+        try:
+            response = self._make_authenticated_request(
+                "POST",
+                "/api/v1/daari/secrets/",
+                json={"displayName": display_name, "data": data},
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            self._print_api_error(f"creating Daari Secret '{display_name}'", e)
+            return None
+
+    def daari_secret_rotate(self, k8s_name: str, data: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Rotate values for the keys passed; merge semantics."""
+        try:
+            response = self._make_authenticated_request(
+                "PUT",
+                f"/api/v1/daari/secrets/{k8s_name}/values",
+                json={"data": data},
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            self._print_api_error(f"rotating {k8s_name}", e)
+            return None
+
+    def daari_secret_delete(self, k8s_name: str, force: bool = False) -> bool:
+        """Delete a Daari Secret. Returns True on success."""
+        try:
+            response = self._make_authenticated_request(
+                "DELETE",
+                f"/api/v1/daari/secrets/{k8s_name}",
+                params={"force": "true" if force else "false"},
+            )
+            if response.status_code == 204:
+                return True
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            self._print_api_error(f"deleting {k8s_name}", e)
+            return False
+
+    def daari_secret_bindings(self, k8s_name: str) -> List[Dict[str, Any]]:
+        """List apps bound to a Daari Secret."""
+        try:
+            response = self._make_authenticated_request(
+                "GET", f"/api/v1/daari/secrets/{k8s_name}/bindings")
+            response.raise_for_status()
+            return response.json() or []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing bindings:[/red] {e}")
+            return []
+
+    def _print_api_error(self, action: str, e):
+        error_detail = ""
+        if hasattr(e, 'response') and e.response is not None:
+            try:
+                error_detail = e.response.json().get('message', '')
+            except Exception:
+                error_detail = e.response.text[:200] if e.response.text else ''
+        console.print(f"[red]Error {action}:[/red] {e}")
+        if error_detail:
+            console.print(f"[red]Details:[/red] {error_detail}")
+
+    def set_autoscaling(self, app_name: str, min_scale: Optional[int] = None,
+                        max_scale: Optional[int] = None, window: Optional[str] = None,
+                        scale_to_zero: bool = False) -> Optional[Dict[str, Any]]:
+        """Pin warm / allow scale-to-zero on an app via Knative
+        autoscaling annotations. Only the fields you pass are written;
+        other annotations on the ksvc are preserved by the server-side
+        merge-patch.
+
+        Args:
+            app_name: target ksvc / app name (displayName or k8s name)
+            min_scale: minimum replicas (0 allows scale-to-zero, 1+ pins warm)
+            max_scale: maximum replicas (>= 1)
+            window: Knative stable window (e.g. "30m", "60s")
+            scale_to_zero: equivalent to min_scale=0; convenience flag
+
+        Knative auto-rolls a fresh revision because spec.template
+        changed. Survives c2a app rebuild + c2a app env set.
+        """
+        try:
+            # NOTE: coord's /api/kn-service/{name}/... endpoints expect the
+            # ksvc name (== the app's displayName, per Utils.identifyServiceName).
+            # get_app() returns the kpack Image resource whose metadata.name
+            # is "{namePrefix}-image" (e.g. "1770055311930-speakez-image") —
+            # passing THAT to a ksvc endpoint 424s with "ksvc not found"
+            # even though the app is serving traffic. SpeakEZ report
+            # 2026-08-02. Pass app_name (what the user typed) directly.
+            ksvc_name = _resolve_ksvc_name(app_name)
+            body: Dict[str, Any] = {}
+            if min_scale is not None:
+                body["minScale"] = min_scale
+            if max_scale is not None:
+                body["maxScale"] = max_scale
+            if window:
+                body["window"] = window
+            if scale_to_zero:
+                body["scaleToZero"] = True
+            if not body:
+                console.print("[red]Nothing to set — pass at least one of --min/--max/--window/--scale-to-zero.[/red]")
+                return None
+            # Pass projectId so coord can resolve the ksvc's namespace
+            # (via getCurrentProject). Without this the endpoint's
+            # getCurrentNamespace() falls back to DEFAULT_NAMESPACE and
+            # the ksvc lookup returns "not found" for any app not in
+            # the platform's own namespace. Same shape as logs / bindings
+            # calls already use.
+            params: Dict[str, str] = {}
+            project_id = get_config_value("context.project.id")
+            if project_id:
+                params["projectId"] = project_id
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/kn-service/{ksvc_name}/autoscaling",
+                json=body,
+                params=params if params else None,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            self._print_api_error(f"setting autoscaling on {app_name}", e)
+            return None
+
+    def add_service_binding(self, app_name: str, binding_secret_name: str,
+                            restart: bool = True) -> Optional[Dict[str, Any]]:
+        """Append a binding to an app's <app>-service-binding Secret.
+
+        Resolves the binding Secret server-side: coordinator reads its
+        `serviceCatalog.targetDisplayName` label (or `targetName` fallback)
+        for the binding key, decodes its data values, and merges into the
+        existing C2A_SYSTEM_ENV.binding map. variables / secrets / other
+        bindings are preserved.
+
+        Args:
+            app_name: target ksvc / app name (NOT displayName)
+            binding_secret_name: the bound Secret name in the same namespace
+            restart: when True, also restart the ksvc so the new binding
+                     takes effect immediately
+
+        See `service_binding_architecture.md` in memory for the C2A_SYSTEM_ENV
+        contract this funnels through.
+        """
+        try:
+            # See set_autoscaling — pass app_name (== ksvc name) directly,
+            # not the get_app()-resolved kpack Image name.
+            ksvc_name = _resolve_ksvc_name(app_name)
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/kn-service/{ksvc_name}/bindings",
+                params={"restart": "true" if restart else "false"},
+                json={"name": binding_secret_name},
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except Exception:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error binding {binding_secret_name} to {app_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def list_service_bindings(self, app_name: str) -> Optional[List[Dict[str, Any]]]:
+        """List the Daari services currently bound to an app.
+
+        Returns a list of {kind, displayName, k8sName} dicts, in server order.
+        Empty list when the app has never been bound. None on transport error.
+
+        Backed by coordinator GET /api/kn-service/{name}/bindings.
+        """
+        try:
+            ksvc_name = _resolve_ksvc_name(app_name)
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/kn-service/{ksvc_name}/bindings",
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing bindings for {app_name}:[/red] {e}")
+            return None
+
+    def remove_service_binding(self, app_name: str, binding_key: str,
+                               restart: bool = True) -> Optional[Dict[str, Any]]:
+        """Remove a Daari binding from an app.
+
+        Mirror of add_service_binding — same primitive, opposite direction.
+
+        binding_key may be either the display-name key that appears in
+        C2A_SYSTEM_ENV.binding OR the source binding secret's k8s name.
+        The coordinator resolves either.
+
+        Idempotent: unbinding a key that isn't currently bound returns
+        200 with binding.notFound=true — safe to retry.
+        """
+        try:
+            ksvc_name = _resolve_ksvc_name(app_name)
+            from urllib.parse import quote
+            response = self._make_authenticated_request(
+                "DELETE",
+                f"/api/kn-service/{ksvc_name}/bindings/{quote(binding_key, safe='')}",
+                params={"restart": "true" if restart else "false"},
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except Exception:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error unbinding {binding_key} from {app_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def sync_image_to_service(self, app_name: str) -> Optional[Dict[str, Any]]:
+        """Sync kpack image to Knative service after a build completes.
+
+        This updates the Knative service to use the latest image from kpack.
+        Call this after a build completes to deploy the new image.
+
+        Args:
+            app_name: The application name (can be displayName or actual k8s name)
+
+        Returns:
+            Dict with sync status on success, None on failure
+        """
+        try:
+            # Try to resolve the name first if it's a displayName
+            app = self.get_app(app_name)
+            if app:
+                actual_name = app.get('metadata', {}).get('name', app_name)
+                namespace = app.get('metadata', {}).get('namespace')
+            else:
+                actual_name = app_name
+                namespace = None
+
+            if not namespace:
+                # Try to get namespace from context
+                context = self.get_project_context()
+                namespace = context.get('namespace') if context else None
+
+            if not namespace:
+                console.print("[red]Error:[/red] Could not determine namespace")
+                return None
+
+            payload = {"ns": namespace}
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/k8s-image/sync/{actual_name}",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error syncing image for {app_name}:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def get_service_account(self, name: str = "system-default") -> Optional[Dict[str, Any]]:
+        """Fetch a ServiceAccount in the active project's namespace.
+
+        Args:
+            name: SA name. Defaults to `system-default` (the SA wizard-v3 apps share).
+
+        Returns:
+            The SA resource dict, or None if not found.
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = f"/api/k8s-service-account/{name}"
+            if project_id:
+                endpoint = f"{endpoint}?projectId={project_id}"
+
+            response = self._make_authenticated_request("GET", endpoint)
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            if not response.text or response.text.strip() in ('', 'null'):
+                return None
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error fetching service account {name}:[/red] {e}")
+            return None
+
+    def get_service(self, service_name: str, namespace: str = None) -> Optional[Dict[str, Any]]:
+        """Get details of a Knative service.
+
+        Args:
+            service_name: The service name
+            namespace: Optional namespace (uses project context if not specified)
+
+        Returns:
+            Dict with service details on success, None on failure
+        """
+        try:
+            if not namespace:
+                context = self.get_project_context()
+                namespace = context.get('namespace') if context else None
+
+            if not namespace:
+                console.print("[red]Error:[/red] Could not determine namespace")
+                return None
+
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/kn-service/{service_name}",
+                params={"ns": namespace}
+            )
+            response.raise_for_status()
+
+            # Handle empty response body (coordinator returns 200 with null when service not found)
+            if not response.text or response.text.strip() in ('', 'null'):
+                return None
+
+            data = response.json()
+
+            # Extract service from response
+            service = data.get('Service', data)
+            if service:
+                # Add computed URL from status
+                url = None
+                if 'status' in service:
+                    url = service['status'].get('url')
+                    if not url and 'address' in service['status']:
+                        url = service['status']['address'].get('url')
+
+                return {
+                    'name': service.get('metadata', {}).get('name'),
+                    'namespace': service.get('metadata', {}).get('namespace'),
+                    'url': url,
+                    'ready': self._is_service_ready(service),
+                    'image': self._get_service_image(service),
+                    'created': service.get('metadata', {}).get('creationTimestamp'),
+                    'raw': service
+                }
+            return None
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting service {service_name}:[/red] {e}")
+            return None
+
+    def _is_service_ready(self, service: Dict) -> bool:
+        """Check if a Knative service is ready."""
+        conditions = service.get('status', {}).get('conditions', [])
+        for cond in conditions:
+            if cond.get('type') == 'Ready':
+                return cond.get('status') == 'True'
+        return False
+
+    def _get_service_image(self, service: Dict) -> Optional[str]:
+        """Extract the container image from a Knative service."""
+        try:
+            containers = service.get('spec', {}).get('template', {}).get('spec', {}).get('containers', [])
+            if containers:
+                return containers[0].get('image')
+        except:
+            pass
+        return None
+
+    def trigger_heal_agent(self, dry_run: bool = False, project_id: str = None) -> Dict[str, Any]:
+        """Trigger the platform's self-healing agent.
+
+        The healer agent detects and resolves infrastructure issues like:
+        - ECR credential expiration
+        - Failed builds that can be retried
+        - Service health issues
+
+        Args:
+            dry_run: If True, detect issues but don't take action
+            project_id: Optional project ID to limit scope. If None, checks all projects.
+
+        Returns:
+            Dict with:
+                - success: bool
+                - issues_detected: int
+                - issues_healed: int
+                - actions: list of actions taken
+                - error: optional error message
+        """
+        try:
+            payload = {
+                "dry_run": dry_run,
+            }
+            if project_id:
+                payload["project_id"] = project_id
+
+            response = self._make_authenticated_request(
+                "POST",
+                "/api/admin/heal",
+                json=payload
+            )
+
+            if response.status_code == 200:
+                return response.json()
+            body_lower = (response.text or "").lower()
+            # Spring returns 404 for a truly-missing route, but some
+            # configurations wrap it as 500 with body containing "no static
+            # resource ...". Treat both as "endpoint not implemented" so the
+            # CLI can print a friendly message + suggest --local mode
+            # (SpeakEZ report finding #5).
+            if response.status_code == 404 or "no static resource" in body_lower:
+                return {
+                    "success": False,
+                    "error": "Heal endpoint not available. The coordinator needs to implement /api/admin/heal"
+                }
+            return {
+                "success": False,
+                "error": f"HTTP {response.status_code}: {response.text[:200]}"
+            }
+
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = str(e)
+            return {
+                "success": False,
+                "error": error_detail or str(e)
+            }
+
+    def get_app_runtime_metrics(self, service_name: str = None, project_id: str = None) -> List[Dict[str, Any]]:
+        """Get runtime metrics for services.
+
+        Args:
+            service_name: Optional specific service name. If None, returns all services.
+            project_id: Optional project ID to filter by. If None, uses context project.
+
+        Returns:
+            List of runtime metrics with pods, cpu, memory, url, status etc.
+        """
+        try:
+            # Get project ID from context if not provided
+            if not project_id:
+                project_id = get_config_value("context.project.id")
+
+            params = {}
+            if project_id:
+                params['projectId'] = project_id
+
+            if service_name:
+                endpoint = f"/api/metrics/realtime/{service_name}"
+                if params:
+                    endpoint += "?" + "&".join(f"{k}={v}" for k, v in params.items())
+                response = self._make_authenticated_request("GET", endpoint)
+                if response.status_code == 200:
+                    data = response.json()
+                    return [data] if isinstance(data, dict) else data
+                return []
+            else:
+                endpoint = "/api/metrics/realtime"
+                if params:
+                    endpoint += "?" + "&".join(f"{k}={v}" for k, v in params.items())
+                response = self._make_authenticated_request("GET", endpoint)
+                response.raise_for_status()
+                return response.json() if isinstance(response.json(), list) else []
+        except:
+            return []
+
+    def get_knative_service(self, service_name: str) -> Optional[Dict[str, Any]]:
+        """Get Knative service details by name."""
+        try:
+            response = self._make_authenticated_request("GET", f"/api/kn-service/{service_name}")
+            if response.status_code == 200:
+                return response.json()
+            return None
+        except:
+            return None
+
+    def restart_service(self, service_name: str, namespace: Optional[str] = None) -> Dict[str, Any]:
+        """Restart/wake up a Knative service (useful for scaled-to-zero services).
+
+        Args:
+            service_name: The service name to restart
+            namespace: The namespace where the service is deployed
+
+        Returns:
+            Dict with 'success' bool and 'error' message if failed
+        """
+        try:
+            url = f"/api/kn-service/{service_name}/restart"
+            if namespace:
+                url += f"?namespace={namespace}"
+            response = self._make_authenticated_request("PUT", url)
+            response.raise_for_status()
+            return {"success": True, "data": response.json()}
+        except requests.exceptions.RequestException as e:
+            error_msg = str(e)
+            # Try to get more details from response
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_data = e.response.json()
+                    if 'error' in error_data:
+                        error_msg = error_data['error']
+                    elif 'message' in error_data:
+                        error_msg = error_data['message']
+                except:
+                    error_msg = e.response.text[:200] if e.response.text else str(e)
+            return {"success": False, "error": error_msg}
+
+    def create_project(self, name: str, description: str = "") -> Optional[Dict[str, Any]]:
+        """Create a new project with the current user as contributor."""
+        # Get current user info from token to add as contributor
+        token = get_access_token()
+        user_info = {}
+        if token:
+            try:
+                token_data = parse_jwt_token(token)
+                user_info = {
+                    "id": token_data.get("uid"),
+                    "username": token_data.get("sub"),
+                    "email": token_data.get("email"),
+                    "userType": token_data.get("userType", "SYSTEM"),
+                    "enabled": True,
+                    "givenName": token_data.get("givenName", ""),
+                    "familyName": token_data.get("familyName", ""),
+                    "source": token_data.get("source", "GOOGLE")
+                }
+            except Exception:
+                pass  # Fall back to empty userRights if token parsing fails
+
+        # Build userRights with current user
+        user_rights = []
+        if user_info.get("id"):
+            user_rights.append({
+                "user": user_info,
+                "isContributor": True
+            })
+
+        payload = {
+            "name": name,
+            "userRights": user_rights
+        }
+        if description:
+            payload["description"] = description
+
+        try:
+            response = self._make_authenticated_request("POST", "/api/k8s-project/", json=payload, timeout=120)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error creating project:[/red] {e}")
+            return None
+
+    def get_project(self, project_id: str, quiet: bool = False) -> Optional[Dict[str, Any]]:
+        """Get details for a specific project.
+
+        Args:
+            project_id: The project ID
+            quiet: If True, don't print errors to console
+        """
+        try:
+            response = self._make_authenticated_request("GET", f"/api/k8s-project/{project_id}")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            if not quiet:
+                console.print(f"[red]Error getting project {project_id}:[/red] {e}")
+            return None
+
+    def delete_project(self, project_id: str) -> bool:
+        """Delete a project."""
+        try:
+            response = self._make_authenticated_request("DELETE", f"/api/k8s-project/{project_id}", timeout=120)
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting project {project_id}:[/red] {e}")
+            return False
+
+    def create_app(self, name: str, git_url: str, project_id: str = None,
+                   git_username: str = "git", git_password: str = "",
+                   branch: str = "main", config: Dict[str, Any] = None,
+                   skip_entry_check: bool = False) -> Optional[Dict[str, Any]]:
+        """Create/deploy a new app within a project using the wizard API.
+
+        Args:
+            name: Display name for the application
+            git_url: Git repository URL (HTTPS format preferred)
+            project_id: Project/AppGroup ID (uses context if not provided)
+            git_username: Git username for authentication (default: "git")
+            git_password: Git password/token for authentication
+            branch: Git branch to build from (default: "main")
+            config: Additional configuration to merge into payload
+            skip_entry_check: If True, skip the pre-flight check that
+                refuses repos without a working web entry point (Procfile
+                / auto-detected file). Default False — most users want
+                the safety net.
+        """
+        # Get project ID from context if not provided
+        if not project_id:
+            project_id = get_config_value("context.project.id")
+
+        if not project_id:
+            console.print(f"[red]No project selected. Use 'config set context.project.id <id>' first.[/red]")
+            return None
+
+        # Convert SSH URL to HTTPS if needed
+        if git_url.startswith("git@github.com:"):
+            git_url = git_url.replace("git@github.com:", "https://github.com/")
+
+        # Pre-flight: catch repos that will silently fail at runtime
+        # because Paketo has nothing to launch (no Procfile, no
+        # auto-detected entry point). Cheap shallow-clone + inspection.
+        if not skip_entry_check:
+            issue = detect_entrypoint_issue(
+                git_url,
+                branch=branch,
+                git_username=git_username,
+                git_password=git_password,
+            )
+            if issue is not None:
+                console.print(f"[red]Cannot create app `{name}`:[/red] {issue.summary}\n")
+                console.print(issue.detail)
+                console.print(
+                    "\n[dim]Pass --skip-entry-check to bypass this check "
+                    "if you know the build will start some other way.[/dim]"
+                )
+                return None
+
+        payload = {
+            "displayName": name,
+            "git": {
+                "repo": git_url,
+                "revision": branch,
+                "accessType": "PUBLIC",
+                "secrets": {
+                    "username": git_username,
+                    "password": git_password
+                }
+            },
+            "deployAutomatically": True,
+            "service": {
+                "appGroupId": project_id,
+                "name": name,
+                "displayName": name,
+                "containerPort": "8080",
+                "applicationSize": "SMALL",
+                "scaleTo0": False
+            }
+        }
+
+        # Merge any additional config
+        if config:
+            # Deep merge for nested structures
+            for key, value in config.items():
+                if key in payload and isinstance(payload[key], dict) and isinstance(value, dict):
+                    payload[key].update(value)
+                else:
+                    payload[key] = value
+
+        try:
+            # Pass project_id as query parameter - coordinator reads it from request params
+            endpoint = f"/api/k8s/wizard-v3?appGroupId={project_id}"
+            response = self._make_authenticated_request("POST", endpoint, json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            # Try to get more details from the response
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error creating app:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def update_app(self, app_id: str, **kwargs) -> Optional[Dict[str, Any]]:
+        """Update an existing application."""
+        try:
+            response = self._make_authenticated_request("PUT", f"/apps/{app_id}", json=kwargs)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error updating app {app_id}:[/red] {e}")
+            return None
+
+    # Data Management
+    def list_datasets(self, app_id: str = None) -> List[Dict[str, Any]]:
+        """List datasets, optionally filtered by application."""
+        endpoint = "/datasets"
+        if app_id:
+            endpoint += f"?app_id={app_id}"
+
+        try:
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            return response.json().get("datasets", [])
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing datasets:[/red] {e}")
+            return []
+
+    def get_dataset(self, dataset_id: str) -> Optional[Dict[str, Any]]:
+        """Get details for a specific dataset."""
+        try:
+            response = self._make_authenticated_request("GET", f"/datasets/{dataset_id}")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting dataset {dataset_id}:[/red] {e}")
+            return None
+
+    def delete_dataset(self, dataset_id: str) -> bool:
+        """Delete a dataset."""
+        try:
+            response = self._make_authenticated_request("DELETE", f"/datasets/{dataset_id}")
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting dataset {dataset_id}:[/red] {e}")
+            return False
+
+    def upload_data(self, app_id: str, data: Any, format: str = "json") -> Optional[Dict[str, Any]]:
+        """Upload data to an application."""
+        if format == "json":
+            payload = {"data": data, "format": format}
+            try:
+                response = self._make_authenticated_request(
+                    "POST",
+                    f"/apps/{app_id}/data",
+                    json=payload
+                )
+                response.raise_for_status()
+                return response.json()
+            except requests.exceptions.RequestException as e:
+                console.print(f"[red]Error uploading data:[/red] {e}")
+                return None
+        else:
+            console.print(f"[red]Unsupported format:[/red] {format}")
+            return None
+
+    # Deployment Management
+    def list_deployments(self, app_id: str = None) -> List[Dict[str, Any]]:
+        """List deployments, optionally filtered by application."""
+        endpoint = "/deployments"
+        if app_id:
+            endpoint += f"?app_id={app_id}"
+
+        try:
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            return response.json().get("deployments", [])
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing deployments:[/red] {e}")
+            return []
+
+    def deploy_app(self, app_id: str, environment: str = "production") -> Optional[Dict[str, Any]]:
+        """Deploy an application to the specified environment."""
+        payload = {"environment": environment}
+
+        try:
+            response = self._make_authenticated_request(
+                "POST",
+                f"/apps/{app_id}/deploy",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deploying app {app_id}:[/red] {e}")
+            return None
+
+    def get_deployment_status(self, deployment_id: str) -> Optional[Dict[str, Any]]:
+        """Get the status of a deployment."""
+        try:
+            response = self._make_authenticated_request("GET", f"/deployments/{deployment_id}")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting deployment status:[/red] {e}")
+            return None
+
+    def get_deployment_logs(self, deployment_id: str, lines: int = 100) -> List[Dict[str, Any]]:
+        """Get logs for a deployment."""
+        params = {"lines": lines}
+
+        try:
+            response = self._make_authenticated_request(
+                "GET",
+                f"/deployments/{deployment_id}/logs",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json().get("logs", [])
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting deployment logs:[/red] {e}")
+            return []
+
+    # Logging and Monitoring
+    def get_app_logs(self, app_id: str, lines: int = 100, follow: bool = False) -> List[Dict[str, Any]]:
+        """Get logs for an application."""
+        params = {"lines": lines, "follow": follow}
+
+        try:
+            response = self._make_authenticated_request(
+                "GET",
+                f"/apps/{app_id}/logs",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json().get("logs", [])
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting logs:[/red] {e}")
+            return []
+
+    def get_app_metrics(self, app_id: str, timeframe: str = "1h") -> Optional[Dict[str, Any]]:
+        """Get metrics for an application."""
+        params = {"timeframe": timeframe}
+
+        try:
+            response = self._make_authenticated_request(
+                "GET",
+                f"/apps/{app_id}/metrics",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting metrics:[/red] {e}")
+            return None
+
+    # Image Management
+    def list_images(self, project_id: str = None) -> List[Dict[str, Any]]:
+        """List container images, optionally filtered by project."""
+        try:
+            # Get project ID from context if not provided
+            if not project_id:
+                project_id = get_config_value("context.project.id")
+
+            endpoint = "/api/k8s-image/"
+            if project_id:
+                endpoint = f"/api/k8s-image/?appGroupId={project_id}"
+
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            data = response.json()
+            if isinstance(data, list):
+                return data
+            return data.get("images", [])
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing images:[/red] {e}")
+            return []
+
+    def get_image(self, image_id: str) -> Optional[Dict[str, Any]]:
+        """Get details for a specific image."""
+        try:
+            response = self._make_authenticated_request("GET", f"/images/{image_id}")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting image {image_id}:[/red] {e}")
+            return None
+
+    def delete_image(self, image_id: str) -> bool:
+        """Delete an image."""
+        try:
+            response = self._make_authenticated_request("DELETE", f"/images/{image_id}")
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting image {image_id}:[/red] {e}")
+            return False
+
+    def rebuild_app(self, app_name: str) -> Dict[str, Any]:
+        """Trigger a rebuild for an application.
+
+        Args:
+            app_name: The application name, image name, or partial name.
+                     Will search for matching image if exact match not found.
+
+        Returns:
+            Dict with rebuild status information
+
+        Raises:
+            Exception: If rebuild fails
+        """
+        try:
+            # Try to find the image name
+            image_name = None
+
+            # First, try to get app directly
+            app = self.get_app(app_name)
+            if app:
+                image_name = app.get('metadata', {}).get('name', app_name)
+            else:
+                # Search through images to find a match
+                images = self.list_images()
+                for img in images:
+                    img_name = img.get('metadata', {}).get('name', '')
+                    # Match if app_name is contained in image name
+                    if app_name in img_name or img_name.endswith(f"-{app_name}-image"):
+                        image_name = img_name
+                        break
+
+            if not image_name:
+                # Last resort - use the name as-is, adding -image suffix if needed
+                image_name = app_name if app_name.endswith('-image') else f"{app_name}-image"
+
+            # Get project ID from context
+            project_id = get_config_value("context.project.id")
+            params = {}
+            if project_id:
+                params["projectId"] = project_id
+
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/k8s-image/rebuild/{image_name}",
+                params=params if params else None
+            )
+            response.raise_for_status()
+            return response.json() if response.text else {"status": "rebuild triggered", "image": image_name}
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"Error triggering rebuild for {app_name}: {e}")
+
+    def update_app_labels(self, app_name: str, labels: Dict[str, str]) -> Optional[Dict[str, Any]]:
+        """Update the labels on an application (image).
+
+        Calls the coordinator API to update image labels.
+        Uses PUT /api/k8s-image/{name} with the labels field.
+
+        Args:
+            app_name: The name of the app/image to update
+            labels: Dictionary of labels to set (e.g., {"appGroupId": "project-uuid"})
+
+        Returns:
+            The updated app details, or None on failure
+        """
+        try:
+            # First, get the app to find its current details
+            app = self.get_app(app_name)
+            if not app:
+                console.print(f"[red]App not found:[/red] {app_name}")
+                return None
+
+            actual_name = app.get('metadata', {}).get('name', app_name)
+            spec = app.get('spec', {})
+            git_source = spec.get('source', {}).get('git', {})
+
+            # Build the payload matching K8sImageRecord format
+            payload = {
+                "tag": spec.get('tag', ''),
+                "serviceAccountName": spec.get('serviceAccountName', ''),
+                "builder": spec.get('builder', {}).get('name', ''),
+                "git": {
+                    "repo": git_source.get('url', ''),
+                    "revision": git_source.get('revision', 'main')
+                },
+                "labels": labels
+            }
+
+            response = self._make_authenticated_request(
+                "PUT",
+                f"/api/k8s-image/{actual_name}",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error updating app labels:[/red] {e}")
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                    if error_detail:
+                        console.print(f"[red]Details:[/red] {error_detail}")
+                except:
+                    pass
+            return None
+
+    def link_app_to_project(self, app_name: str, project_id: str) -> Optional[Dict[str, Any]]:
+        """Link an app to a project by setting its appGroupId label.
+
+        Args:
+            app_name: The name of the app/image to link
+            project_id: The project ID (UUID) to link the app to
+
+        Returns:
+            The updated app details, or None on failure
+        """
+        return self.update_app_labels(app_name, {"appGroupId": project_id})
+
+    def get_instance_logs(self, app_name: str, lines: int = 100, follow: bool = False):
+        """Get instance logs for an application.
+
+        Args:
+            app_name: The application name (k8s resource name)
+            lines: Number of log lines to retrieve (default 100)
+            follow: If True, stream logs continuously (yields log lines)
+
+        Returns:
+            If follow=False: String containing log output
+            If follow=True: Generator yielding log lines
+        """
+        # /api/k8s-service/{name}/instance-logs expects the KSVC name
+        # (== the app's displayName, per coord's Utils.identifyServiceName).
+        # get_app() returns the kpack Image whose metadata.name is
+        # "{namePrefix}-image" — passing that here 424s with "not found"
+        # for the entire lifetime of the app, even while it serves
+        # traffic on its URL. SpeakEZ report 2026-08-02.
+        ksvc_name = _resolve_ksvc_name(app_name)
+
+        # Get project ID from context for namespace resolution
+        project_id = get_config_value("context.project.id")
+        params = {"tailLines": lines}
+        if project_id:
+            params["projectId"] = project_id
+
+        if follow:
+            # For streaming logs, use a generator
+            return self._stream_instance_logs(ksvc_name, lines, project_id)
+        else:
+            try:
+                response = self._make_authenticated_request(
+                    "GET",
+                    f"/api/k8s-service/{ksvc_name}/instance-logs",
+                    params=params
+                )
+                response.raise_for_status()
+                return response.text
+            except requests.exceptions.RequestException as e:
+                raise Exception(f"Error getting logs for {app_name}: {e}")
+
+    def _stream_instance_logs(self, app_name: str, lines: int = 100, project_id: str = None):
+        """Stream instance logs for an application.
+
+        Args:
+            app_name: The application name (k8s resource name)
+            lines: Initial number of log lines to retrieve
+            project_id: Project ID for namespace resolution
+
+        Yields:
+            Log lines as they become available
+        """
+        params = {"tailLines": lines, "follow": "true"}
+        if project_id:
+            params["projectId"] = project_id
+
+        try:
+            token = get_access_token()
+            if not token:
+                raise Exception("Not authenticated. Please login first.")
+
+            headers = {
+                "Authorization": f"Bearer {token}",
+                "Accept": "text/plain"
+            }
+
+            url = f"{self.base_url}/api/k8s-service/{app_name}/instance-logs"
+
+            # Use stream=True for following logs
+            response = requests.get(
+                url,
+                params=params,
+                headers=headers,
+                stream=True,
+                timeout=None  # No timeout for streaming
+            )
+            response.raise_for_status()
+
+            # Yield lines as they come in
+            for line in response.iter_lines(decode_unicode=True):
+                if line:
+                    yield line
+
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"Error streaming logs for {app_name}: {e}")
+
+    def get_builds(self, image_name: str = None, project_id: str = None) -> List[Dict[str, Any]]:
+        """Get kpack builds, optionally filtered by image name.
+
+        Args:
+            image_name: Optional image name to filter builds
+            project_id: Optional project ID to filter builds
+
+        Returns:
+            List of build objects
+        """
+        try:
+            params = {}
+            if image_name:
+                # Resolve to actual k8s name
+                app = self.get_app(image_name)
+                if app:
+                    image_name = app.get('metadata', {}).get('name', image_name)
+                params['imageName'] = image_name
+
+            # Add project ID if provided or from context
+            if project_id is None:
+                project_id = get_config_value("context.project.id")
+            if project_id:
+                params['appGroupId'] = project_id
+
+            response = self._make_authenticated_request(
+                "GET",
+                "/api/k8s/builds",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting builds:[/red] {e}")
+            return []
+
+    def get_latest_commit(self, image_name: str, project_id: str = None) -> Optional[str]:
+        """Get the latest build's commit SHA for an image.
+
+        Args:
+            image_name: The image name (k8s name)
+            project_id: Optional project ID
+
+        Returns:
+            Short commit SHA (7 chars) or None if not found
+        """
+        try:
+            builds = self.get_builds(image_name=image_name, project_id=project_id)
+            if not builds:
+                return None
+
+            # Sort by build number to get latest
+            sorted_builds = sorted(
+                builds,
+                key=lambda b: int(b.get('metadata', {}).get('labels', {}).get('image.kpack.io/buildNumber', 0)),
+                reverse=True
+            )
+            latest = sorted_builds[0] if sorted_builds else None
+            if latest:
+                revision = latest.get('spec', {}).get('source', {}).get('git', {}).get('revision', '')
+                if revision and len(revision) >= 7:
+                    return revision[:7]
+            return None
+        except Exception:
+            return None
+
+    def get_build_logs(self, build_name: str, namespace: str = None, lines: int = 100, follow: bool = False) -> str:
+        """Get build logs for a specific build.
+
+        Args:
+            build_name: The build name (e.g., "1234567890-myapp-image-build-1")
+            namespace: Optional namespace (uses project context if not provided)
+            lines: Number of log lines (not currently supported by backend)
+            follow: Follow log output (not currently supported by backend)
+
+        Returns:
+            String containing build log output
+        """
+        try:
+            # Build the pod name from build name
+            # Build names are like: 1234567890-myapp-image-build-1
+            # Pod names are: {build-name}-build-pod
+            pod_name = f"{build_name}-build-pod"
+
+            # Get project ID from context for namespace resolution
+            project_id = get_config_value("context.project.id")
+            params = {}
+            if project_id:
+                params["projectId"] = project_id
+
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/k8s/pod-logs/{pod_name}",
+                params=params if params else None
+            )
+            response.raise_for_status()
+            return response.text
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"Error getting build logs for {build_name}: {e}")
+
+    def get_latest_build_logs(self, app_name: str) -> str:
+        """Get build logs for the latest build of an app.
+
+        Args:
+            app_name: The application name
+
+        Returns:
+            String containing build log output, or empty string if no builds
+        """
+        try:
+            # Get app details to find the build info
+            app = self.get_app(app_name)
+            if not app:
+                return ""
+
+            actual_name = app.get('metadata', {}).get('name', app_name)
+            status = app.get('status', {})
+            build_counter = status.get('buildCounter', 0)
+
+            if build_counter == 0:
+                return "No builds available for this application."
+
+            # Construct the build name (not pod name - get_build_logs adds -build-pod)
+            # Format: {image-name}-build-{build-number}
+            build_name = f"{actual_name}-build-{build_counter}"
+
+            return self.get_build_logs(build_name)
+        except Exception as e:
+            return f"Error getting build logs: {e}"
+
+    # Secrets Management
+    def list_git_secrets(self) -> List[Dict[str, Any]]:
+        """List Git secrets in the current project context.
+
+        Returns:
+            List of Git secrets with metadata
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = "/api/k8s-secrets/git"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing Git secrets:[/red] {e}")
+            return []
+
+    def get_git_secret(self, secret_name: str) -> Optional[Dict[str, Any]]:
+        """Get a Git secret by name and return its credentials.
+
+        Args:
+            secret_name: The name of the secret (k8s name or display name)
+
+        Returns:
+            Dict with 'username' and 'password' keys, or None if not found
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = f"/api/k8s-secrets/{secret_name}/"
+            if project_id:
+                endpoint = f"{endpoint}?projectId={project_id}"
+
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            data = response.json()
+
+            # Extract credentials from secret data
+            # The secret data may be base64 encoded or plain text
+            secret_data = data.get('data', {})
+
+            # Try different field names for username
+            username = (secret_data.get('username') or
+                       secret_data.get('git-username') or
+                       secret_data.get('user') or
+                       'git')
+
+            # Try different field names for password/token
+            password = (secret_data.get('password') or
+                       secret_data.get('git-password') or
+                       secret_data.get('token') or
+                       secret_data.get('git-token') or
+                       '')
+
+            # Base64 decode if needed (check if it looks like base64)
+            import base64
+            try:
+                if username and len(username) % 4 == 0 and not ' ' in username:
+                    decoded = base64.b64decode(username).decode('utf-8')
+                    if decoded.isprintable():
+                        username = decoded
+            except Exception:
+                pass
+
+            try:
+                if password and len(password) % 4 == 0 and not ' ' in password:
+                    decoded = base64.b64decode(password).decode('utf-8')
+                    if decoded.isprintable():
+                        password = decoded
+            except Exception:
+                pass
+
+            return {'username': username, 'password': password}
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error getting secret {secret_name}:[/red] {e}")
+            return None
+
+    def create_git_secret(self, display_name: str, username: str, password: str) -> Optional[Dict[str, Any]]:
+        """Create a new Git secret for accessing private repositories.
+
+        Args:
+            display_name: Human-readable name for the secret
+            username: Git username (e.g., GitHub username)
+            password: Git password or Personal Access Token
+
+        Returns:
+            Created secret details with name, or None on failure
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = "/api/k8s-secrets/git"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            payload = {
+                "displayName": display_name,
+                "username": username,
+                "password": password
+            }
+
+            response = self._make_authenticated_request("POST", endpoint, json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error creating Git secret:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def update_git_secret(self, name: str, username: Optional[str], password: str) -> Optional[Dict[str, Any]]:
+        """Rotate the credentials in an existing Git secret.
+
+        Patches the in-cluster K8s Secret in place, so the SA's `secrets` list
+        and any apps already referencing the secret remain undisturbed — no
+        re-attachment, no rebuild ordering side-effects.
+
+        Args:
+            name: The K8s secret name (resolves display name → K8s name first).
+            username: New Git username; pass None to leave unchanged.
+            password: New password / PAT.
+
+        Returns:
+            Updated secret metadata on success, None on failure.
+        """
+        try:
+            actual_name = name
+            try:
+                existing = self.get_git_secret(name)
+                if existing is None:
+                    console.print(f"[red]Secret not found:[/red] {name}")
+                    return None
+                if username is None:
+                    username = existing.get("username") or "git"
+            except Exception:
+                pass  # fall through with the caller-provided name
+
+            project_id = get_config_value("context.project.id")
+            endpoint = f"/api/k8s-secrets/git/{actual_name}"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            payload = {
+                "username": username,
+                "password": password,
+            }
+
+            response = self._make_authenticated_request("PUT", endpoint, json=payload)
+            response.raise_for_status()
+            try:
+                return response.json()
+            except ValueError:
+                return {"name": actual_name}
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, "response") and e.response is not None:
+                try:
+                    error_detail = e.response.json().get("message", "")
+                except Exception:
+                    error_detail = e.response.text[:200] if e.response.text else ""
+            console.print(f"[red]Error updating Git secret:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def delete_secret(self, name: str) -> bool:
+        """Delete a secret by name.
+
+        Args:
+            name: The K8s secret name (not display name)
+
+        Returns:
+            True if deleted successfully, False otherwise
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = f"/api/k8s-secrets/{name}/"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            response = self._make_authenticated_request("DELETE", endpoint)
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting secret:[/red] {e}")
+            return False
+
+    def list_registry_secrets(self) -> List[Dict[str, Any]]:
+        """List container registry secrets in the current project context.
+
+        Returns:
+            List of registry secrets with metadata
+        """
+        try:
+            project_id = get_config_value("context.project.id")
+            endpoint = "/api/k8s-secrets/registry"
+            if project_id:
+                endpoint = f"{endpoint}?appGroupId={project_id}"
+
+            response = self._make_authenticated_request("GET", endpoint)
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing registry secrets:[/red] {e}")
+            return []
+
+    # ==================== Domain Management ====================
+
+    def list_platform_domains(self) -> List[Dict[str, Any]]:
+        """List platform domains available to all users.
+
+        Returns:
+            List of platform domains with their configuration
+        """
+        try:
+            response = self._make_authenticated_request("GET", "/api/domains/platform")
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing platform domains:[/red] {e}")
+            return []
+
+    def list_domains(self, project_id: str = None) -> List[Dict[str, Any]]:
+        """List domains for a project (includes platform domains).
+
+        Args:
+            project_id: Project ID to list domains for (uses context if not specified)
+
+        Returns:
+            List of domains (project + platform domains)
+        """
+        try:
+            if project_id is None:
+                project_id = get_config_value("context.project.id")
+            if not project_id:
+                console.print("[yellow]No project specified. Use context or --project.[/yellow]")
+                return self.list_platform_domains()
+
+            response = self._make_authenticated_request("GET", f"/api/domains/?projectId={project_id}")
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing domains:[/red] {e}")
+            return []
+
+    def register_domain(self, domain: str, project_id: str = None, dns_method: str = "CNAME_ONLY") -> Optional[Dict[str, Any]]:
+        """Register a custom domain for a project.
+
+        Args:
+            domain: Domain name to register (e.g., mycompany.com)
+            project_id: Project ID (uses context if not specified)
+            dns_method: DNS setup method (DELEGATION, SUBDOMAIN_DELEGATION, CNAME_ONLY)
+
+        Returns:
+            Dict with domain details and nameservers on success, None on failure
+        """
+        try:
+            if project_id is None:
+                project_id = get_config_value("context.project.id")
+            if not project_id:
+                console.print("[red]Error:[/red] No project specified. Use context or --project.")
+                return None
+
+            payload = {
+                "domain": domain,
+                "projectId": project_id,
+                "dnsMethod": dns_method
+            }
+            response = self._make_authenticated_request("POST", "/api/domains/", json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error registering domain:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def check_domain_status(self, domain: str) -> Optional[Dict[str, Any]]:
+        """Check DNS delegation status for a domain.
+
+        Args:
+            domain: Domain name to check
+
+        Returns:
+            Dict with DNS status information
+        """
+        try:
+            response = self._make_authenticated_request("GET", f"/api/domains/{domain}/status")
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error checking domain status:[/red] {e}")
+            return None
+
+    def delete_domain(self, domain_id: str) -> bool:
+        """Delete a custom domain.
+
+        Args:
+            domain_id: Domain UUID to delete
+
+        Returns:
+            True on success, False on failure
+        """
+        try:
+            response = self._make_authenticated_request("DELETE", f"/api/domains/{domain_id}")
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error deleting domain:[/red] {e}")
+            return False
+
+    def list_domain_assignments(self, project_id: str = None, app_name: str = None) -> List[Dict[str, Any]]:
+        """List domain assignments for a project, optionally filtered by app.
+
+        Args:
+            project_id: Project ID (uses context if not specified)
+            app_name: Filter by app name (optional)
+
+        Returns:
+            List of domain assignments
+        """
+        try:
+            if project_id is None:
+                project_id = get_config_value("context.project.id")
+            if not project_id:
+                console.print("[yellow]No project specified.[/yellow]")
+                return []
+
+            url = f"/api/domains/assignments?projectId={project_id}"
+            if app_name:
+                url += f"&appName={app_name}"
+            response = self._make_authenticated_request("GET", url)
+            response.raise_for_status()
+            data = response.json()
+            return data if isinstance(data, list) else []
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error listing domain assignments:[/red] {e}")
+            return []
+
+    def assign_domain(self, subdomain: str, domain: str, app_name: str, project_id: str = None) -> Optional[Dict[str, Any]]:
+        """Assign a subdomain to an app.
+
+        Args:
+            subdomain: Subdomain name (e.g., "api" for api.example.com)
+            domain: Base domain (e.g., "apps.clue2.app")
+            app_name: Application name to assign the domain to
+            project_id: Project ID (uses context if not specified)
+
+        Returns:
+            Dict with assignment details on success, None on failure
+        """
+        try:
+            if project_id is None:
+                project_id = get_config_value("context.project.id")
+            if not project_id:
+                console.print("[red]Error:[/red] No project specified. Use context or --project.")
+                return None
+
+            payload = {
+                "subdomain": subdomain,
+                "domain": domain,
+                "appName": app_name,
+                "projectId": project_id
+            }
+            response = self._make_authenticated_request("POST", "/api/domains/assignments", json=payload)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            error_detail = ""
+            if hasattr(e, 'response') and e.response is not None:
+                try:
+                    error_detail = e.response.json().get('message', '')
+                except:
+                    error_detail = e.response.text[:200] if e.response.text else ''
+            console.print(f"[red]Error assigning domain:[/red] {e}")
+            if error_detail:
+                console.print(f"[red]Details:[/red] {error_detail}")
+            return None
+
+    def unassign_domain(self, assignment_id: str) -> bool:
+        """Remove domain assignment from an app.
+
+        Args:
+            assignment_id: Assignment UUID to remove
+
+        Returns:
+            True on success, False on failure
+        """
+        try:
+            response = self._make_authenticated_request("DELETE", f"/api/domains/assignments/{assignment_id}")
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException as e:
+            console.print(f"[red]Error unassigning domain:[/red] {e}")
+            return False
+
+    # -----------------------------------------------------------------
+    # User / member management (bugfix — SCK-460 followup)
+    #
+    # These methods lived only on SDKClientWrapper before, but
+    # `get_sdk()` returns a Clue2AppSDK — so every `c2a user *` call
+    # (including my SCK-460 `invite_member`) crashed with
+    # "'Clue2AppSDK' object has no attribute '_get_current_account_id'".
+    # Adding them directly to Clue2AppSDK so the main CLI path works.
+    # -----------------------------------------------------------------
+
+    def _get_current_account_id(self) -> Optional[str]:
+        """Get current user's account ID from the JWT.
+
+        The slim JWT minted by auth carries `account.id` (nested), not
+        a top-level `accountId`. Older code that read `accountId`
+        silently returned None — hence "Could not determine account
+        ID" when running `c2a user invite -P …`. Read both shapes so
+        we survive any future claim rename.
+        """
+        try:
+            token = get_access_token()
+            if not token:
+                return None
+            from .auth import parse_jwt_token
+            token_data = parse_jwt_token(token) or {}
+            # Modern shape: account = {id, name, ...}
+            acct = token_data.get("account")
+            if isinstance(acct, dict) and acct.get("id"):
+                return acct["id"]
+            # Legacy / alternate shapes some code paths might have written.
+            return (
+                token_data.get("accountId")
+                or token_data.get("account_id")
+                or None
+            )
+        except Exception:
+            return None
+
+    def invite_member(self, account_id: str, email: str,
+                      role: str = "MEMBER",
+                      can_create_projects: bool = False,
+                      project_grants: Optional[List[Dict[str, str]]] = None,
+                      ) -> Dict[str, Any]:
+        """Invite a member to an account with optional project grants.
+
+        Uses POST /api/accounts/{accountId}/members. Idempotent for
+        existing same-account emails. Refuses cross-account moves.
+        """
+        payload = {
+            "email": email,
+            "role": role,
+            "canCreateProjects": can_create_projects,
+            "projectGrants": project_grants or [],
+        }
+        try:
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/accounts/{account_id}/members",
+                json=payload,
+            )
+            if not response.ok:
+                # Surface coord's error envelope — silently raise-for-status
+                # was swallowing the body, which made 500s undebuggable.
+                # Coord returns {"error_code": ..., "message": ...} on failure.
+                body_snippet = (response.text or "")[:600]
+                raise Exception(
+                    f"HTTP {response.status_code} POST /api/accounts/{account_id}/members\n"
+                    f"  body: {body_snippet}"
+                )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error inviting member: {e}")
+
+    def _resolve_project(self, name_or_id: str) -> Dict[str, Any]:
+        """Resolve a project name OR UUID string to the FULL project record.
+
+        Returns the K8sProjectRecord dict which already carries accountId
+        (per K8sProjectRecord.java) — so callers can invite into the
+        project's OWNING account without a second round-trip. SCK-475
+        surfaced that returning just the id led the invite path to
+        POST into the SYSTEM caller's own account, which coord rejected.
+        """
+        import uuid as _uuid
+        projects = self.list_projects(suppress_errors=False) or []
+        try:
+            _uuid.UUID(name_or_id)
+            # UUID input — find matching record so we can return accountId too.
+            for p in projects:
+                if str(p.get("id") or p.get("uuid")) == name_or_id:
+                    return p
+            # UUID not in list_projects (caller may not be a member of it).
+            # Fall back to a direct fetch.
+            resp = self._make_authenticated_request(
+                "GET", f"/api/k8s-project/{name_or_id}"
+            )
+            resp.raise_for_status()
+            return resp.json() or {}
+        except ValueError:
+            pass
+        # Name lookup path.
+        needle = name_or_id.strip().lower()
+        matches = [p for p in projects
+                   if str(p.get("name", "")).strip().lower() == needle]
+        if not matches:
+            available = ", ".join(
+                sorted({str(p.get("name")) for p in projects if p.get("name")})
+            ) or "(none — check `c2a project list`)"
+            raise Exception(
+                f"No project named '{name_or_id}'. Available: {available}"
+            )
+        if len(matches) > 1:
+            raise Exception(
+                f"Multiple projects named '{name_or_id}' — pass the UUID "
+                f"directly (e.g. `-P <project-uuid>`)."
+            )
+        return matches[0]
+
+    def _resolve_project_id(self, name_or_id: str) -> str:
+        """Back-compat shim — delegates to _resolve_project()."""
+        rec = self._resolve_project(name_or_id)
+        return rec.get("id") or rec.get("uuid")
+
+    def create_user(self, account_id: str, username: str, email: str,
+                    given_name: str = "", family_name: str = "",
+                    password: str = None, source: str = "LOCAL",
+                    groups: List[str] = None, enabled: bool = True
+                    ) -> Dict[str, Any]:
+        """Create a user via the legacy auth-service endpoint. Kept for
+        back-compat with `c2a user invite -u foo -e foo@x -p pass`.
+        The invite-with-projects flow uses invite_member() above.
+        """
+        try:
+            payload = {
+                "username": username,
+                "email": email,
+                "givenName": given_name,
+                "familyName": family_name,
+                "source": source,
+                "enabled": enabled,
+                "groups": groups or []
+            }
+            if password and source == "LOCAL":
+                payload["password"] = password
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/user/account/{account_id}",
+                json=payload
+            )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error creating user: {e}")
+
+
+class IntegrationTestRunner:
+    """
+    Integration test runner based on SDK functionality.
+
+    This class provides comprehensive testing capabilities for the Clue2App CLI
+    and SDK integration, simulating the integration tests you might find in
+    the clue2app-python-sdk repository.
+    """
+
+    def __init__(self, sdk: Clue2AppSDK):
+        self.sdk = sdk
+        self.test_results = []
+
+    def run_all_tests(self) -> bool:
+        """Run all integration tests."""
+        console.print("[bold blue]🧪 Running Integration Tests[/bold blue]")
+        console.print()
+
+        tests = [
+            ("Authentication Test", self.test_authentication),
+            ("App Management Test", self.test_app_management),
+            ("Data Upload Test", self.test_data_operations),
+            ("Deployment Test", self.test_deployment),
+            ("Logging Test", self.test_logging),
+        ]
+
+        all_passed = True
+
+        for test_name, test_func in tests:
+            console.print(f"🔬 Running {test_name}...")
+            try:
+                result = test_func()
+                if result:
+                    console.print(f"   ✅ [green]{test_name} PASSED[/green]")
+                else:
+                    console.print(f"   ❌ [red]{test_name} FAILED[/red]")
+                    all_passed = False
+                self.test_results.append((test_name, result))
+            except Exception as e:
+                console.print(f"   ❌ [red]{test_name} ERROR: {e}[/red]")
+                all_passed = False
+                self.test_results.append((test_name, False))
+
+        console.print()
+        if all_passed:
+            console.print("✅ [bold green]All tests passed![/bold green]")
+        else:
+            console.print("❌ [bold red]Some tests failed[/bold red]")
+
+        return all_passed
+
+    def test_authentication(self) -> bool:
+        """Test authentication functionality."""
+        from .auth import is_authenticated
+        return is_authenticated()
+
+    def test_app_management(self) -> bool:
+        """Test application management operations."""
+        try:
+            # Test listing apps
+            apps = self.sdk.list_apps()
+            return isinstance(apps, list)
+        except Exception:
+            return False
+
+    def test_data_operations(self) -> bool:
+        """Test data upload and management."""
+        # Test listing datasets
+        datasets = self.sdk.list_datasets()
+        return isinstance(datasets, list)
+
+    def test_deployment(self) -> bool:
+        """Test deployment operations."""
+        # Test listing deployments
+        deployments = self.sdk.list_deployments()
+        return isinstance(deployments, list)
+
+    def test_logging(self) -> bool:
+        """Test logging functionality."""
+        # This would test log retrieval in a real implementation
+        return True  # Placeholder
+
+
+# Global SDK instance
+_sdk_instance = None
+
+
+def get_sdk() -> Clue2AppSDK:
+    """Get a global SDK instance."""
+    global _sdk_instance
+    if _sdk_instance is None:
+        _sdk_instance = Clue2AppSDK()
+    return _sdk_instance
+
+
+class AppsNamespace:
+    """Namespace class providing apps-related methods for SDK client compatibility."""
+
+    def __init__(self, sdk: Clue2AppSDK):
+        self.sdk = sdk
+
+    def get_projects(self):
+        """Get all projects."""
+        return self.sdk.list_projects()
+
+    def deploy_app_v3(self, payload: Dict[str, Any], project_id: str = None,
+                      skip_entry_check: bool = False) -> Dict[str, Any]:
+        """Deploy app using wizard-v3 API."""
+        # Map to the SDK's create_app method which calls wizard-v3 API
+        name = payload.get('displayName', payload.get('service', {}).get('name', 'app'))
+        git_url = payload.get('git', {}).get('repo', '')
+        branch = payload.get('git', {}).get('revision', 'main')
+        git_secrets = payload.get('git', {}).get('secrets', {})
+        git_username = git_secrets.get('username', 'git')
+        git_password = git_secrets.get('password', '')
+
+        return self.sdk.create_app(
+            name=name,
+            git_url=git_url,
+            project_id=project_id,
+            git_username=git_username,
+            git_password=git_password,
+            branch=branch,
+            config=payload,
+            skip_entry_check=skip_entry_check,
+        )
+
+    def get_images(self, project_id: str = None):
+        """Get images for a project."""
+        return self.sdk.list_images(project_id=project_id)
+
+    def get_builds(self):
+        """Get all builds."""
+        return self.sdk.list_deployments()
+
+    def get_build_logs(self, build_name: str, namespace: str = None, lines: int = 100, follow: bool = False):
+        """Get build logs."""
+        return self.sdk.get_build_logs(build_name, namespace=namespace, lines=lines, follow=follow)
+
+    def get_logs(self, app_name: str, log_type: str = "instance", lines: int = 100):
+        """Get application logs."""
+        return self.sdk.get_instance_logs(app_name, lines=lines)
+
+
+class SDKClientWrapper:
+    """Wrapper class providing SDK client interface compatible with clue2app package."""
+
+    def __init__(self, sdk: Clue2AppSDK):
+        self._sdk = sdk
+        self.apps = AppsNamespace(sdk)
+
+    def set_token(self, token: str):
+        """Set authentication token (no-op, token is managed by auth module)."""
+        pass
+
+    # =========================================================================
+    # User Management
+    # =========================================================================
+
+    def list_users(self, account_id: str = None) -> List[Dict[str, Any]]:
+        """List users in an account.
+
+        Args:
+            account_id: Account ID (uses current account if not specified)
+
+        Returns:
+            List of user objects
+        """
+        try:
+            if not account_id:
+                # Get current user's account
+                account_id = self._get_current_account_id()
+                if not account_id:
+                    raise Exception("No account ID available")
+
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/user/account/{account_id}"
+            )
+            return response.json() if response.text else []
+        except Exception as e:
+            raise Exception(f"Error listing users: {e}")
+
+    def get_user(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """Get user by ID.
+
+        Args:
+            user_id: User UUID
+
+        Returns:
+            User object or None
+        """
+        try:
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/user/{user_id}"
+            )
+            return response.json() if response.text else None
+        except Exception as e:
+            raise Exception(f"Error getting user: {e}")
+
+    def create_user(self, account_id: str, username: str, email: str,
+                    given_name: str = "", family_name: str = "",
+                    password: str = None, source: str = "LOCAL",
+                    groups: List[str] = None, enabled: bool = True
+                    ) -> Dict[str, Any]:
+        """Create a new user in an account.
+
+        Args:
+            account_id: Account ID
+            username: Username
+            email: Email address
+            given_name: First name
+            family_name: Last name
+            password: Password (required for LOCAL source)
+            source: Auth source (LOCAL, GOOGLE, GITHUB)
+            groups: List of group IDs to add user to
+            enabled: Whether user is enabled
+
+        Returns:
+            Created user object
+        """
+        try:
+            payload = {
+                "username": username,
+                "email": email,
+                "givenName": given_name,
+                "familyName": family_name,
+                "source": source,
+                "enabled": enabled,
+                "groups": groups or []
+            }
+            if password and source == "LOCAL":
+                payload["password"] = password
+
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/user/account/{account_id}",
+                json=payload
+            )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error creating user: {e}")
+
+    def invite_member(self, account_id: str, email: str,
+                      role: str = "MEMBER",
+                      can_create_projects: bool = False,
+                      project_grants: Optional[List[Dict[str, str]]] = None,
+                      ) -> Dict[str, Any]:
+        """Invite a member to an account, optionally with per-project grants.
+
+        Uses POST /api/accounts/{accountId}/members (AccountMembersController.
+        invite). Unlike create_user() — which hits the auth service's legacy
+        /api/user/account/{id} and can't attach project grants — this endpoint
+        is the invite-by-email flow on coord and accepts project_grants in
+        the SAME atomic call, closing the two-step onboarding gap.
+
+        Coord's own contract (from AccountMemberRecord.java):
+          - If the email already exists in the same account, the response is
+            a no-op (current row returned) — idempotent.
+          - If the email exists in a DIFFERENT account, coord refuses with
+            "Cross-account moves aren't supported automatically yet."
+          - projectGrants is optional — omit to leave the invitee at
+            account-level with no project access.
+
+        Args:
+            account_id: Account UUID to invite into.
+            email: Invitee email.
+            role: "ACCOUNT_ADMIN" or "MEMBER" (default MEMBER).
+            can_create_projects: Whether the member can create new projects.
+            project_grants: List of {"projectId": "<uuid>", "role":
+                "PROJECT_ADMIN"|"CONTRIBUTOR"|"VIEWER"}.
+
+        Returns:
+            The member record coord returns (id, email, role, etc.).
+        """
+        payload = {
+            "email": email,
+            "role": role,
+            "canCreateProjects": can_create_projects,
+            "projectGrants": project_grants or [],
+        }
+        try:
+            response = self._make_authenticated_request(
+                "POST",
+                f"/api/accounts/{account_id}/members",
+                json=payload,
+            )
+            if not response.ok:
+                # Surface coord's error envelope — silently raise-for-status
+                # was swallowing the body, which made 500s undebuggable.
+                # Coord returns {"error_code": ..., "message": ...} on failure.
+                body_snippet = (response.text or "")[:600]
+                raise Exception(
+                    f"HTTP {response.status_code} POST /api/accounts/{account_id}/members\n"
+                    f"  body: {body_snippet}"
+                )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error inviting member: {e}")
+
+    def _resolve_project_id(self, name_or_id: str) -> str:
+        """Resolve a project name OR UUID string to a canonical UUID.
+
+        If the input parses as a UUID, it is returned unchanged (no lookup).
+        Otherwise, list_projects() is called and a case-insensitive name
+        match is attempted. Raises if the name doesn't match exactly one
+        project — ambiguous or missing.
+        """
+        import uuid as _uuid
+        try:
+            _uuid.UUID(name_or_id)
+            return name_or_id
+        except ValueError:
+            pass
+        projects = self.list_projects(suppress_errors=False) or []
+        needle = name_or_id.strip().lower()
+        matches = [p for p in projects
+                   if str(p.get("name", "")).strip().lower() == needle]
+        if not matches:
+            available = ", ".join(
+                sorted({str(p.get("name")) for p in projects if p.get("name")})
+            ) or "(none — check `c2a project list`)"
+            raise Exception(
+                f"No project named '{name_or_id}'. Available: {available}"
+            )
+        if len(matches) > 1:
+            raise Exception(
+                f"Multiple projects named '{name_or_id}' — pass the UUID "
+                f"directly (e.g. `-P <project-uuid>`)."
+            )
+        return matches[0].get("id") or matches[0].get("uuid")
+
+    def update_user(self, user_id: str, **kwargs) -> Dict[str, Any]:
+        """Update a user.
+
+        Args:
+            user_id: User UUID
+            **kwargs: Fields to update (givenName, familyName, enabled, groups)
+
+        Returns:
+            Updated user object
+        """
+        try:
+            # Map snake_case to camelCase
+            payload = {}
+            field_map = {
+                'given_name': 'givenName',
+                'family_name': 'familyName',
+                'enabled': 'enabled',
+                'groups': 'groups'
+            }
+            for key, value in kwargs.items():
+                if key in field_map:
+                    payload[field_map[key]] = value
+                else:
+                    payload[key] = value
+
+            response = self._make_authenticated_request(
+                "PUT",
+                f"/api/user/{user_id}",
+                json=payload
+            )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error updating user: {e}")
+
+    def delete_user(self, user_id: str) -> bool:
+        """Delete a user.
+
+        Args:
+            user_id: User UUID
+
+        Returns:
+            True if deleted successfully
+        """
+        try:
+            self._make_authenticated_request(
+                "DELETE",
+                f"/api/user/{user_id}"
+            )
+            return True
+        except Exception as e:
+            raise Exception(f"Error deleting user: {e}")
+
+    # =========================================================================
+    # Group Management
+    # =========================================================================
+
+    def list_groups(self, account_id: str = None) -> List[Dict[str, Any]]:
+        """List groups in an account.
+
+        Args:
+            account_id: Account ID (uses current account if not specified)
+
+        Returns:
+            List of group objects
+        """
+        try:
+            if not account_id:
+                account_id = self._get_current_account_id()
+                if not account_id:
+                    raise Exception("No account ID available")
+
+            response = self._make_authenticated_request(
+                "GET",
+                f"/api/group/account/{account_id}"
+            )
+            return response.json() if response.text else []
+        except Exception as e:
+            raise Exception(f"Error listing groups: {e}")
+
+    def create_group(self, name: str, role_id: str, account_id: str = None,
+                     enabled: bool = True) -> Dict[str, Any]:
+        """Create a new group.
+
+        Args:
+            name: Group name
+            role_id: Role ID to assign to group
+            account_id: Account ID (uses current account if not specified)
+            enabled: Whether group is enabled
+
+        Returns:
+            Created group object
+        """
+        try:
+            if not account_id:
+                account_id = self._get_current_account_id()
+                if not account_id:
+                    raise Exception("No account ID available")
+
+            payload = {
+                "name": name,
+                "accountId": account_id,
+                "userRole": {"id": role_id},
+                "enabled": enabled
+            }
+            response = self._make_authenticated_request(
+                "POST",
+                "/api/group/",
+                json=payload
+            )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error creating group: {e}")
+
+    def update_group(self, group_id: str, **kwargs) -> Dict[str, Any]:
+        """Update a group.
+
+        Args:
+            group_id: Group UUID
+            **kwargs: Fields to update (name, roleId, enabled)
+
+        Returns:
+            Updated group object
+        """
+        try:
+            payload = {}
+            if 'name' in kwargs:
+                payload['name'] = kwargs['name']
+            if 'role_id' in kwargs:
+                payload['userRole'] = {'id': kwargs['role_id']}
+            if 'enabled' in kwargs:
+                payload['enabled'] = kwargs['enabled']
+
+            response = self._make_authenticated_request(
+                "PUT",
+                f"/api/group/{group_id}",
+                json=payload
+            )
+            return response.json() if response.text else {}
+        except Exception as e:
+            raise Exception(f"Error updating group: {e}")
+
+    def delete_group(self, group_id: str) -> bool:
+        """Delete a group.
+
+        Args:
+            group_id: Group UUID
+
+        Returns:
+            True if deleted successfully
+        """
+        try:
+            self._make_authenticated_request(
+                "DELETE",
+                f"/api/group/{group_id}"
+            )
+            return True
+        except Exception as e:
+            raise Exception(f"Error deleting group: {e}")
+
+    # =========================================================================
+    # Role Management
+    # =========================================================================
+
+    def list_roles(self) -> List[Dict[str, Any]]:
+        """List all available roles.
+
+        Returns:
+            List of role objects
+        """
+        try:
+            response = self._make_authenticated_request(
+                "GET",
+                "/api/role/"
+            )
+            return response.json() if response.text else []
+        except Exception as e:
+            raise Exception(f"Error listing roles: {e}")
+
+    def _get_current_account_id(self) -> Optional[str]:
+        """Get current user's account ID from token or context."""
+        try:
+            token = get_access_token()
+            if token:
+                from .auth import parse_jwt_token
+                token_data = parse_jwt_token(token)
+                return token_data.get("accountId")
+        except:
+            pass
+        return None
+
+
+def _get_sdk_client() -> SDKClientWrapper:
+    """Get an SDK client wrapper compatible with clue2app package interface.
+
+    Returns a wrapper that provides .apps namespace with methods like:
+    - get_projects()
+    - deploy_app_v3()
+    - get_images()
+    - get_builds()
+    - get_build_logs()
+    - get_logs()
+    """
+    sdk = get_sdk()
+    return SDKClientWrapper(sdk)
+
+
+# =============================================================================
+# Repository Analysis (Pre-flight checks)
+# =============================================================================
+
+def analyze_repo(path: str) -> Dict[str, Any]:
+    """Analyze a repository structure before deployment.
+
+    Scans for common patterns and issues that might cause deployment problems.
+
+    Args:
+        path: Path to the repository root
+
+    Returns:
+        Dict with 'issues', 'warnings', 'suggestions', and 'detected' keys
+    """
+    import os
+
+    issues = []      # Critical - will likely fail
+    warnings = []    # May cause problems
+    suggestions = [] # Helpful tips
+    detected = {}    # What we detected about the app
+
+    def exists(filename):
+        return os.path.exists(os.path.join(path, filename))
+
+    def read_file(filename):
+        try:
+            with open(os.path.join(path, filename), 'r') as f:
+                return f.read()
+        except:
+            return None
+
+    def load_json(filename):
+        try:
+            with open(os.path.join(path, filename), 'r') as f:
+                return json.load(f)
+        except:
+            return None
+
+    # === Detect app type ===
+    app_type = None
+    framework = None
+
+    # --- Node.js / JavaScript ---
+    if exists('package.json'):
+        app_type = 'nodejs'
+        pkg = load_json('package.json')
+
+        if pkg:
+            scripts = pkg.get('scripts', {})
+            deps = {**pkg.get('dependencies', {}), **pkg.get('devDependencies', {})}
+            detected['package_name'] = pkg.get('name', 'unknown')
+            detected['node_scripts'] = list(scripts.keys())
+
+            # Check for start command
+            has_start = 'start' in scripts
+            has_procfile = exists('Procfile')
+            has_server_file = any(exists(f) for f in ['server.js', 'serve.js', 'app.js', 'index.js'])
+
+            if has_start:
+                detected['start_command'] = scripts['start']
+            elif has_procfile:
+                detected['start_source'] = 'Procfile'
+            elif has_server_file:
+                warnings.append("No 'start' script but server file found - buildpack may detect it")
+            else:
+                issues.append("No 'start' script and no Procfile - app won't know how to run")
+
+            # Detect framework
+            if 'vite' in deps:
+                framework = 'vite'
+                detected['framework'] = 'Vite'
+                if 'react' in deps:
+                    detected['framework'] = 'Vite + React'
+
+                # Vite apps need a static file server for production
+                # NOTE: node_modules is pruned at runtime by the buildpack,
+                # so packages like 'serve' won't be available. Use a server.js
+                # with only Node.js built-ins (http, fs, path).
+                has_server = any(exists(f) for f in ['serve.js', 'server.js'])
+
+                if 'start' not in scripts and not has_server:
+                    issues.append("Vite/React app needs a server.js to serve the built files")
+                    suggestions.append('Create a server.js using Node.js built-in http/fs modules to serve dist/')
+                    suggestions.append('Do NOT use the "serve" npm package — node_modules is pruned at runtime by the buildpack')
+                    warnings.append("Don't use 'vite preview' in production - it's for local testing only")
+                elif 'vite preview' in scripts.get('start', ''):
+                    warnings.append("'vite preview' is NOT for production - use a proper static file server")
+                    suggestions.append('Create a server.js using Node.js built-in http/fs modules to serve dist/')
+
+                # Check for dist folder (built output)
+                if exists('dist'):
+                    detected['has_dist'] = True
+                    detected['build_output'] = 'dist/'
+
+            if 'next' in deps:
+                framework = 'nextjs'
+                detected['framework'] = 'Next.js'
+                # Next.js usually works out of box
+
+            if 'express' in deps:
+                detected['has_express'] = True
+                if not any(exists(f) for f in ['server.js', 'app.js', 'index.js']):
+                    warnings.append("Has express but no server.js/app.js/index.js found")
+
+            if 'fastify' in deps:
+                detected['has_fastify'] = True
+
+    # --- Python ---
+    if exists('requirements.txt') or exists('pyproject.toml') or exists('setup.py'):
+        app_type = 'python'
+        detected['python_app'] = True
+
+        reqs_content = read_file('requirements.txt') or ''
+
+        if 'fastapi' in reqs_content.lower():
+            framework = 'fastapi'
+            detected['framework'] = 'FastAPI'
+            if not exists('Procfile'):
+                suggestions.append('Add Procfile: web: uvicorn main:app --host 0.0.0.0 --port 8080')
+
+        if 'flask' in reqs_content.lower():
+            framework = 'flask'
+            detected['framework'] = 'Flask'
+            if not exists('Procfile'):
+                suggestions.append('Add Procfile: web: gunicorn app:app --bind 0.0.0.0:8080')
+
+        if 'django' in reqs_content.lower():
+            framework = 'django'
+            detected['framework'] = 'Django'
+
+        if not any(exists(f) for f in ['main.py', 'app.py', 'wsgi.py', 'asgi.py']):
+            warnings.append("Python app - no main.py, app.py, or wsgi.py found")
+
+    # --- Go ---
+    if exists('go.mod'):
+        app_type = 'go'
+        detected['go_app'] = True
+
+        if not exists('main.go') and not exists('cmd/'):
+            warnings.append("Go app - no main.go or cmd/ directory found")
+
+    # --- Java ---
+    if exists('pom.xml') or exists('build.gradle'):
+        app_type = 'java'
+        detected['java_app'] = True
+
+    # === General Checks ===
+
+    # Procfile
+    if not exists('Procfile'):
+        if app_type in ['python', 'nodejs']:
+            warnings.append("No Procfile - buildpack will guess start command")
+    else:
+        detected['has_procfile'] = True
+        procfile_content = read_file('Procfile')
+        if procfile_content:
+            detected['procfile_content'] = procfile_content.strip()
+
+    # Dockerfile
+    if exists('Dockerfile'):
+        detected['has_dockerfile'] = True
+        suggestions.append("Dockerfile found - consider using Docker buildpack for more control")
+
+    # Server entry points
+    server_files = ['server.js', 'serve.js', 'app.js', 'index.js', 'main.py', 'app.py', 'main.go']
+    found_servers = [f for f in server_files if exists(f)]
+    if found_servers:
+        detected['server_files'] = found_servers
+    elif app_type and app_type not in ['java']:
+        if framework not in ['nextjs']:  # Next.js doesn't need explicit server
+            warnings.append(f"No server entry point found ({', '.join(server_files[:3])}...)")
+
+    # Port configuration
+    if exists('.env'):
+        env_content = read_file('.env') or ''
+        if 'PORT' in env_content:
+            detected['has_port_config'] = True
+
+    detected['app_type'] = app_type
+    detected['framework'] = framework
+
+    return {
+        'issues': issues,
+        'warnings': warnings,
+        'suggestions': suggestions,
+        'detected': detected,
+        'ready': len(issues) == 0
+    }