docs(ai-service): update readme with plugin protocol integration

Update AI service README to reflect the dual-service architecture (AI operations + plugin protocol) and complete integration guide.

Architecture Updates:
- Document both GitCaddyAIService and PluginService running on port 5000
- Add architecture diagram showing server's AI client and plugin manager connections
- Clarify h2c (cleartext HTTP/2) transport for gRPC + REST on same port

API Reference:
- Add plugin protocol RPC methods (Initialize, HealthCheck, OnEvent, Shutdown)
- Explain plugin lifecycle and health monitoring (30s intervals)
- Document manifest-based capability declaration

Integration Guide:
- Split configuration into [ai] (operations) and [plugins.gitcaddy-ai] (lifecycle)
- Explain how both sections work together for complete integration
- Update client examples to use port 5000 (was 5051)
- Add transport details and event subscription explanation

This provides a complete picture of how the AI service integrates with the server as both an AI operations provider and a managed plugin.

README.md

@@ -13,19 +13,30 @@ AI-powered code intelligence service for GitCaddy. Provides code review, documen
 
 ## Architecture
 
+The AI service runs as a sidecar alongside the GitCaddy server. It exposes two gRPC services on the same port (HTTP/2 + HTTP/1.1):
+
+- **GitCaddyAIService** - AI operations (review, triage, docs, chat) called by the server's AI client
+- **PluginService** - Plugin lifecycle protocol (initialize, health, events) managed by the server's external plugin manager
+
 ```
-┌─────────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────────────┐
-│  GitCaddy Server (Go)                                           │
+│  GitCaddy Server (Go)                                                │
-│  └── AI Client (gRPC)                                           │
+│  ├── AI Client (gRPC) ──────────────── GitCaddyAIService             │
-│        │                                                        │
+│  │     ReviewPullRequest, TriageIssue,     │                         │
-│        ▼                                                        │
+│  │     ExplainCode, GenerateDocumentation  │                         │
-│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                                         │                         │
-│  │  GitCaddy AI Service (.NET 9)                           │   │
+│  └── External Plugin Manager (gRPC) ─── PluginService                │
-│  │  ├── gRPC API                                           │   │
+│        Initialize, HealthCheck (30s),      │                         │
-│  │  ├── MarketAlly.AIPlugin (Multi-provider AI)            │   │
+│        OnEvent, Shutdown                   ▼                         │
-│  │  └── License Validation                                 │   │
+│                                   ┌──────────────────────────┐      │
-│  └─────────────────────────────────────────────────────────┘   │
+│                                   │  GitCaddy AI (.NET 9)    │      │
-└─────────────────────────────────────────────────────────────────┘
+│                                   │  Port 5000 (h2c + HTTP)  │      │
+│                                   │  ├── AI Providers         │      │
+│                                   │  │   (Claude/OpenAI/      │      │
+│                                   │  │    Gemini)             │      │
+│                                   │  └── License Validation   │      │
+│                                   └──────────────────────────┘      │
+└──────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Quick Start
@@ -94,7 +105,9 @@ Environment variable format: `AIService__DefaultProvider=Claude`
 
 ## API Reference
 
-The service exposes a gRPC API defined in `protos/gitcaddy_ai.proto`.
+The service exposes two gRPC services on port 5000 (cleartext HTTP/2):
+
+### AI Operations (`protos/gitcaddy_ai.proto`)
 
 ### Code Review
 
@@ -134,6 +147,21 @@ rpc ExecuteTask(ExecuteTaskRequest) returns (ExecuteTaskResponse);
 rpc Chat(stream ChatRequest) returns (stream ChatResponse);
 ```
 
+### Plugin Protocol (`protos/plugin.proto`)
+
+The plugin protocol allows the GitCaddy server to manage this service as an external plugin:
+
+```protobuf
+rpc Initialize(InitializeRequest) returns (InitializeResponse);
+rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
+rpc HealthCheck(PluginHealthCheckRequest) returns (PluginHealthCheckResponse);
+rpc GetManifest(GetManifestRequest) returns (PluginManifest);
+rpc OnEvent(PluginEvent) returns (EventResponse);
+rpc HandleHTTP(HTTPRequest) returns (HTTPResponse);
+```
+
+The server calls `Initialize` on startup, `HealthCheck` every 30 seconds, `OnEvent` for subscribed events (e.g., `license:updated`), and `Shutdown` on server stop. The service declares its capabilities (routes, permissions, license tier) via the `PluginManifest` returned during initialization.
+
 ## Client Libraries
 
 ### .NET Client
@@ -141,7 +169,7 @@ rpc Chat(stream ChatRequest) returns (stream ChatResponse);
 ```csharp
 using GitCaddy.AI.Client;
 
-var client = new GitCaddyAIClient("http://localhost:5051");
+var client = new GitCaddyAIClient("http://localhost:5000");
 
 var response = await client.ReviewPullRequestAsync(new ReviewPullRequestRequest
 {
@@ -159,7 +187,7 @@ Console.WriteLine(response.Summary);
 ```go
 import ai "git.marketally.com/gitcaddy/gitcaddy-ai/go/gitcaddy-ai-client"
 
-client, err := ai.NewClient("localhost:5051")
+client, err := ai.NewClient("localhost:5000")
 if err != nil {
     log.Fatal(err)
 }
@@ -213,14 +241,43 @@ go generate
 
 ## Integration with GitCaddy Server
 
-Add the AI client to your GitCaddy server configuration:
+Add both sections to the server's `app.ini`:
+
+**1. AI client configuration** (how the server calls AI operations):
 
 ```ini
 [ai]
 ENABLED = true
-SERVICE_URL = http://localhost:5051
+SERVICE_URL = localhost:5000
+DEFAULT_PROVIDER = claude
+DEFAULT_MODEL = claude-sonnet-4-20250514
+CLAUDE_API_KEY = sk-ant-...
 ```
 
+See the [server README](https://git.marketally.com/gitcaddy/gitcaddy-server#ai-features-configuration) for the full `[ai]` reference.
+
+**2. Plugin registration** (how the server manages the sidecar's lifecycle):
+
+```ini
+[plugins]
+ENABLED = true
+HEALTH_CHECK_INTERVAL = 30s
+
+[plugins.gitcaddy-ai]
+ENABLED = true
+ADDRESS = localhost:5000
+HEALTH_TIMEOUT = 5s
+SUBSCRIBED_EVENTS = license:updated
+```
+
+With both sections configured, the server will:
+- Call AI operations (review, triage, etc.) via `[ai] SERVICE_URL`
+- Manage the sidecar's lifecycle via the plugin protocol on `[plugins.gitcaddy-ai] ADDRESS`
+- Health-check the sidecar every 30 seconds and log status changes
+- Dispatch subscribed events (e.g., license updates) to the sidecar in real-time
+
+**Transport**: All communication uses cleartext HTTP/2 (h2c). The sidecar's Kestrel server is configured for `Http1AndHttp2` on port 5000, supporting both gRPC (HTTP/2) and REST (HTTP/1.1) on the same port.
+
 ## Support
 
 - Documentation: https://docs.gitcaddy.com/ai