docs: update CLAUDE.md and DevUI README for Orleans bridge architecture

Add DevUI and MCP sections to CLAUDE.md documenting the Orleans client
architecture, OrleansAgentChatClient bridge, and registered agents.
Rewrite DevUI README replacing the default template content.

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

Author: LeftTwixWand

CLAUDE.md

@@ -31,12 +31,12 @@ dotnet test IAW.slnx --filter "FullyQualifiedName~MethodName"       # run a sing
 src/
   Core/Core.csproj                  -- Agent base class (AgentV2), V2 contracts, LLM integration
   IAW.AppHost/Aspire.csproj         -- Aspire orchestration (AppHost)
-  IAW.MCP/MCP.csproj                -- MCP server bridge (stdio, self-contained exe)
+  IAW.MCP/MCP.csproj                -- MCP server bridge (Orleans client, HTTP transport)
   IAW.ServiceDefaults/              -- Shared Aspire defaults (OpenTelemetry, health checks)
-  Clients.Telegram.Bot/             -- Telegram bot silo service
-  DevUI/                            -- Microsoft Agent Framework dev UI
+  Clients.Telegram.Bot/             -- Telegram bot (Orleans silo, ports 11112/30001)
+  DevUI/                            -- Microsoft Agent Framework DevUI (Orleans client → IAgent grains)
 samples/
-  Samples/Samples.csproj            -- Orleans silo with ~20 HTTP sample endpoints
+  Samples/Samples.csproj            -- Primary Orleans silo (ports 11111/30000), ~20 HTTP sample endpoints
   IAW.Testing/IAW.Testing.csproj    -- Testing framework: AgentTestV2<T>, AspireAgentTest<T>, ScenarioBuilder
 test/
   Core.Tests/                       -- AgentTestV2<Agent> behavior tests + architecture guards
@@ -83,6 +83,20 @@ Models are registered in `src/Core/AI/Models/` as singletons extending `LLMModel
 
 Multi-silo setup: `samples` on ports 11111/30000, `telegram-bot` on 11112/30001, joined via `PrimarySiloEndpoint` config.
 
+### DevUI (Microsoft Agent Framework)
+
+DevUI provides a web-based chat UI for interacting with Orleans agents. It runs as an **Orleans client** (not a silo) connecting to the `samples` silo via gateway.
+
+**Architecture**: DevUI → `OrleansAgentChatClient : IChatClient` → `IClusterClient.GetGrain<IAgent>(agentId)` → `RespondAsync()` → response.
+
+`OrleansAgentChatClient` bridges `Microsoft.Extensions.AI.IChatClient` to Orleans `IAgent` grains. The `AddAIAgent()` registration passes the grain ID as `instructions`, which the client uses for routing. GenAI telemetry flows through the grain's `UseOpenTelemetry()` pipeline.
+
+Well-known agents are registered in `Program.cs`: `personal-assistant`, `roslyn`, `dotnet`, `nuget`, `github`, `reviewer`, `fs`, `shell`, `git`, `build`, `knowledge`, `user`, `planning`, `notification`.
+
+### MCP Server
+
+`IAW.MCP` runs as an Orleans client connecting to `samples` silo. Exposes 8 orchestration tools via MCP HTTP transport: `agent_list_all`, `assistant_chat`, `agent_send_message`, `agent_get_status`, `agent_assign_task`, `agent_get_events`, `agent_get_metrics`, `agent_trigger_self_improvement`.
+
 ### Orleans Streaming
 
 Stream provider named `"agents"`. Behavior streams use namespaces `"agent-events"`, `"agent-history"`, `"agent-notifications"` keyed by agent ID. Custom streams supported via `PublishStreamAsync(namespace, streamId, message)`.

src/DevUI/README.md

@@ -1,129 +1,60 @@
-# AI Agent Web API
+# IAW DevUI
 
-This is an AI Agent Web API application created from the `aiagent-webapi` template. This template is currently in a preview stage. If you have feedback, please take a [brief survey](https://aka.ms/dotnet/aiagent-webapi/preview1/survey).
+Web-based chat UI for interacting with IAW Orleans agents, built on [Microsoft Agent Framework DevUI](https://aka.ms/dotnet/agent-framework/docs).
 
-## Prerequisites
+## Architecture
 
-- A GitHub Models API token (free to get started)
+DevUI runs as an **Orleans client** (not a silo), connecting to the `samples` silo via gateway port 30000.
 
-## Getting Started
-
-### 1. Configure Your AI Service
-
-#### GitHub Models Configuration
-
-This application uses GitHub Models (model: gpt-4o-mini) for AI functionality. You'll need to configure your GitHub Models API token:
-
-**Option A: Using User Secrets (Recommended for Development)**
-
-```bash
-dotnet user-secrets set "GITHUB_TOKEN" "your-github-models-token-here"
 ```
-
-**Option B: Using Environment Variables**
-
-Set the `GITHUB_TOKEN` environment variable:
-
-- **Windows (PowerShell)**:
-  ```powershell
-  $env:GITHUB_TOKEN = "your-github-models-token-here"
-  ```
-
-- **Linux/macOS**:
-  ```bash
-  export GITHUB_TOKEN="your-github-models-token-here"
-  ```
-
-#### Get a GitHub Models Token
-
-1. Visit [GitHub Models](https://github.com/marketplace/models)
-2. Sign in with your GitHub account
-3. Select a model (e.g., gpt-4o-mini)
-4. Click "Get API Key" or follow the authentication instructions
-5. Copy your personal access token
-
-
-### 2. Run the Application
-
-```bash
-dotnet run -lp https
+DevUI (Orleans Client)
+  └── OrleansAgentChatClient : IChatClient
+        └── IClusterClient.GetGrain<IAgent>(agentId).RespondAsync()
+              └── Agent grain in samples silo (with UseOpenTelemetry pipeline)
 ```
 
-The application will start and listen on:
-- HTTP: `http://localhost:5191`
-- HTTPS: `https://localhost:7283`
-
-### 3. Test the Application
-
-The application exposes OpenAI-compatible API endpoints. You can interact with the AI agents using any OpenAI-compatible client or tools.
-
-In development environments, a `/devui/` route is mapped to the Agent Framework development UI (DevUI), and when the app is launched through an IDE a browser will open to this URL. DevUI provides a web-based UI for interacting with agents and workflows. DevUI operates as an OpenAI-compatible client using the Responses and Conversations endpoints.
-
-## How It Works
+`OrleansAgentChatClient` bridges `Microsoft.Extensions.AI.IChatClient` to Orleans `IAgent` grains. The `AddAIAgent()` registration passes the grain ID as `instructions`, which the client uses for routing.
 
-This application demonstrates Agent Framework with:
+## Running
 
-1. **Writer Agent**: Writes short stories (300 words or less) about specified topics
-2. **Editor Agent**: Edits stories to improve grammar and style, ensuring they stay under 300 words
-3. **Publisher Workflow Agent**: A sequential workflow agent that combines the writer and editor agents
-
-The agents are exposed through OpenAI-compatible API endpoints, making them easy to integrate with existing tools and applications.
-
-## Template Parameters
-
-When creating a new project, you can customize it using template parameters:
+Always start via Aspire (never `dotnet run` directly):
 
 ```bash
-# Specify AI service provider
-dotnet new aiagent-webapi --provider azureopenai
-
-# Specify a custom chat model
-dotnet new aiagent-webapi --chat-model gpt-4o
-
-# Use API key authentication for Azure OpenAI
-dotnet new aiagent-webapi --provider azureopenai --managed-identity false
-
-# Use Ollama with a different model
-dotnet new aiagent-webapi --provider ollama --chat-model llama3.1
+aspire run
 ```
 
-### Available Parameters
-
-- **`--provider`**: Choose the AI service provider
-  - `githubmodels` (default) - GitHub Models
-  - `azureopenai` - Azure OpenAI
-  - `openai` - OpenAI Platform
-  - `ollama` - Ollama (local development)
-
-- **`--chat-model`**: Specify the chat model/deployment name
-  - Default for OpenAI/Azure OpenAI/GitHub Models: `gpt-4o-mini`
-  - Default for Ollama: `llama3.2`
-
-- **`--managed-identity`**: Use managed identity for Azure services (default: `true`)
-  - Only applicable when `--provider azureopenai`
-
-- **`--framework`**: Target framework (default: `net10.0`)
-  - Options: `net10.0`, `net9.0`, `net8.0`
-
-## Project Structure
-
-- `Program.cs` - Application entry point and configuration
-- `appsettings.json` - Application configuration
-- `Properties/launchSettings.json` - Launch profiles for development
-
-## Learn More
-
-- [AI apps for .NET developers](https://learn.microsoft.com/dotnet/ai)
-- [Microsoft Agent Framework Documentation](https://aka.ms/dotnet/agent-framework/docs)
-- [GitHub Models](https://github.com/marketplace/models)
-
-## Troubleshooting
-
-**Problem**: Application fails with "Missing configuration: GITHUB_TOKEN"
-
-**Solution**: Make sure you've configured your GitHub Models API token using one of the methods described above.
-
-**Problem**: API requests fail with authentication errors
-
-**Solution**: Verify your GitHub Models token is valid and hasn't expired. You may need to regenerate it from the GitHub Models website.
-
+DevUI is available at the `/devui/` path shown in the Aspire dashboard.
+
+## Registered Agents
+
+Well-known agents registered in `Program.cs`:
+
+| Agent | Grain ID | Role |
+|-------|----------|------|
+| PersonalAssistant | personal-assistant | Task decomposition and delegation |
+| Roslyn | roslyn | C# code intelligence |
+| DotNet | dotnet | Build, test, format |
+| NuGet | nuget | Package management |
+| GitHub | github | PRs, issues, releases |
+| Reviewer | reviewer | Code quality review |
+| FileSystem | fs | File read/write/search |
+| Shell | shell | Shell command execution |
+| Git | git | Version control |
+| Build | build | Generic build runner |
+| Knowledge | knowledge | Project knowledge store |
+| User | user | Preferences, memories |
+| Planning | planning | Execution plan generation |
+| Notification | notification | User alerts |
+
+## Telemetry
+
+GenAI telemetry flows through the agent pipeline:
+- `agent.respond` spans from `AgentV2.RespondAsync()`
+- `agent.llm` + GenAI spans when agents call `RespondWithLlmAsync()`
+- Trace sample ratio set to 1.0 for full capture in development
+
+## Key Files
+
+- `Program.cs` -- Orleans client setup, agent registration, DevUI mapping
+- `OrleansAgentChatClient.cs` -- IChatClient → IAgent grain bridge
+- `appsettings.json` -- Telemetry config (SampleRatio: 1.0)