docs: add state machine and component diagrams to README

Author: OgeonX-Ai

README.md

@@ -20,6 +20,72 @@ The state machine drives the entire flow. Each state uses GitHub MCP tools via s
 
 ---
 
+## Diagrams
+
+### State Machine
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    [*] --> Idle
+    Idle --> Analyzing
+    Analyzing --> Branching
+    Branching --> Editing
+    Editing --> Validating
+    Validating --> Committing
+    Committing --> PrCreating
+    PrCreating --> Reviewing
+    Reviewing --> Documenting
+    Documenting --> [*]
+```
+
+**State descriptions:**
+
+- **Idle** — Fetches repository metadata and full issue body from GitHub via MCP. Reads labels and default branch.
+- **Analyzing** — Asks Claude to produce an implementation plan: branch name, files to modify, summary, and whether tests are required. Retries up to 3 times if JSON parse fails.
+- **Branching** — Creates a new feature branch from the default branch. Idempotent: if the branch already exists, resumes from it.
+- **Editing** — For each file in the plan, runs a ReAct loop: reads current content, asks Claude to edit it, commits the result via `create_or_update_file`. Max 20 turns per file.
+- **Validating** — Runs four gates: file safety blocklist, merge conflict pre-flight, diff size, and test coverage intent. Blocks on critical failures; warns on soft failures.
+- **Committing** — Confirms the final commit SHA is present on the branch by calling `get_branch`. Records the commit URL.
+- **PrCreating** — Generates a PR title and body via Claude, then opens the pull request. Idempotent: checks for an existing open PR from the same branch before creating.
+- **Reviewing** — Posts a bot review comment explaining what changed and why. Requests reviewers from `GSD_REVIEWERS` env var if configured.
+- **Documenting** — Updates `docs/github-mcp-tools.md` and `CHANGELOG.md` on the default branch. If `GSD_AUTO_MERGE=true`, squash-merges the PR.
+
+---
+
+### Component Topology
+
+```mermaid
+flowchart LR
+    subgraph Orchestrator["GSD Orchestrator (.NET 10)"]
+        SM[GsdStateMachine]
+        MCP[McpStdioClient]
+        LLM[Anthropic.SDK]
+        CP[FileCheckpointStore]
+    end
+
+    subgraph GitHub["GitHub"]
+        MCPS[github-mcp-server.exe]
+        GHAPI[GitHub API]
+    end
+
+    subgraph Anthropic["Anthropic"]
+        CLAUDE[Claude API]
+    end
+
+    subgraph Storage["Local Storage"]
+        CKPT[.gsd/state/]
+    end
+
+    SM --> MCP
+    MCP -->|stdio| MCPS
+    MCPS --> GHAPI
+    SM --> LLM
+    LLM --> CLAUDE
+    SM --> CP
+    CP --> CKPT
+```
+
 ## Prerequisites
 
 - Windows (Task Scheduler integration for auto-start)