fix: improve workspace context error messages (closes #28)

Updated workspace_id error messages in all MCP tools to include
actionable guidance and a documentation link. Affected tools:
PlanCreate, PlanGet, PlanList, StateSet, StateGet, StateList,
SessionStart.

Resolves DX-001 from TODO.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Mcp/Tools/Agent/Plan/PlanCreate.php

@@ -99,7 +99,7 @@ class PlanCreate extends AgentTool
         // Determine workspace_id - never fall back to hardcoded value in multi-tenant environment
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required but could not be determined from context');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         $plan = AgentPlan::create([

Mcp/Tools/Agent/Plan/PlanGet.php

@@ -71,7 +71,7 @@ class PlanGet extends AgentTool
         // Validate workspace context for tenant isolation
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required for plan operations');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         $format = $this->optional($args, 'format', 'json');

Mcp/Tools/Agent/Plan/PlanList.php

@@ -71,7 +71,7 @@ class PlanList extends AgentTool
         // Validate workspace context for tenant isolation
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required for plan operations');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         // Query plans with workspace scope to prevent cross-tenant access

Mcp/Tools/Agent/Session/SessionStart.php

@@ -88,7 +88,7 @@ class SessionStart extends AgentTool
             // Determine workspace_id - never fall back to hardcoded value in multi-tenant environment
             $workspaceId = $context['workspace_id'] ?? $plan?->workspace_id ?? null;
             if ($workspaceId === null) {
-                return $this->error('workspace_id is required but could not be determined from context or plan');
+                return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session, or provide a valid plan_slug to infer workspace context. See: https://host.uk.com/ai');
             }
 
             $session = AgentSession::create([

Mcp/Tools/Agent/State/StateGet.php

@@ -71,7 +71,7 @@ class StateGet extends AgentTool
         // Validate workspace context for tenant isolation
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required for state operations');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         // Query plan with workspace scope to prevent cross-tenant access

Mcp/Tools/Agent/State/StateList.php

@@ -70,7 +70,7 @@ class StateList extends AgentTool
         // Validate workspace context for tenant isolation
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required for state operations');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         // Query plan with workspace scope to prevent cross-tenant access

Mcp/Tools/Agent/State/StateSet.php

@@ -81,7 +81,7 @@ class StateSet extends AgentTool
         // Validate workspace context for tenant isolation
         $workspaceId = $context['workspace_id'] ?? null;
         if ($workspaceId === null) {
-            return $this->error('workspace_id is required for state operations');
+            return $this->error('workspace_id is required. Ensure you have authenticated with a valid API key and started a session. See: https://host.uk.com/ai');
         }
 
         // Query plan with workspace scope to prevent cross-tenant access

TODO.md

@@ -115,10 +115,10 @@ Production-quality task list for the AI agent orchestration package.
 
 ### Developer Experience
 
-- [ ] **DX-001: Missing workspace context error messages unclear**
+- [x] **DX-001: Missing workspace context error messages unclear** (FIXED 2026-02-23)
   - Location: Multiple MCP tools
-  - Issue: "workspace_id is required" doesn't explain how to fix
-  - Fix: Include context about authentication/session setup
+  - Issue: "workspace_id is required" didn't explain how to fix
+  - Fix: Updated error messages in PlanCreate, PlanGet, PlanList, StateSet, StateGet, StateList, SessionStart to include actionable guidance and link to documentation
 
 - [ ] **DX-002: AgenticManager doesn't validate API keys on init**
   - Location: `Services/AgenticManager.php::registerProviders()`