docs: add EnableCondition migration guide for remote server

Author: SamMorrowDrums

docs/enable-condition-migration.md

@@ -0,0 +1,194 @@
+# EnableCondition Migration Guide for Remote Server
+
+This guide explains how to adopt the composable `EnableCondition` system in `github/github-mcp-server-remote`.
+
+## Go Module Update
+
+To use this feature, update your `go.mod`:
+
+```bash
+go get github.com/github/github-mcp-server@3a52f7bd4ba45a6799eb9209db09080428bf0878
+```
+
+Or add directly to `go.mod`:
+```
+require github.com/github/github-mcp-server v0.0.0-20251218XXXXXX-3a52f7bd4ba4
+```
+
+Then run `go mod tidy`.
+
+> **Note**: Once PR #1641 is merged, you can use `@main` or wait for a tagged release.
+
+## Quick Start
+
+### Before (old approach with Enabled func)
+
+```go
+tool := inventory.ServerTool{
+    Tool: mcp.Tool{Name: "my_tool"},
+    Enabled: func(ctx context.Context) (bool, error) {
+        // CCA bypass pattern
+        if isCCA(ctx) {
+            return true, nil
+        }
+        // Otherwise check feature flag
+        return checkFeatureFlag(ctx, "my_feature")
+    },
+}
+```
+
+### After (new approach with EnableCondition)
+
+```go
+tool := inventory.ServerTool{
+    Tool: mcp.Tool{Name: "my_tool"},
+    EnableCondition: inventory.Or(
+        inventory.ContextBool("is_cca"),
+        inventory.FeatureFlag("my_feature"),
+    ),
+}
+```
+
+## Available Primitives
+
+```go
+import "github.com/github/github-mcp-server/pkg/inventory"
+
+// Feature flag - checked via FeatureCheckerFromContext
+inventory.FeatureFlag("flag_name")
+
+// Context bool - checked via ContextBoolFromContext  
+inventory.ContextBool("key_name")
+
+// Static values
+inventory.Always()  // always enabled
+inventory.Never()   // always disabled
+inventory.Static(true)  // explicit bool
+```
+
+## Combinators
+
+```go
+// AND - all must be true (short-circuits on first false)
+inventory.And(cond1, cond2, cond3)
+
+// OR - any must be true (short-circuits on first true)
+inventory.Or(cond1, cond2, cond3)
+
+// NOT - inverts condition
+inventory.Not(cond)
+```
+
+## Setting Up Context
+
+At request start, set up the context with your actor/request info:
+
+```go
+// 1. Set feature flag checker
+ctx = inventory.ContextWithFeatureChecker(ctx, func(ctx context.Context, flagName string) (bool, error) {
+    // Your feature flag service call
+    return myFeatureFlagService.IsEnabled(ctx, flagName, actor)
+})
+
+// 2. Set context bools (pre-computed actor properties)
+ctx = inventory.ContextWithBools(ctx, inventory.ContextBools{
+    "is_cca":              actor.IsCCA(),
+    "is_copilot_chat":     actor.IsCopilotChatHost(),
+    "has_paid_bing":       actor.HasPaidBing(),
+    "is_premium":          actor.IsPremium(),
+    "is_staff":            actor.IsStaff(),
+})
+```
+
+## Common Patterns
+
+### CCA Bypass (most common)
+```go
+// CCA users always get the tool, others need the feature flag
+tool.EnableCondition = inventory.Or(
+    inventory.ContextBool("is_cca"),
+    inventory.FeatureFlag("my_feature"),
+)
+```
+
+### Copilot-chat Host Bypass
+```go
+tool.EnableCondition = inventory.Or(
+    inventory.ContextBool("is_copilot_chat"),
+    inventory.FeatureFlag("my_feature"),
+)
+```
+
+### Multiple Requirements (AND)
+```go
+// Requires both premium AND feature flag
+tool.EnableCondition = inventory.And(
+    inventory.ContextBool("is_premium"),
+    inventory.FeatureFlag("advanced_features"),
+)
+```
+
+### Kill Switch Pattern
+```go
+// Enabled by default, but can be killed
+tool.EnableCondition = inventory.Not(
+    inventory.FeatureFlag("kill_my_tool"),
+)
+```
+
+### Complex Nested Conditions
+```go
+// Premium users OR (staff with beta flag), but not if kill switch is on
+tool.EnableCondition = inventory.And(
+    inventory.Or(
+        inventory.ContextBool("is_premium"),
+        inventory.And(
+            inventory.ContextBool("is_staff"),
+            inventory.FeatureFlag("beta_access"),
+        ),
+    ),
+    inventory.Not(inventory.FeatureFlag("kill_switch")),
+)
+```
+
+### Custom Logic (fallback)
+```go
+// For complex cases that can't be expressed with primitives
+tool.EnableCondition = inventory.ConditionFunc(func(ctx context.Context) (bool, error) {
+    actor := actorFromContext(ctx)
+    return someComplexLogic(actor), nil
+})
+```
+
+## How Optimization Works
+
+You don't need to do anything special - optimization is automatic:
+
+1. **Build time**: `Builder.Build()` compiles all `EnableCondition`s into bitmask evaluators
+2. **Request time**: `AvailableTools(ctx)` builds a `RequestMask` once (evaluates all flags/bools), then uses O(1) bitmask operations per tool
+3. **Pre-sorted**: Tools are sorted at build time, so filtering preserves order without re-sorting
+
+### Performance
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Time (1000 req × 50 tools) | 23.7ms | 12.9ms | **46% faster** |
+| Allocations | 15000 | 12000 | 20% fewer |
+
+## Migration Strategy
+
+1. **Phase 1**: Add `EnableCondition` alongside existing `Enabled` func (both work)
+2. **Phase 2**: Gradually migrate tools to `EnableCondition`
+3. **Phase 3**: Remove old `Enabled` funcs once all migrated
+
+The system is fully backward compatible - `Enabled` func is checked first, then `EnableCondition`.
+
+## Files to Reference
+
+- [conditions.go](../pkg/inventory/conditions.go) - EnableCondition interface and primitives
+- [condition_compiler.go](../pkg/inventory/condition_compiler.go) - Bitmask compiler (you don't need to use this directly)
+- [conditions_test.go](../pkg/inventory/conditions_test.go) - Usage examples in tests
+
+## Questions?
+
+See PR #1641 for discussion or reach out to @SamMorrowDrums.