fix: named exception for WP-CLI being unavailable (CONV-10)

.harness.json

@@ -11,7 +11,6 @@
     "observed": [
         "Code style",
         "Rector",
-        "Dependency analysis",
-        "Security patterns"
+        "Dependency analysis"
     ]
 }

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Registering a command outside WP-CLI throws the named `WpCliUnavailable` exception instead of a bare `\RuntimeException`. It extends `\RuntimeException`, and the message keeps its `WP-CLI is not available` prefix, followed by how to avoid it
+
 ## [0.1.1] - 2026-10-13
 
 ### Fixed

src/Domain/Exceptions/WpCliUnavailable.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\WpCli\Domain\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown when a command is registered outside a WP-CLI process.
+ */
+final class WpCliUnavailable extends RuntimeException
+{
+    public static function whenRegisteringACommand(): self
+    {
+        return new self('WP-CLI is not available. Register commands from code that runs under `wp`, or check the adapter with isAvailable() first.');
+    }
+}

src/Infrastructure/Adapters/WpCliAdapter.php

@@ -4,6 +4,7 @@
 
 namespace Pollora\WpCli\Infrastructure\Adapters;
 
+use Pollora\WpCli\Domain\Exceptions\WpCliUnavailable;
 use WP_CLI;
 
 /**
@@ -36,7 +37,7 @@ public function isAvailable(): bool
     public function addCommand(string $name, string|array|object $handler, array $args = []): void
     {
         if (! $this->isAvailable()) {
-            throw new \RuntimeException('WP-CLI is not available');
+            throw WpCliUnavailable::whenRegisteringACommand();
         }
 
         $this->validateHandler($handler);

tests/Unit/Domain/Exceptions/WpCliUnavailableTest.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use Pollora\WpCli\Domain\Exceptions\WpCliUnavailable;
+
+it('says WP-CLI is missing and what to do about it', function (): void {
+    $exception = WpCliUnavailable::whenRegisteringACommand();
+
+    expect($exception)->toBeInstanceOf(RuntimeException::class)
+        ->and($exception->getMessage())->toStartWith('WP-CLI is not available')
+        ->and($exception->getMessage())->toContain('isAvailable()');
+});