[codex] Add MCP guidance prompt

app/Mcp/Prompts/EvolveClientSetup.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Mcp\Prompts;
+
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Title;
+use Laravel\Mcp\Server\Prompt;
+
+#[Title('Evolve Client Setup')]
+#[Description('Onboard an MCP client or agent to the Evolve workbench workflow.')]
+class EvolveClientSetup extends Prompt
+{
+    public function handle(Request $request): Response
+    {
+        return Response::text(<<<'MARKDOWN'
+            You are connected to the Evolve MCP server.
+
+            Evolve is a Laravel and Livewire workbench that edits real framework files through structured artifacts. Treat the manifest and library-backed MCP tools as the source of truth for workbench changes.
+
+            First steps:
+            - Use `list-artifacts` and `read-artifact` before changing workbench files.
+            - Use `upsert-artifact`, `delete-artifact`, `restore-artifact`, and `reorder-styles` for artifact changes so path guards, protected-file checks, starter-kit snapshots, and manifest metadata stay consistent.
+            - Use content tools for database-backed content models and rows.
+            - Use `send-feedback` and `triage-feedback` only for developer/agent process feedback, not website content.
+
+            Safety conventions:
+            - Mutating tools default to `dry_run: true`; inspect the structured response before setting `dry_run: false`.
+            - Destructive or restorative operations require `confirm_id` when `dry_run` is false.
+            - Do not weaken protected-file behavior or write outside the workspace.
+            - Prefer artifact boundaries: styles for shared CSS, layouts for page chrome, components for reusable Livewire units, snippets for static fragments, pages/forms for route orchestration.
+
+            Direct file edits are acceptable for application code outside the artifact model, tests, migrations, and documentation. For artifact files, use MCP tools or the Evolve library/API unless the task explicitly requires lower-level application changes.
+
+            Read the `evolve://guides/workflow` MCP resource for the fuller workflow reference.
+            MARKDOWN);
+    }
+}

app/Mcp/Resources/EvolveWorkflowGuide.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Mcp\Resources;
+
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\MimeType;
+use Laravel\Mcp\Server\Attributes\Title;
+use Laravel\Mcp\Server\Attributes\Uri;
+use Laravel\Mcp\Server\Resource;
+
+#[Title('Evolve Workflow Guide')]
+#[Description('Reference guidance for MCP clients and agents working with Evolve.')]
+#[Uri('evolve://guides/workflow')]
+#[MimeType('text/markdown')]
+class EvolveWorkflowGuide extends Resource
+{
+    public function handle(Request $request): Response
+    {
+        return Response::text(<<<'MARKDOWN'
+            # Evolve MCP Workflow Guide
+
+            ## Workbench Model
+
+            Evolve manages real Laravel and Livewire files through a structured artifact model. The manifest identifies workbench artifacts, and the Evolve library maps artifact operations to filesystem changes.
+
+            Use artifact boundaries deliberately:
+            - `style` artifacts contain shared CSS, design tokens, and visual foundations.
+            - `layout` artifacts contain repeated page chrome and structural wrappers.
+            - `component` artifacts contain reusable Livewire single-file components.
+            - `form` artifacts contain Livewire single-file form components.
+            - `snippet` artifacts contain Blade-only reusable fragments.
+            - `page` artifacts contain route-specific orchestration and content.
+            - `view` artifacts cover plain Blade files not owned by another typed artifact kind.
+
+            ## Tool Sequence
+
+            1. Inspect existing state with `list-artifacts`, `read-artifact`, `list-content-models`, or `list-content-rows`.
+            2. Plan the smallest artifact/content operation that preserves reuse and page structure.
+            3. Run mutating tools in dry-run mode first.
+            4. Inspect the structured response.
+            5. Re-run with `dry_run: false` only after the planned result is correct.
+            6. Run focused tests and build checks appropriate to the change.
+
+            ## Safety Rules
+
+            Mutating tools default to dry-run. Destructive and restorative operations require `confirm_id` when dry-run is disabled. Keep writes inside the workspace and do not weaken protected-file handling.
+
+            Protected starter-kit and workbench shell files exist because the workbench shares framework files with the application. When in doubt, use MCP tools or the Evolve library/API instead of direct artifact file edits.
+
+            ## Feedback Channel
+
+            `send-feedback` and `triage-feedback` are a separate developer/agent process channel. Use them to record process problems, tool guidance gaps, and improvement opportunities. Do not use feedback rows as website content or artifact metadata.
+
+            ## Direct Edits
+
+            Direct file edits are appropriate for application code outside the artifact model, tests, migrations, documentation, MCP server implementation, and service code. Direct artifact file edits should be a last resort because they can bypass manifest consistency, starter-kit snapshot/restore behavior, and path safety checks.
+            MARKDOWN);
+    }
+}

app/Mcp/Servers/EvolveServer.php

@@ -2,6 +2,8 @@
 
 namespace App\Mcp\Servers;
 
+use App\Mcp\Prompts\EvolveClientSetup;
+use App\Mcp\Resources\EvolveWorkflowGuide;
 use App\Mcp\Tools\CreateContentModel;
 use App\Mcp\Tools\DeleteArtifact;
 use App\Mcp\Tools\DeleteContentRow;
@@ -22,7 +24,7 @@
 
 #[Name('Evolve')]
 #[Version('0.1.0')]
-#[Instructions('Use these tools to inspect and safely update Evolve workbench artifacts and content. Mutating tools default to dry_run and destructive tools require confirm_id.')]
+#[Instructions('Use the evolve-client-setup prompt before editing. These tools inspect and safely update Evolve workbench artifacts, content, and developer feedback. Mutating tools default to dry_run and destructive tools require confirm_id.')]
 class EvolveServer extends Server
 {
     protected array $tools = [
@@ -42,10 +44,10 @@ class EvolveServer extends Server
     ];
 
     protected array $resources = [
-        //
+        EvolveWorkflowGuide::class,
     ];
 
     protected array $prompts = [
-        //
+        EvolveClientSetup::class,
     ];
 }

tests/Feature/EvolveMcpServerTest.php

@@ -2,6 +2,8 @@
 
 namespace Tests\Feature;
 
+use App\Mcp\Prompts\EvolveClientSetup;
+use App\Mcp\Resources\EvolveWorkflowGuide;
 use App\Mcp\Servers\EvolveServer;
 use App\Mcp\Tools\CreateContentModel;
 use App\Mcp\Tools\DeleteArtifact;
@@ -23,6 +25,7 @@
 use Illuminate\Support\Facades\File;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Str;
+use Laravel\Mcp\Server\Transport\FakeTransporter;
 use Tests\TestCase;
 
 class EvolveMcpServerTest extends TestCase
@@ -69,6 +72,37 @@ protected function tearDown(): void
         parent::tearDown();
     }
 
+    public function test_guidance_prompt_and_resource_are_discoverable(): void
+    {
+        $context = (new EvolveServer(new FakeTransporter))->createContext();
+
+        $this->assertSame('evolve-client-setup', $context->prompts()->first()?->name());
+        $this->assertSame('Evolve Client Setup', $context->prompts()->first()?->title());
+        $this->assertSame('evolve://guides/workflow', $context->resources()->first()?->uri());
+        $this->assertStringContainsString('evolve-client-setup', $context->instructions);
+    }
+
+    public function test_guidance_prompt_and_resource_explain_safe_tool_use(): void
+    {
+        EvolveServer::prompt(EvolveClientSetup::class)
+            ->assertOk()
+            ->assertSee([
+                'Use `list-artifacts` and `read-artifact` before changing workbench files.',
+                'Mutating tools default to `dry_run: true`',
+                'Use `send-feedback` and `triage-feedback` only for developer/agent process feedback',
+                'evolve://guides/workflow',
+            ]);
+
+        EvolveServer::resource(EvolveWorkflowGuide::class)
+            ->assertOk()
+            ->assertSee([
+                '# Evolve MCP Workflow Guide',
+                'Run mutating tools in dry-run mode first.',
+                'Destructive and restorative operations require `confirm_id`',
+                'Direct artifact file edits should be a last resort',
+            ]);
+    }
+
     public function test_artifact_tools_list_read_and_dry_run_without_writing(): void
     {
         File::ensureDirectoryExists(resource_path('evolve'));