docs: name tools and error codes the way the client sees them

Indirect abilities are written lit/<name> (via mcp-adapter-execute-ability) in
guides, descriptions and hints, direct tools lit-<name>; guides use the
client-visible codes (write_failed, partial_write) and say exactly which tools
return a revision_id. ToolNamingTest keeps guides and sources consistent with
Ability::isDirect() and checks the overview's direct-tool list.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7

tests/Unit/Abilities/ErrorsTest.php

@@ -76,7 +76,8 @@ final class ErrorsTest extends TestCase
         self::assertStringContainsString('Eintrag 5', $payload['message']);
         self::assertStringContainsString('Revision 811', $payload['message']);
         self::assertStringContainsString('lit-content-get', $payload['hint']);
-        self::assertStringContainsString('lit-revisions-list', $payload['hint']);
+        self::assertStringContainsString('lit/revisions-list', $payload['hint']);
+        self::assertStringContainsString('mcp-adapter-execute-ability', $payload['hint']);
         self::assertStringContainsString('nicht einfach wiederholen', $payload['hint']);
         self::assertSame(5, $payload['post_id']);
         self::assertSame(811, $payload['revision_id']);

tests/Unit/Abilities/WriteFailedTest.php

@@ -36,14 +36,14 @@ final class WriteFailedTest extends TestCase
             'Menü nicht gespeichert.',
             false,
             state: 'Das Menü ist teilweise geändert.',
-            hint: 'Mit lit-menu-get prüfen.',
+            hint: 'Mit lit/menu-get prüfen.',
             details: ['menu_id' => 3]
         ))->toError();
 
         self::assertSame('lit_partial_write', $error->get_error_code());
         self::assertStringContainsString('Das Menü ist teilweise geändert.', $error->get_error_message());
         self::assertStringNotContainsString('Entwurf', $error->get_error_message());
-        self::assertSame('Mit lit-menu-get prüfen.', $error->get_error_data()['hint']);
+        self::assertSame('Mit lit/menu-get prüfen.', $error->get_error_data()['hint']);
         self::assertSame(3, $error->get_error_data()['menu_id']);
     }
 

tests/Unit/Guides/ToolNamingTest.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Guides;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Tests\Unit\TestCase;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+use ReflectionClass;
+
+/**
+ * Guides, descriptions and hints must name tools the way the client sees them: direct
+ * tools as lit-<name>, indirect ones as lit/<name> (reached via mcp-adapter-execute-ability),
+ * and error codes without the internal lit_ prefix of the WP_Error code.
+ */
+final class ToolNamingTest extends TestCase
+{
+    /** @return array<string, bool> Ability name without "lit/" => isDirect(). */
+    private static function abilities(): array
+    {
+        $root = dirname(__DIR__, 3);
+        $abilities = [];
+        $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root . '/src'));
+        foreach ($files as $file) {
+            if (! str_ends_with((string) $file, 'Ability.php')) {
+                continue;
+            }
+
+            $class = 'LIT\\MCP\\' . str_replace(['/', '.php'], ['\\', ''], substr((string) $file, strlen($root . '/src/')));
+            $reflection = new ReflectionClass($class);
+            if ($reflection->isInterface() || ! $reflection->implementsInterface(Ability::class)) {
+                continue;
+            }
+
+            /** @var Ability $ability */
+            $ability = $reflection->newInstanceWithoutConstructor();
+            $abilities[substr($ability->name(), strlen('lit/'))] = $ability->isDirect();
+        }
+
+        ksort($abilities);
+
+        return $abilities;
+    }
+
+    /** @return array<string, string> Path => content of the guides and all PHP sources. */
+    private static function texts(): array
+    {
+        $root = dirname(__DIR__, 3);
+        $texts = [];
+        foreach (glob($root . '/docs/guides/*.md') ?: [] as $file) {
+            $texts[$file] = (string) file_get_contents($file);
+        }
+
+        $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root . '/src'));
+        foreach ($files as $file) {
+            if (str_ends_with((string) $file, '.php')) {
+                $texts[(string) $file] = (string) file_get_contents((string) $file);
+            }
+        }
+
+        return $texts;
+    }
+
+    public function testIndirectToolsAreNeverNamedLikeDirectOnes(): void
+    {
+        $abilities = self::abilities();
+        self::assertArrayHasKey('menu-set-items', $abilities);
+
+        foreach (self::texts() as $path => $text) {
+            preg_match_all('/\blit-([a-z]+(?:-[a-z]+)*)/', $text, $matches);
+            foreach ($matches[1] as $name) {
+                self::assertFalse(
+                    ($abilities[$name] ?? true) === false,
+                    sprintf('%s names the indirect tool lit/%s as lit-%s', basename($path), $name, $name)
+                );
+            }
+
+            preg_match_all('#\blit/([a-z]+(?:-[a-z]+)*)#', $text, $matches);
+            foreach ($matches[1] as $name) {
+                self::assertFalse(
+                    ($abilities[$name] ?? false) === true && str_ends_with($path, '.md'),
+                    sprintf('%s names the direct tool lit-%s as lit/%s', basename($path), $name, $name)
+                );
+            }
+        }
+    }
+
+    public function testGuidesUseTheErrorCodesTheClientSees(): void
+    {
+        foreach (self::texts() as $path => $text) {
+            if (str_ends_with($path, '.md')) {
+                self::assertDoesNotMatchRegularExpression('/`lit_(?!mcp)[a-z_]+`/', $text, basename($path));
+            }
+        }
+    }
+
+    public function testOverviewListsExactlyTheDirectTools(): void
+    {
+        $overview = (string) file_get_contents(dirname(__DIR__, 3) . '/docs/guides/overview.md');
+        preg_match('/Direkt sichtbar:(.*?)\n\n/s', $overview, $section);
+        preg_match_all('/`lit-([a-z-]+)`/', $section[1] ?? '', $listed);
+
+        $direct = array_keys(array_filter(self::abilities()));
+        $listedNames = $listed[1];
+        sort($listedNames);
+
+        self::assertSame($direct, $listedNames);
+    }
+}

tests/Unit/Integrations/WordPress/Menus/MenuWriterTest.php

@@ -360,7 +360,8 @@ final class MenuWriterTest extends TestCase
             self::assertSame('lit_partial_write', $error->get_error_code());
             self::assertSame(3, $error->get_error_data()['menu_id']);
             self::assertSame('Home', $error->get_error_data()['previous_items'][0]['title']);
-            self::assertStringContainsString('lit-menu-get', $error->get_error_data()['hint']);
+            self::assertStringContainsString('lit/menu-get', $error->get_error_data()['hint']);
+            self::assertStringContainsString('mcp-adapter-execute-ability', $error->get_error_data()['hint']);
         }
     }
 }