📖 docs: add comprehensive API discovery documentation to gitea-client

.vibe/skills/gitea-client/REFERENCE.md

@@ -299,10 +299,109 @@ All commands use the Gitea REST API v1:
 | `show-issue` | Show issue details | `gitea-client show-issue <owner> <repo> <issue_number>` |
 | `comment-issue` | Comment on issue | `gitea-client comment-issue <owner> <repo> <issue_number> <comment>` |
 
+## 🔍 Discovering Gitea API Endpoints
+
+### Using Swagger Documentation
+
+The Gitea API provides comprehensive Swagger/OpenAPI documentation that you can use to discover available endpoints:
+
+```bash
+# Fetch the complete Swagger JSON
+curl -s https://gitea.arcodange.lab/swagger.v1.json > gitea_api.json
+
+# List all available endpoints
+jq '.paths | keys' gitea_api.json
+
+# Find Actions/CI/CD related endpoints
+jq '.paths | with_entries(select(.key | contains("actions"))) | keys' gitea_api.json
+
+# Get details about a specific endpoint
+jq '.paths["/repos/{owner}/{repo}/actions/runs"]' gitea_api.json
+```
+
+### Exploring Actions API
+
+```bash
+# List all Actions-related endpoints
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths | with_entries(select(.key | contains("actions"))) | keys'
+
+# Check available methods for workflow runs endpoint
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths["/repos/{owner}/{repo}/actions/runs/{run}"] | keys'
+
+# Check available methods for jobs endpoint  
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths["/repos/{owner}/{repo}/actions/jobs/{job_id}"] | keys'
+```
+
+### Practical API Discovery Examples
+
+**Find all repository endpoints:**
+```bash
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths | with_entries(select(.key | startswith("/repos/"))) | keys | length'
+```
+
+**Find issue-related endpoints:**
+```bash
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths | with_entries(select(.key | contains("issues"))) | keys'
+```
+
+**Get endpoint parameters and responses:**
+```bash
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths["/repos/{owner}/{repo}/actions/runs"] | .get | {parameters, responses}'
+```
+
+### API Documentation Structure
+
+The Gitea Swagger documentation follows this structure:
+
+```json
+{
+  "paths": {
+    "/endpoint/path": {
+      "get": {
+        "tags": ["category"],
+        "summary": "Endpoint description",
+        "parameters": [...],
+        "responses": {...}
+      },
+      "post": {...},
+      "delete": {...}
+    }
+  },
+  "definitions": {...},
+  "responses": {...}
+}
+```
+
+### Common Endpoint Patterns
+
+- **Repository actions**: `/repos/{owner}/{repo}/actions/*`
+- **Organization actions**: `/orgs/{org}/actions/*`
+- **User actions**: `/user/actions/*`
+- **Admin actions**: `/admin/actions/*`
+
+### Discovering New Features
+
+When Gitea adds new features, check the Swagger documentation first:
+
+```bash
+# Compare with official Gitea documentation
+curl -s https://try.gitea.io/swagger.v1.json | \
+  jq '.paths | length'  # Official Gitea instance
+
+curl -s https://gitea.arcodange.lab/swagger.v1.json | \
+  jq '.paths | length'  # Your instance
+```
+
 ## 🎓 Learning Resources
 
 - **Gitea API Docs**: https://gitea.com/api/swagger
 - **GitHub Actions**: https://docs.github.com/en/actions
 - **JQ Tutorial**: https://stedolan.github.io/jq/manual/
 
-This reference guide provides comprehensive examples for using the gitea-client skill in real-world scenarios, covering job monitoring, PR management, and issue tracking with practical, copy-paste-ready examples.
+This reference guide provides comprehensive examples for using the gitea-client skill in real-world scenarios, covering job monitoring, PR management, issue tracking, and API discovery with practical, copy-paste-ready examples.

.vibe/skills/gitea-client/SKILL.md

@@ -32,8 +32,11 @@ Create a token in Gitea:
 
 ### API Documentation
 
-- Swagger: https://gitea.arcodange.lab/swagger.v1.json
-- Base URL: https://gitea.arcodange.lab
+- **Swagger JSON**: https://gitea.arcodange.lab/swagger.v1.json
+- **Base URL**: https://gitea.arcodange.lab
+- **Official Docs**: https://gitea.com/api/swagger
+
+**Tip:** See the [REFERENCE.md](#reference) for detailed guidance on discovering and exploring Gitea API endpoints using the Swagger documentation.
 
 ## Commands