Cont prep for V2 release

Author: ddebowczyk

docs-build/packages/agents/01-introduction.mdx

@@ -31,7 +31,7 @@ $agent = AgentBuilder::base()
     ->withCapability(new UseBash())
     ->withCapability(new UseGuards(maxSteps: 10))
     ->build();
-// @doctest id="29c6"
+// @doctest id="e81d"
 ```
 
 ## Package Structure
@@ -53,7 +53,7 @@ Hook/                 # HookStack, HookInterface, HookContext, built-in hooks
 Interception/         # CanInterceptAgentLifecycle, PassThroughInterceptor
 Template/             # Agent definitions, parsers, registry
 Tool/                 # ToolInterface, BaseTool, FunctionTool, ToolExecutor
-// @doctest id="4b57"
+// @doctest id="bffa"
 ```
 
 ## Minimal Example
@@ -66,5 +66,5 @@ $state = AgentState::empty()->withUserMessage('Hello!');
 $result = $loop->execute($state);
 
 echo $result->finalResponse()->toString();
-// @doctest id="a23d"
+// @doctest id="f32f"
 ```

docs-build/packages/agents/02-basic-agent.mdx

@@ -18,7 +18,7 @@ $result = $loop->execute($state);
 
 echo $result->finalResponse()->toString();
 // "2 + 2 equals 4."
-// @doctest id="ab9a"
+// @doctest id="162b"
 ```
 
 ## What Happens
@@ -50,7 +50,7 @@ $result = $loop->execute($state);
 
 echo $result->finalResponse()->toString();
 // "The weather in Paris is 72°F and sunny."
-// @doctest id="0747"
+// @doctest id="996c"
 ```
 
 ## Customizing the Loop
@@ -81,7 +81,7 @@ $loop = AgentLoop::default()->withDriver(new ReActDriver(
     structuredOutput: $structuredOutput,
     model: 'gpt-4o',
 ));
-// @doctest id="688b"
+// @doctest id="b92b"
 ```
 
 ## System Prompt
@@ -90,7 +90,7 @@ $loop = AgentLoop::default()->withDriver(new ReActDriver(
 $state = AgentState::empty()
     ->withSystemPrompt('You are a helpful assistant.')
     ->withUserMessage('Hello!');
-// @doctest id="015f"
+// @doctest id="47e3"
 ```
 
 ## Using AgentBuilder
@@ -110,7 +110,7 @@ $agent = AgentBuilder::base()
     ->build();
 
 $result = $agent->execute($state);
-// @doctest id="cd2e"
+// @doctest id="54bd"
 ```
 
 See [AgentBuilder & Capabilities](13-agent-builder.md) for details.

docs-build/packages/agents/03-basic-concepts.mdx

@@ -11,7 +11,7 @@ The orchestrator. Runs a step-based loop: call LLM, execute tools, check stop co
 
 ```
 BeforeExecution -> [ BeforeStep -> UseTools -> AfterStep -> ShouldStop? ] -> AfterExecution
-// @doctest id="434d"
+// @doctest id="8062"
 ```
 
 ## AgentState
@@ -31,7 +31,7 @@ $state = AgentState::empty()
     ->withSystemPrompt('You are helpful.')
     ->withUserMessage('Hello')
     ->withBudget(new AgentBudget(maxSteps: 10));
-// @doctest id="b66a"
+// @doctest id="f4b9"
 ```
 
 ## AgentContext
@@ -42,7 +42,7 @@ Holds the conversation data: messages, system prompt, metadata, and response for
 $state = AgentState::empty()
     ->withSystemPrompt('You are helpful.')
     ->withMetadata('user_id', 123);
-// @doctest id="9591"
+// @doctest id="14b8"
 ```
 
 ## AgentStep
@@ -67,5 +67,5 @@ Tracks the current execution's transient state: status, completed steps, current
 $state->execution()->status();        // ExecutionStatus::InProgress
 $state->execution()->stepCount();     // 3
 $state->execution()->shouldStop();    // false
-// @doctest id="3408"
+// @doctest id="6f28"
 ```

docs-build/packages/agents/04-controlling-the-loop.mdx

@@ -11,7 +11,7 @@ description: 'Run agents to completion with execute() or step through with itera
 
 ```php
 $finalState = $loop->execute($state);
-// @doctest id="e561"
+// @doctest id="0c0a"
 ```
 
 `iterate()` yields state after each step, giving you full control:
@@ -26,7 +26,7 @@ foreach ($loop->iterate($state) as $stepState) {
         echo "  Tool: {$exec->name()} -> {$exec->value()}\n";
     }
 }
-// @doctest id="4ec1"
+// @doctest id="6edc"
 ```
 
 ## Inspecting State
@@ -51,7 +51,7 @@ $toolExec = $state->lastToolExecution();
 $toolExec?->name();     // 'weather'
 $toolExec?->value();    // '72F, sunny'
 $toolExec?->hasError(); // false
-// @doctest id="6c8b"
+// @doctest id="288f"
 ```
 
 ## Reading the Agent's Response
@@ -68,7 +68,7 @@ all other cases: forced stops, errors, budget exhaustion, etc.
 ```php
 $state->hasFinalResponse();             // true only on natural completion
 $state->finalResponse()->toString();    // strict: empty when interrupted
-// @doctest id="9e2e"
+// @doctest id="6d20"
 ```
 
 Use `finalResponse()` when you need to distinguish between a genuine
@@ -82,7 +82,7 @@ otherwise the last step's output messages regardless of step type.
 
 ```php
 $state->currentResponse()->toString();  // pragmatic: last output text
-// @doctest id="f337"
+// @doctest id="e730"
 ```
 
 Use `currentResponse()` when you want to show *something* to the user
@@ -111,7 +111,7 @@ if ($state->hasFinalResponse()) {
     echo "Agent stopped: {$reason->value}\n";
     echo $state->currentResponse()->toString();
 }
-// @doctest id="a4ac"
+// @doctest id="dd6f"
 ```
 
 ## Listening to Events
@@ -129,5 +129,5 @@ $loop->onEvent(AgentStepCompleted::class, function (AgentStepCompleted $event) {
 $loop->wiretap(function ($event) {
     echo get_class($event) . "\n";
 });
-// @doctest id="439f"
+// @doctest id="d62e"
 ```

docs-build/packages/agents/05-tools.mdx

@@ -16,7 +16,7 @@ use Cognesy\Agents\Collections\Tools;use Cognesy\Agents\Tool\Tools\MockTool;
 
 $calculator = MockTool::returning('calculator', 'Performs math', '42');
 $tools = new Tools($calculator);
-// @doctest id="0ed4"
+// @doctest id="bb44"
 ```
 
 ## Using FunctionTool
@@ -33,7 +33,7 @@ $tool = FunctionTool::fromCallable(
 );
 
 $tools = new Tools($tool);
-// @doctest id="c48b"
+// @doctest id="7b15"
 ```
 
 ## Multiple Tools
@@ -57,7 +57,7 @@ $calculator = FunctionTool::fromCallable(
 );
 
 $tools = new Tools($weather, $calculator);
-// @doctest id="ac7d"
+// @doctest id="e419"
 ```
 
 ## Agent with Tools
@@ -71,7 +71,7 @@ $loop = AgentLoop::default()->withTools($tools);
 $state = AgentState::empty()->withUserMessage('What is the weather in Paris?');
 $result = $loop->execute($state);
 // LLM calls the weather tool, gets result, then responds
-// @doctest id="1c5a"
+// @doctest id="25ad"
 ```
 
 ## Tool Contracts
@@ -88,7 +88,7 @@ interface ToolInterface {
     public function toToolSchema(): array;           // JSON schema sent to LLM
     public function descriptor(): CanDescribeTool;   // metadata accessor
 }
-// @doctest id="2465"
+// @doctest id="e6bc"
 ```
 
 ### CanDescribeTool
@@ -102,7 +102,7 @@ interface CanDescribeTool {
     public function metadata(): array;       // summary for browsing/discovery
     public function instructions(): array;   // full specification with parameters
 }
-// @doctest id="b643"
+// @doctest id="6b26"
 ```
 
 `metadata()` returns lightweight info (name, summary, namespace) for tool listings. `instructions()` returns the complete specification including parameters and return type.
@@ -127,7 +127,7 @@ class WeatherTool extends BaseTool
         return "Weather in {$city}: 72F, sunny";
     }
 }
-// @doctest id="58aa"
+// @doctest id="5a3b"
 ```
 
 See [Building Tools](06-building-tools.md) for the full guide on creating custom tools.

docs-build/packages/agents/06-building-tools.mdx

@@ -30,7 +30,7 @@ class GetWeather extends BaseTool
         return "Weather in {$city}: 22 {$unit}";
     }
 }
-// @doctest id="eacf"
+// @doctest id="1625"
 ```
 
 ## Using FunctionTool
@@ -43,7 +43,7 @@ use Cognesy\Agents\Tool\Tools\FunctionTool;
 $tool = FunctionTool::fromCallable(function (string $query): string {
     return "Results for: {$query}";
 });
-// @doctest id="e5d3"
+// @doctest id="6d36"
 ```
 
 ## Accessing Agent State
@@ -59,7 +59,7 @@ class StatefulTool extends BaseTool
         return "Step {$stepCount}: processing {$input}";
     }
 }
-// @doctest id="d110"
+// @doctest id="1137"
 ```
 
 ## The ToolInterface
@@ -73,7 +73,7 @@ interface ToolInterface
     public function toToolSchema(): array;
     public function descriptor(): CanDescribeTool;
 }
-// @doctest id="641f"
+// @doctest id="8844"
 ```
 
 - `use()` - execute the tool, returns `Result` (success or failure)
@@ -116,7 +116,7 @@ final readonly class MyToolDescriptor extends ToolDescriptor
         );
     }
 }
-// @doctest id="d8ae"
+// @doctest id="7c43"
 ```
 
 Then wire it into your tool:
@@ -144,7 +144,7 @@ class MyTool extends BaseTool
         return "Processed: {$input}";
     }
 }
-// @doctest id="1c16"
+// @doctest id="baae"
 ```
 
 Most built-in tools use this pattern — `BashTool` has `BashToolDescriptor`, each file tool has its own descriptor, and so on. The `metadata()` and `instructions()` arrays power progressive disclosure: tool registries can show lightweight summaries via `metadata()`, while the LLM receives full specifications via `instructions()` when needed.
@@ -158,5 +158,5 @@ $tool = MockTool::returning('my_tool', 'Does something', 'fixed result');
 
 // Or with custom logic
 $tool = new MockTool('my_tool', 'Does something', fn($x) => strtoupper($x));
-// @doctest id="9a0c"
+// @doctest id="1988"
 ```

docs-build/packages/agents/07-context-and-compilers.mdx

@@ -18,7 +18,7 @@ $state = AgentState::empty()
 $state->context()->systemPrompt();
 $state->context()->messages();
 $state->context()->metadata();
-// @doctest id="44b4"
+// @doctest id="5e1c"
 ```
 
 ## Message Compilers
@@ -30,7 +30,7 @@ interface CanCompileMessages
 {
     public function compile(AgentState $state): Messages;
 }
-// @doctest id="6408"
+// @doctest id="c0ab"
 ```
 
 The default compiler assembles messages from the agent's context. You can replace it to control exactly what the LLM sees.
@@ -50,7 +50,7 @@ class MyCompiler implements CanCompileMessages
         return $state->messages();
     }
 }
-// @doctest id="15dc"
+// @doctest id="f5a8"
 ```
 
 Inject it into the loop's driver:
@@ -62,7 +62,7 @@ $driver = new ToolCallingDriver(
     messageCompiler: new MyCompiler(),
 );
 $loop = AgentLoop::default()->withDriver($driver);
-// @doctest id="3816"
+// @doctest id="9cec"
 ```
 
 Or via `AgentBuilder`:
@@ -74,7 +74,7 @@ use Cognesy\Agents\Capability\Core\UseContextCompiler;
 $agent = AgentBuilder::base()
     ->withCapability(new UseContextCompiler(new MyCompiler()))
     ->build();
-// @doctest id="c329"
+// @doctest id="0d9f"
 ```
 
 ## Use Cases
@@ -117,7 +117,7 @@ class TokenLimitCompiler implements CanCompileMessages
         return Messages::fromArray($kept);
     }
 }
-// @doctest id="2780"
+// @doctest id="5e6f"
 ```
 
 Use as a decorator via `UseContextCompilerDecorator`:
@@ -130,7 +130,7 @@ $agent = AgentBuilder::base()
         fn(CanCompileMessages $inner) => new TokenLimitCompiler($inner, maxTokens: 4000)
     ))
     ->build();
-// @doctest id="0cd9"
+// @doctest id="b235"
 ```
 
 The decorator pattern wraps the default compiler, so you get standard message assembly plus your custom logic on top.