Merge master (post-#113 identity checklist) into docs/issue-108-compact-controller-handoff

docs/llm-workflow-runbooks.md

@@ -124,8 +124,35 @@ and the two `GITEA_MCP_*` variables — never a token or password:
 }
 ```
 
-Run the same server as several launcher entries (e.g. `-author`, `-reviewer`,
-`-merger`), each pointing at a different `GITEA_MCP_PROFILE`.
+### Dual-profile MCP launcher pattern (Recommended)
+
+To avoid the bottleneck of relaunching/restarting the MCP server to switch between author and reviewer roles, the client should register **both** profiles concurrently as separate server instances in the client's MCP configuration:
+
+```json
+"gitea-author": {
+  "command": "/path/to/Gitea-Tools/venv/bin/python3",
+  "args": ["/path/to/Gitea-Tools/mcp_server.py"],
+  "env": {
+    "GITEA_MCP_CONFIG": "/path/to/.config/gitea-tools/profiles.json",
+    "GITEA_MCP_PROFILE": "prgs-author"
+  }
+},
+"gitea-reviewer": {
+  "command": "/path/to/Gitea-Tools/venv/bin/python3",
+  "args": ["/path/to/Gitea-Tools/mcp_server.py"],
+  "env": {
+    "GITEA_MCP_CONFIG": "/path/to/.config/gitea-tools/profiles.json",
+    "GITEA_MCP_PROFILE": "prgs-reviewer"
+  }
+}
+```
+
+* **Tool Namespaces:** Tool calls become distinct and identity-scoped in the client UI:
+  * `mcp__gitea-author__*` (for creating issues, pushing branches, creating PRs)
+  * `mcp__gitea-reviewer__*` (for reviewing PRs, approving, requesting changes, merging)
+* **Trust Model:** Separate tokens remain separate in the keychain/environment. Each instance operates under its own `GITEA_MCP_PROFILE` and enforces its own `allowed_operations`. A runtime `whoami` identity check is still performed independently, and self-review/self-merge checks remain strictly mandatory. The dual-server pattern is a operational convenience and never a security bypass.
+* **Reviewer-Identity PR Creation Deadlock:** Reviewer/merge identities must not create PRs or push branches. Doing so makes the reviewer identity the PR author in Gitea, blocking subsequent independent review and causing a review deadlock. Normally, PRs must be created by the author/work identity (`gitea-author`), leaving the reviewer identity (`gitea-reviewer`) clean and available for independent review and merge.
+* **Fallback:** If the dual-profile MCP launcher pattern is not supported or configured in the client, the LLM must relaunch or restart the client/MCP with the correct profile environment variable before claiming or working on any tasks.
 
 ## Setup runbook — interactive menu