[docs] Consolidate developer specifications - fix tone, add Gemini MCP config pattern (v2.5)

scratchpad/dev.md

@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 2.4
-**Last Updated**: 2026-02-17
+**Version**: 2.5
+**Last Updated**: 2026-02-19
 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows
 
 This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices.
@@ -1448,6 +1448,37 @@ func LoadMCPConfig(path string) (*MCPConfig, error) {
 }
 ```
 
+### Engine-Specific MCP Config Delivery
+
+Some AI engine CLIs do not support a `--mcp-config` flag and instead read MCP server configuration from engine-native config files. When implementing `RenderMCPConfig()` for such engines, write configuration to the engine's expected location rather than passing it via CLI flag.
+
+**Pattern: Standard CLI flag** (Claude, Copilot, Codex):
+```go
+// Engine reads MCP config from --mcp-config flag
+args = append(args, "--mcp-config", "/tmp/gh-aw/mcp-config/mcp-servers.json")
+```
+
+**Pattern: Engine-native config file** (Gemini):
+```bash
+# Gemini CLI does not support --mcp-config flag
+# Use a conversion script to write to .gemini/settings.json instead
+actions/setup/sh/convert_gateway_config_gemini.sh
+# Writes MCP server configuration to .gemini/settings.json (project-level)
+```
+
+**Implementation**: Use a shell script in `actions/setup/sh/` to convert the MCP gateway config to the engine's native format. Route the engine to this script via `start_mcp_gateway.sh`.
+
+```mermaid
+graph LR
+    GW[MCP Gateway Config] --> Script[convert_gateway_config_<engine>.sh]
+    Script --> NativeConfig[Engine-native config file]
+    NativeConfig --> Engine[AI Engine CLI]
+```
+
+When adding a new engine, check the engine CLI's documentation to determine whether it supports `--mcp-config` or requires an alternative config delivery method.
+
+---
+
 ### MCP Logs Guardrail
 
 **Purpose**: Prevent sensitive information leakage in MCP logs
@@ -1745,6 +1776,7 @@ type Everything interface {
 ---
 
 **Document History**:
+- v2.5 (2026-02-19): Fixed 6 tone issues in engine review docs, added Engine-Specific MCP Config Delivery section (Gemini pattern), analyzed 61 files
 - v2.4 (2026-02-17): Quality verification - analyzed 4 new files, zero tone issues found across all 61 files
 - v2.3 (2026-02-16): Quality verification - zero tone issues, all formatting standards maintained
 - v2.2 (2026-02-15): Quality verification with metadata update

scratchpad/engine-architecture-review.md

@@ -6,7 +6,7 @@
 
 ## Executive Summary
 
-The agentic engine architecture is **well-designed and ready for extension**. The Interface Segregation Principle (ISP) implementation provides excellent flexibility for adding new engines while maintaining backward compatibility. Minor improvements and comprehensive documentation have been added to further enhance extensibility.
+The agentic engine architecture follows the Interface Segregation Principle (ISP) and is structured for extension. The ISP implementation provides flexibility for adding new engines while maintaining backward compatibility. Minor improvements and comprehensive documentation have been added to further enhance extensibility.
 
 ### Key Findings
 
@@ -307,7 +307,7 @@ Engine code includes:
 
 ## Conclusion
 
-The agentic engine architecture is **well-designed, secure, and ready for extension**. The Interface Segregation Principle implementation provides excellent flexibility while maintaining backward compatibility. All current implementations follow established patterns and are thoroughly tested.
+The agentic engine architecture follows ISP, implements security at multiple layers, and is structured for extension. The Interface Segregation Principle implementation provides flexibility while maintaining backward compatibility. All current implementations follow established patterns and are thoroughly tested.
 
 The addition of comprehensive documentation (`adding-new-engines.md`) significantly improves the developer experience for adding new engines. The architecture requires no structural changes and is ready to support additional integrations.
 
@@ -339,7 +339,7 @@ The addition of comprehensive documentation (`adding-new-engines.md`) significan
 
 ### No Code Changes Required
 
-The architecture itself requires **no structural changes**. The codebase is well-organized, follows SOLID principles, and provides excellent extensibility through:
+The architecture itself requires **no structural changes**. The codebase follows SOLID principles and provides extensibility through:
 - Interface segregation
 - BaseEngine defaults
 - Shared helper functions

scratchpad/engine-review-summary.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Completed comprehensive deep review of the agentic engine architecture, interface design, and all implementations (Copilot, Claude, Codex, Custom). The architecture is **excellent and ready for extension**.
+Completed comprehensive deep review of the agentic engine architecture, interface design, and all implementations (Copilot, Claude, Codex, Custom). The architecture is structured for extension and follows established ISP patterns.
 
 ## What Was Reviewed
 
@@ -273,7 +273,7 @@ All implementations follow established patterns and are thoroughly tested.
 
 ## Conclusion
 
-The agentic engine architecture is **production-ready and well-designed**. It follows SOLID principles, has excellent test coverage, and provides clear extensibility patterns through:
+The agentic engine architecture is **production-ready**. It follows SOLID principles, has comprehensive test coverage, and provides clear extensibility patterns through:
 
 1. **Interface Segregation**: Focused interfaces composed together
 2. **BaseEngine Defaults**: Sensible defaults for all methods

scratchpad/errors.md

@@ -142,7 +142,7 @@ enhanced := workflow.EnhanceError(
 
 **Use when:**
 - Adding context to errors from external libraries
-- Providing user-friendly explanations
+- Providing clear explanations for end users
 - Adding suggestions without changing error structure
 
 #### WrapErrorWithContext