docs: retarget setup to Claude connectors

docs/troubleshooting.md

@@ -1,15 +1,15 @@
 # Troubleshooting
 
-## "Internal server error (-32603)" from ChatGPT
+## "Internal server error (-32603)" from Claude
 
-**Symptom:** ChatGPT shows `Internal server error` with JSON-RPC error code `-32603` when trying to use Gitea tools.
+**Symptom:** Claude shows `Internal server error` with JSON-RPC error code `-32603` when trying to use Gitea tools.
 
-**Cause:** The OAuth token stored by ChatGPT was issued without Gitea API scopes (e.g. `read:repository`). This happens when the initial authorization request didn't include the correct `scope` parameter. The token passes OIDC validation (openid/profile/email) but gets **403 Forbidden** from Gitea's REST API.
+**Cause:** In user-token mode, the OAuth token stored by the client may have been issued without Gitea API scopes (e.g. `read:repository`). In service-PAT mode, the call may fail because the authenticated user does not have the required repository permission or the permission probe cannot be completed.
 
 **Fix:**
 1. In Gitea: Go to **Settings > Applications > Authorized OAuth2 Applications** and revoke the MCP application.
-2. In ChatGPT: Go to **Settings > Connected apps** and disconnect the Gitea integration.
-3. Re-authorize: Use the ChatGPT integration again. It will trigger a fresh OAuth flow with the correct scopes (`read:repository`).
+2. In Claude: disconnect the MCP server and authenticate again.
+3. Re-authorize: Use the MCP connector again. It will trigger a fresh OAuth flow. For repository-targeted calls in service-PAT mode, also verify the signed-in Gitea user has read/write access to the target repository.
 
 **Verification:** Check the server logs for `oauth_auth_summary`. A working token shows:
 ```
@@ -24,19 +24,19 @@ oauth_token_lacks_api_scope: status=403 login=alice
 
 **Symptom:** Tool calls return 403 with a message about re-authorizing.
 
-**Cause:** Same root cause as above — the OAuth token doesn't have the required Gitea API scopes. The middleware's API scope probe detected this and returned a clear error instead of letting it fail deep in the tool handler.
+**Cause:** The OAuth token does not have the required API scope in user-token mode, or the per-user repository permission check denied the request in service-PAT mode.
 
-**Fix:** Same as above — revoke and re-authorize.
+**Fix:** Revoke and re-authorize if the token lacks API scope. If the error mentions repository permission, grant the signed-in Gitea user the required repository access or use a repository they can access.
 
-## ChatGPT caches stale tokens
+## Claude caches stale tokens
 
-**Symptom:** After fixing the OAuth configuration, ChatGPT still sends the old token.
+**Symptom:** After fixing the OAuth configuration, Claude still sends the old token.
 
-**Cause:** ChatGPT caches access tokens and doesn't automatically re-authenticate when the server configuration changes.
+**Cause:** The client caches access tokens and doesn't automatically re-authenticate when the server configuration changes.
 
 **Fix:**
-1. In ChatGPT: **Settings > Connected apps** > disconnect the integration.
-2. Start a new conversation and use the integration again — this forces a fresh OAuth flow.
+1. Disconnect the server in the client.
+2. Start a new conversation and use the integration again - this forces a fresh OAuth flow.
 
 ## How OAuth scopes work with Gitea
 
@@ -48,9 +48,9 @@ Gitea's OAuth2/OIDC implementation uses **granular scopes** for API access:
 | `write:repository` | Create/edit issues, PRs, comments, files |
 | `openid` | OIDC identity (login, email) |
 
-When an OAuth application requests authorization, the `scope` parameter in the authorize URL determines what permissions the resulting token has. If only OIDC scopes are requested (e.g. `openid profile email`), the token will validate via the userinfo endpoint but will be rejected by Gitea's REST API with 403.
+When an OAuth application requests authorization, the `scope` parameter in the authorize URL determines what permissions the resulting token has. If only OIDC scopes are requested (e.g. `openid profile email`), the token can establish identity but may not be usable for direct Gitea REST calls. When `GITEA_TOKEN` is configured, the server uses OIDC for identity and checks the user's repository permission before using the service PAT.
 
-The MCP server's `openapi-gpt.yaml` file controls which scopes ChatGPT requests. Ensure it includes:
+The MCP server's OAuth metadata controls which scopes the client requests. Ensure it includes:
 ```yaml
 scopes:
   read:repository: "Read access to Gitea repositories"
@@ -73,3 +73,4 @@ Every authenticated request emits a structured log line:
 - `api_probe=fail:403` — token lacks API scopes, request rejected with re-auth guidance
 - `api_probe=skip:cached` — previous probe passed, cached result used
 - `api_probe=skip:error` — network error during probe, request allowed to proceed
+- `repository_permission_denied` in the audit log — the user lacks required read/write permission for a service-PAT call