fix: surface Gitea auth errors and document the service PAT

Two related issues made the connected MCP server return a bare "Internal
server error" for tools that need real Gitea API access (e.g.
list_repositories), while public-repo-by-path reads worked:

1. Gitea OIDC access tokens only carry openid/profile/email and cannot call
   the repository REST API, so pure-OAuth mode fails for most tools. A service
   PAT (GITEA_TOKEN) is required in practice; per-user permission is still
   enforced before each call, so this does not weaken authorization.
2. The tool handlers caught GiteaError broadly and re-raised it as RuntimeError.
   Because GiteaAuthenticationError/GiteaAuthorizationError subclass GiteaError,
   a clean 401/403 was masked as a generic internal error and the server's
   re-authorization guidance never fired.

Changes:
- read_tools.py / repository.py / write_tools.py: re-raise the auth/authz
  subclasses before the broad GiteaError catch so server.py returns actionable
  guidance instead of a generic 500.
- .env.example + README.md: document GITEA_TOKEN as a least-privilege bot PAT,
  explain why it's needed and that OAuth remains authoritative, and note that
  list_repositories is intentionally unavailable in service-PAT mode.
- tests: assert tool handlers propagate auth errors unwrapped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -68,7 +68,16 @@ AUTOMATION_ENABLED=false
 AUTOMATION_SCHEDULER_ENABLED=false
 AUTOMATION_STALE_DAYS=30
 
-# Legacy compatibility (not used for OAuth-protected MCP tool execution)
-# GITEA_TOKEN=
+# Service PAT for Gitea REST execution (recommended in OAuth mode).
+# Gitea's OIDC access tokens carry only openid/profile/email and CANNOT call the
+# repository REST API, so without this most tools fail. Set GITEA_TOKEN to a
+# Personal Access Token from a DEDICATED bot account with least privilege:
+#   - scope: read:repository  (add write:repository only if WRITE_MODE=true)
+# The user's OAuth identity is still authoritative: before every repository call
+# the server checks that the signed-in user has permission on the target repo and
+# denies it otherwise — the PAT only performs the API call after that check.
+GITEA_TOKEN=
+
+# API-key mode only (used when OAUTH_MODE=false). Leave unset in OAuth mode.
 # MCP_API_KEYS=
 # AUTH_ENABLED=true