Clarify optional Docker and Kubernetes tooling

ColimaStackTests/AppStateBackendAggregationTests.swift

@@ -298,6 +298,26 @@ struct AppStateBackendAggregationTests {
         #expect(snapshot.docker == nil)
     }
 
+    @Test func backendSnapshotReturnsIssuesWhenOptionalResourceProvidersFail() async {
+        let service = LiveBackendSnapshotService(
+            dockerService: FailingDockerResourceProvider(),
+            kubernetesService: FailingKubernetesResourceProvider()
+        )
+        var profile = Self.profile(named: "default", state: .running)
+        profile.kubernetes = KubernetesConfig(enabled: true, version: "v1.30.4+k3s1", context: "colima")
+        var status = Self.detail(profile: "default", state: .running)
+        status.kubernetes = profile.kubernetes
+
+        let snapshot = await service.snapshot(profile: profile, status: status)
+
+        #expect(snapshot.profile.name == "default")
+        #expect(snapshot.status.state == .running)
+        #expect(snapshot.docker == nil)
+        #expect(snapshot.kubernetes == nil)
+        #expect(snapshot.issues.contains { $0.source == .docker && $0.title == "Unable to load Docker resources" })
+        #expect(snapshot.issues.contains { $0.source == .kubernetes && $0.title == "Unable to load Kubernetes resources" })
+    }
+
     fileprivate static func profile(named name: String, state: ProfileState) -> ColimaProfile {
         ColimaProfile(
             name: name,
@@ -441,6 +461,42 @@ private struct EmptyKubernetesResourceProvider: KubernetesResourceProviding {
     }
 }
 
+private struct FailingDockerResourceProvider: DockerResourceProviding {
+    func loadSnapshot(context: String?) async -> ResourceLoadState<DockerResourceSnapshot> {
+        .failed(
+            BackendIssue(
+                severity: .error,
+                source: .docker,
+                title: "Unable to load Docker resources",
+                message: "docker: command not found"
+            ),
+            lastValue: nil
+        )
+    }
+
+    func snapshot(context: String?) async throws -> DockerResourceSnapshot {
+        throw AppStateAggregationTestError(message: "docker: command not found")
+    }
+}
+
+private struct FailingKubernetesResourceProvider: KubernetesResourceProviding {
+    func loadSnapshot(context: String?) async -> ResourceLoadState<KubernetesResourceSnapshot> {
+        .failed(
+            BackendIssue(
+                severity: .error,
+                source: .kubernetes,
+                title: "Unable to load Kubernetes resources",
+                message: "kubectl: command not found"
+            ),
+            lastValue: nil
+        )
+    }
+
+    func snapshot(context: String?) async throws -> KubernetesResourceSnapshot {
+        throw AppStateAggregationTestError(message: "kubectl: command not found")
+    }
+}
+
 @MainActor
 private final class RecordingFakeColima: ColimaControlling {
     var profiles: [ColimaProfile]

ColimaStackTests/ColimaStackTests.swift

@@ -295,6 +295,42 @@ struct ColimaCLITests {
         #expect(diagnostics.docker.error == "Colima default is stopped")
     }
 
+    @Test func diagnosticsTreatsDockerKubectlAndLimaAsOptionalWhenMissing() async throws {
+        let runner = FakeProcessRunner(results: [
+            "version": ProcessResult(
+                request: ProcessRequest(arguments: ["colima", "version"]),
+                exitCode: 0,
+                stdout: "colima version 0.10.1",
+                stderr: ""
+            ),
+            "colima status --json": ProcessResult(
+                request: ProcessRequest(arguments: ["colima", "status", "--json"], environment: ["COLIMA_PROFILE": "default"]),
+                exitCode: 0,
+                stdout: #"{"display_name":"colima","runtime":"containerd","kubernetes":false}"#,
+                stderr: ""
+            )
+        ])
+        let cli = LiveColimaCLI(
+            processRunner: runner,
+            toolLocator: FakeToolLocator(urls: [
+                "colima": URL(fileURLWithPath: "/opt/homebrew/bin/colima")
+            ])
+        )
+
+        let diagnostics = await cli.diagnostics()
+
+        #expect(diagnostics.tools.first(where: { $0.id == "colima" })?.availability == .available(path: "/opt/homebrew/bin/colima", version: "colima version 0.10.1"))
+        #expect(diagnostics.tools.first(where: { $0.id == "docker" })?.availability == .missing)
+        #expect(diagnostics.tools.first(where: { $0.id == "kubectl" })?.availability == .missing)
+        #expect(diagnostics.tools.first(where: { $0.id == "limactl" })?.availability == .missing)
+        #expect(diagnostics.colima.state == .running)
+        #expect(diagnostics.colima.runtime == .containerd)
+        #expect(!diagnostics.docker.available)
+        #expect(diagnostics.docker.error == "Not installed")
+        #expect(diagnostics.messages.isEmpty)
+        #expect(runner.requests.allSatisfy { $0.executableURL.lastPathComponent == "colima" })
+    }
+
     @Test func diagnosticsUsesExplicitColimaDockerContextWhenActiveContextDiffers() async throws {
         let runner = FakeProcessRunner(results: [
             "version": ProcessResult(

README.md

@@ -9,28 +9,38 @@
 ColimaStack gives [Colima](https://github.com/abiosoft/colima) a focused graphical workspace for local container development. It helps you inspect runtime health, manage profiles, browse Docker inventory, view Kubernetes resources, and diagnose toolchain issues without hiding the command-line tools doing the work.
 
 > [!NOTE]
-> ColimaStack is not a container engine. It controls and inspects local tools such as `colima`, `docker`, `kubectl`, and `limactl`.
+> ColimaStack is not a container engine. It controls and inspects local tools such as `colima`, plus optional integrations like `docker`, `kubectl`, and `limactl` when those tools are installed.
 
 ## Features
 
 - **Profile management**: create, edit, start, stop, restart, update, and delete Colima profiles.
 - **Runtime overview**: view profile state, Docker context, socket, address, resources, Kubernetes status, recent activity, and logs.
 - **Docker inventory**: browse containers, images, volumes, networks, runtime stats, and Docker disk usage.
 - **Kubernetes visibility**: inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled.
-- **Diagnostics**: check `colima`, `docker`, `kubectl`, `limactl`, Docker context, and Kubernetes context health.
+- **Diagnostics**: check `colima`, optional tool availability, Docker context, and Kubernetes context health.
 - **Command transparency**: review active operations, command history, stdout, stderr, and Colima daemon logs.
 - **Menu bar access**: check runtime state and jump back into the main workspace from the macOS menu bar.
 
 ## Requirements
 
 - macOS 14 or later
-- Homebrew-managed CLI dependencies for the default Docker workflow:
+- Homebrew-managed Colima CLI:
 
 ```sh
-brew install colima docker
+brew install colima
 ```
 
-Install `kubectl` only for Kubernetes workflows. Homebrew normally installs Lima with Colima; if diagnostics report that `limactl` is missing, install Lima explicitly.
+Optional tools unlock additional views and diagnostics:
+
+- Install the Docker CLI only if you want Docker runtime inventory such as containers, images, volumes, networks, stats, and disk usage.
+- Install `kubectl` only for Kubernetes workflows.
+- Homebrew normally installs Lima with Colima; if diagnostics report that `limactl` is missing, install Lima explicitly.
+
+```sh
+brew install docker
+brew install kubectl
+brew install lima
+```
 
 ## Documentation
 
@@ -47,7 +57,7 @@ If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md) for local deve
 
 ## How It Works
 
-ColimaStack is a local-first macOS app. It calls the Colima CLI for profile lifecycle operations, uses Docker CLI JSON output for runtime inventory, reads Kubernetes state through `kubectl`, and loads selected Colima files such as profile configuration, SSH config, and daemon logs.
+ColimaStack is a local-first macOS app. It calls the Colima CLI for profile lifecycle operations, uses Docker CLI JSON output for Docker runtime inventory when the Docker CLI is installed, reads Kubernetes state through `kubectl` when Kubernetes support is installed, and loads selected Colima files such as profile configuration, SSH config, and daemon logs.
 
 Most profile-scoped operations use the `COLIMA_PROFILE` environment variable so the active app selection maps directly to the intended Colima runtime.
 

docs/src/content/docs/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-description: How ColimaStack connects the macOS app, Colima CLI, Docker CLI, kubectl, and local Colima files.
+description: How ColimaStack connects the macOS app, Colima CLI, optional Docker CLI and kubectl integrations, and local Colima files.
 ---
 
 ColimaStack is a native macOS GUI backed by local command-line tools and file-backed Colima configuration.
@@ -26,7 +26,7 @@ Most profile-scoped operations use the `COLIMA_PROFILE` environment variable.
 
 ## Docker inventory
 
-Docker resources are read through the Docker CLI using JSON output where available:
+When the Docker CLI is installed and the selected profile uses the Docker runtime, Docker resources are read through JSON output where available:
 
 - `docker ps -a --format json`
 - `docker images --format json`
@@ -37,7 +37,7 @@ Docker resources are read through the Docker CLI using JSON output where availab
 
 ## Kubernetes inventory
 
-Kubernetes resources are read through `kubectl`:
+When `kubectl` is installed, Kubernetes resources are read through `kubectl`:
 
 - `kubectl get nodes -o json`
 - `kubectl get namespaces -o json`

docs/src/content/docs/compare/orbstack.md

@@ -5,15 +5,15 @@ description: Compare ColimaStack's Colima-focused workflow with OrbStack's bundl
 
 OrbStack is a bundled macOS product for Docker containers, Kubernetes, and Linux machines. Its docs emphasize out-of-the-box installation, automatic container domains, HTTPS, GUI management, command-line usage, Docker Desktop and Colima migration, Kubernetes integration, and Linux machine workflows.
 
-ColimaStack takes a different route: it builds a native GUI and diagnostics layer around Colima, Docker CLI, kubectl, and Lima.
+ColimaStack takes a different route: it builds a native GUI and diagnostics layer around Colima, with optional Docker CLI, kubectl, and Lima integrations.
 
 ## Choose ColimaStack when
 
 - you want an open-source Colima-based runtime stack
 - you already use Colima profiles
 - you want GUI visibility without replacing your Colima setup
 - you need command transparency and CLI compatibility
-- you want Docker and Kubernetes inventory for Colima contexts
+- you want optional Docker and Kubernetes inventory for Colima contexts
 
 ## Choose OrbStack when
 

docs/src/content/docs/faq.md

@@ -11,6 +11,10 @@ No. ColimaStack is a native macOS app for managing and observing Colima. Colima
 
 No. Install the Docker CLI separately. ColimaStack uses Docker commands to read containers, images, volumes, networks, stats, and disk usage from the selected Colima context.
 
+## Do I need Docker or kubectl installed?
+
+Not for core Colima profile management. Install the Docker CLI only for Docker runtime inventory, and install `kubectl` only for Kubernetes inventory and context checks.
+
 ## Can I use multiple Colima profiles?
 
 Yes. ColimaStack lists profiles and scopes operations through `COLIMA_PROFILE`. Docker context names are derived from the selected profile.

docs/src/content/docs/features.md

@@ -3,7 +3,7 @@ title: Features
 description: The main ColimaStack capabilities for local container and Kubernetes development.
 ---
 
-ColimaStack is organized around the workflows developers repeat every day: check runtime health, start or stop a profile, inspect Docker resources, verify Kubernetes state, and recover from toolchain failures.
+ColimaStack is organized around the workflows developers repeat every day: check runtime health, start or stop a profile, inspect Docker resources when the Docker CLI is available, verify Kubernetes state when `kubectl` is available, and recover from toolchain failures.
 
 ## Workspace overview
 
@@ -15,7 +15,7 @@ Create, edit, start, stop, restart, update, and delete Colima profiles. Profile
 
 ## Docker resources
 
-ColimaStack reads Docker resources through the Docker CLI for the active Colima context:
+When the Docker CLI is installed, ColimaStack reads Docker resources through the active Colima context:
 
 - containers
 - images
@@ -26,7 +26,7 @@ ColimaStack reads Docker resources through the Docker CLI for the active Colima
 
 ## Kubernetes resources
 
-When Kubernetes is enabled for a profile, ColimaStack reads cluster state through `kubectl`:
+When Kubernetes is enabled for a profile and `kubectl` is installed, ColimaStack reads cluster state through `kubectl`:
 
 - nodes
 - namespaces
@@ -37,4 +37,4 @@ When Kubernetes is enabled for a profile, ColimaStack reads cluster state throug
 
 ## Diagnostics and recovery
 
-The diagnostics workflow checks for required tools, Colima runtime status, Docker availability, and Kubernetes context. Errors are surfaced as actionable messages instead of raw command failures where possible.
+The diagnostics workflow checks required and optional tools, Colima runtime status, Docker availability, and Kubernetes context. Errors are surfaced as actionable messages instead of raw command failures where possible.

docs/src/content/docs/features/diagnostics.md

@@ -14,13 +14,13 @@ The app checks:
 - `kubectl`
 - `limactl`
 
-Each check reports whether the tool is available, missing, or returned an error.
+Each check reports whether the tool is available, missing, or returned an error. `colima` is required for core profile management. `docker`, `kubectl`, and `limactl` are optional checks that enable Docker inventory, Kubernetes inventory, and deeper runtime diagnostics.
 
 ## Runtime checks
 
 Colima status is read with `colima status --json` where possible. A stopped profile is treated as a normal state, not a fatal error.
 
-Docker availability is checked against the expected Colima context so an unrelated active Docker context does not hide a local setup problem.
+When the Docker CLI is installed, Docker availability is checked against the expected Colima context so an unrelated active Docker context does not hide a local setup problem.
 
 ## Kubernetes context
 

docs/src/content/docs/index.md

@@ -20,7 +20,7 @@ hero:
 
 <section class="landing-intro">
 
-ColimaStack is built for developers who already trust [Colima](https://github.com/abiosoft/colima) as their local container runtime and want a faster way to see, inspect, and recover their environment. It keeps the Colima CLI as the foundation, then adds a focused product layer for daily profile, Docker, and Kubernetes work.
+ColimaStack is built for developers who already trust [Colima](https://github.com/abiosoft/colima) as their local container runtime and want a faster way to see, inspect, and recover their environment. It keeps the Colima CLI as the foundation, then adds optional Docker and Kubernetes visibility when those tools are installed.
 
 </section>
 
@@ -38,15 +38,15 @@ ColimaStack is built for developers who already trust [Colima](https://github.co
   </article>
   <article>
     <h3>Docker inventory</h3>
-    <p>Browse containers, images, volumes, networks, stats, and disk usage for the active Colima context.</p>
+    <p>Browse containers, images, volumes, networks, stats, and disk usage for the active Colima context when the Docker CLI is installed.</p>
   </article>
   <article>
     <h3>Kubernetes awareness</h3>
-    <p>Inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled.</p>
+    <p>Inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled and <code>kubectl</code> is installed.</p>
   </article>
   <article>
     <h3>Actionable diagnostics</h3>
-    <p>Spot missing or misconfigured <code>colima</code>, <code>docker</code>, <code>kubectl</code>, and <code>limactl</code> tools before they derail the session.</p>
+    <p>Spot missing or misconfigured core and optional tools before they derail the workflow you are using.</p>
   </article>
 </div>
 

docs/src/content/docs/install.md

@@ -3,36 +3,45 @@ title: Install
 description: Set up ColimaStack and the command-line tools it controls.
 ---
 
-ColimaStack is a macOS app that controls local tools installed on your machine. It does not replace Colima, Docker, or kubectl. It makes those tools visible and easier to operate.
+ColimaStack is a macOS app that controls local tools installed on your machine. It does not replace Colima, Docker, or kubectl. Colima is the core dependency; Docker CLI and kubectl are optional integrations for the workflows that use them.
 
-## Requirements
+## Core requirements
 
 - macOS
 - Colima
-- Docker CLI
+
+## Optional integrations
+
+- Docker CLI for Docker runtime inventory
 - kubectl for Kubernetes workflows
 - Lima or `limactl` for deeper runtime diagnostics, normally installed by Homebrew with Colima
 
 ## Install dependencies
 
-Install the standard Docker workflow toolchain with Homebrew:
+Install the core Colima dependency with Homebrew:
 
 ```sh
-brew install colima docker
+brew install colima
 ```
 
-Install `kubectl` only if you plan to enable Kubernetes for a Colima profile:
+Install optional tools only for the workflows you plan to use:
 
 ```sh
+brew install docker
 brew install kubectl
 ```
 
-If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`.
+The Docker CLI enables ColimaStack's Docker resource views for containers, images, volumes, networks, stats, and disk usage. `kubectl` enables Kubernetes inventory views. If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`.
 
-Start a default Colima profile from Terminal if you want to verify the CLI path before opening the app:
+Start a default Colima profile from Terminal if you want to verify the core CLI path before opening the app:
 
 ```sh
 colima start
+```
+
+If you installed the Docker CLI, verify the Docker context separately:
+
+```sh
 docker context use colima
 docker ps
 ```

docs/src/content/docs/kubernetes/overview.md

@@ -10,7 +10,7 @@ colima kubernetes start
 colima kubernetes stop
 ```
 
-The Kubernetes views use `kubectl` for cluster inventory.
+The Kubernetes views use `kubectl` for cluster inventory. Install `kubectl` only if you want to use these views.
 
 ## Cluster view
 

docs/src/content/docs/quick-start.md

@@ -7,19 +7,19 @@ Use this guide to get from a clean macOS development machine to a visible Colima
 
 ## Prerequisites
 
-Install Colima and the Docker CLI for the default Docker runtime:
+Install Colima:
 
 ```sh
-brew install colima docker
+brew install colima
 ```
 
-Homebrew installs Lima as a Colima dependency. Install `kubectl` only if you plan to enable Kubernetes for a Colima profile:
+Install the Docker CLI only if you want Docker resource views such as containers, images, volumes, networks, stats, and disk usage:
 
 ```sh
-brew install kubectl
+brew install docker
 ```
 
-If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`.
+Homebrew installs Lima as a Colima dependency. Install `kubectl` only if you plan to enable Kubernetes for a Colima profile. If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`.
 
 ## Launch ColimaStack
 
@@ -33,7 +33,7 @@ Open the ColimaStack macOS app. On first launch, the app runs diagnostics for:
 - Docker context availability
 - Kubernetes context availability
 
-If a dependency is missing, open [Diagnostics](/features/diagnostics/) and follow the recovery suggestion.
+Only `colima` is required for core profile management. Missing optional tools limit the related views: Docker CLI for Docker inventory, `kubectl` for Kubernetes inventory, and `limactl` for deeper runtime diagnostics. If a dependency is missing, open [Diagnostics](/features/diagnostics/) and follow the recovery suggestion for the workflow you want to use.
 
 ## Create or select a profile