diff --git a/.agent/workflows/gitbucket_api.md b/.agent/workflows/gitbucket_api.md
index 88872fc..0fa4d21 100644
--- a/.agent/workflows/gitbucket_api.md
+++ b/.agent/workflows/gitbucket_api.md
@@ -98,10 +98,10 @@
 ### 3. Orchestration Workflow
 - **List All**: `GET /api/v3/repos/owner/repo/issues` to see the current backlog.
 - **Detailed Context**: `GET .../issues/<ID>/comments` to read the history of an ongoing task.
-- **Finish**: Post a final summary comment and use the browser subagent to close the issue in the UI.
+- **Finish**: Post a final summary comment via API. **Note**: The GitBucket API often returns `404 Not Found` for `PATCH` requests on issues; therefore, you **MUST** use the `browser_subagent` to manually click "Close issue" in the UI to finalize the task.
 
 ### 4. UI-Only Actions (Browser Setup)
-For actions that the API cannot handle (like closing an issue in certain configurations), use the `browser_subagent`.
+Required when API limitations (like closing issues) prevent task completion.
 
 // turbo
 #### Establish Browser Bridge (Dev Container)