ima-claude 2.10.0 → 2.13.0

package/plugins/ima-claude/skills/gh-cli/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: gh-cli
+description: >-
+  GitHub CLI (gh) for pull requests, issues, releases, Actions, code review, and repo
+  management. Primary tool for GitHub operations — reliable, fast, always available.
+  Use when: creating PRs, reviewing PRs, managing issues, checking CI status, creating
+  releases, searching GitHub, or any github.com operation. Triggers on: GitHub, gh,
+  pull request, PR, issue, release, actions, workflow, CI status, code review, merge PR.
+  NOT for Gitea — use mcp-gitea for internal repos.
+---
+
+# GitHub CLI (`gh`) — GitHub Operations
+
+The `gh` CLI is the primary tool for all GitHub operations. It's authenticated, reliable, and covers the full GitHub API surface.
+
+## Prerequisites
+
+```bash
+# Verify authentication
+gh auth status
+```
+
+The CLI must be authenticated (`gh auth login`) before use. Verify scopes with `gh auth status`.
+
+## Command Reference
+
+### Pull Requests
+
+| Operation | Command |
+|-----------|---------|
+| Create PR | `gh pr create --title "..." --body "..." --base main` |
+| Create PR (fill from commits) | `gh pr create --fill` |
+| Create draft PR | `gh pr create --draft --title "..." --body "..."` |
+| List open PRs | `gh pr list` |
+| List PRs by state | `gh pr list --state closed` |
+| List PRs by author | `gh pr list --author "@me"` |
+| List PRs by label | `gh pr list --label "bug"` |
+| View PR details | `gh pr view 123` |
+| View PR in browser | `gh pr view 123 --web` |
+| View PR diff | `gh pr diff 123` |
+| Check CI status | `gh pr checks 123` |
+| Checkout PR locally | `gh pr checkout 123` |
+| Merge PR (squash) | `gh pr merge 123 --squash` |
+| Merge PR (rebase) | `gh pr merge 123 --rebase` |
+| Merge PR (merge commit) | `gh pr merge 123 --merge` |
+| Merge + delete branch | `gh pr merge 123 --squash --delete-branch` |
+| Close PR | `gh pr close 123` |
+| Reopen PR | `gh pr reopen 123` |
+| Edit PR | `gh pr edit 123 --title "..." --body "..."` |
+| Add reviewer | `gh pr edit 123 --add-reviewer username` |
+| Add label | `gh pr edit 123 --add-label "bug"` |
+| Mark as ready | `gh pr ready 123` |
+| Comment on PR | `gh pr comment 123 --body "..."` |
+| Review PR (approve) | `gh pr review 123 --approve --body "LGTM"` |
+| Review PR (request changes) | `gh pr review 123 --request-changes --body "..."` |
+| Review PR (comment only) | `gh pr review 123 --comment --body "..."` |
+| My PR status | `gh pr status` |
+
+### Issues
+
+| Operation | Command |
+|-----------|---------|
+| Create issue | `gh issue create --title "..." --body "..."` |
+| Create issue with labels | `gh issue create --title "..." --label "bug" --label "priority"` |
+| Create issue with assignee | `gh issue create --title "..." --assignee "@me"` |
+| List open issues | `gh issue list` |
+| List by state | `gh issue list --state closed` |
+| List by label | `gh issue list --label "bug"` |
+| List by assignee | `gh issue list --assignee "@me"` |
+| View issue | `gh issue view 42` |
+| View in browser | `gh issue view 42 --web` |
+| Close issue | `gh issue close 42` |
+| Close with comment | `gh issue close 42 --comment "Fixed in v2.11.0"` |
+| Reopen issue | `gh issue reopen 42` |
+| Comment on issue | `gh issue comment 42 --body "..."` |
+| Edit issue | `gh issue edit 42 --title "..." --body "..."` |
+| Add label | `gh issue edit 42 --add-label "in-progress"` |
+| Remove label | `gh issue edit 42 --remove-label "triage"` |
+| Assign | `gh issue edit 42 --add-assignee username` |
+| Pin issue | `gh issue pin 42` |
+| Transfer issue | `gh issue transfer 42 owner/other-repo` |
+| My issue status | `gh issue status` |
+
+### Repositories
+
+| Operation | Command |
+|-----------|---------|
+| View repo | `gh repo view owner/name` |
+| View in browser | `gh repo view --web` |
+| Clone repo | `gh repo clone owner/name` |
+| Fork repo | `gh repo fork owner/name` |
+| Create repo | `gh repo create name --public --description "..."` |
+| Create private repo | `gh repo create name --private` |
+| List my repos | `gh repo list` |
+| List org repos | `gh repo list org-name` |
+| Sync fork | `gh repo sync owner/name` |
+| Set default repo | `gh repo set-default owner/name` |
+
+### Releases & Tags
+
+| Operation | Command |
+|-----------|---------|
+| Create release | `gh release create v1.0.0 --title "v1.0.0" --notes "..."` |
+| Create draft release | `gh release create v1.0.0 --draft --title "v1.0.0" --notes "..."` |
+| Create release from tag | `gh release create v1.0.0 --generate-notes` |
+| Upload assets | `gh release upload v1.0.0 ./dist/*.tar.gz` |
+| List releases | `gh release list` |
+| View release | `gh release view v1.0.0` |
+| Download assets | `gh release download v1.0.0` |
+| Delete release | `gh release delete v1.0.0` |
+| Edit release | `gh release edit v1.0.0 --title "..." --notes "..."` |
+
+### GitHub Actions (Workflows & Runs)
+
+| Operation | Command |
+|-----------|---------|
+| List workflows | `gh workflow list` |
+| View workflow | `gh workflow view workflow-name` |
+| Run workflow | `gh workflow run workflow-name` |
+| Run with inputs | `gh workflow run workflow-name -f key=value` |
+| Disable workflow | `gh workflow disable workflow-name` |
+| Enable workflow | `gh workflow enable workflow-name` |
+| List recent runs | `gh run list` |
+| List runs for workflow | `gh run list --workflow workflow-name` |
+| View run details | `gh run view 12345` |
+| View run logs | `gh run view 12345 --log` |
+| Watch run progress | `gh run watch 12345` |
+| Download artifacts | `gh run download 12345` |
+| Rerun failed jobs | `gh run rerun 12345 --failed` |
+| Cancel run | `gh run cancel 12345` |
+
+### Search (Cross-Repository)
+
+| Operation | Command |
+|-----------|---------|
+| Search repos | `gh search repos "query" --sort stars` |
+| Search issues | `gh search issues "query" --repo owner/name` |
+| Search PRs | `gh search prs "query" --state open` |
+| Search code | `gh search code "pattern" --repo owner/name` |
+| Search commits | `gh search commits "query" --repo owner/name` |
+
+### Labels
+
+| Operation | Command |
+|-----------|---------|
+| List labels | `gh label list` |
+| Create label | `gh label create "name" --color "0075ca" --description "..."` |
+| Edit label | `gh label edit "name" --new-name "..." --color "..."` |
+| Delete label | `gh label delete "name" --yes` |
+| Clone labels to another repo | `gh label clone source-owner/source-repo` |
+
+### Raw API Access
+
+For operations not covered by built-in commands:
+
+```bash
+# GET request
+gh api repos/{owner}/{repo}/topics
+
+# POST request
+gh api repos/{owner}/{repo}/labels -f name="priority" -f color="ff0000"
+
+# With pagination
+gh api repos/{owner}/{repo}/issues --paginate
+
+# GraphQL
+gh api graphql -f query='{ viewer { login } }'
+
+# JSON output + jq filtering
+gh api repos/{owner}/{repo}/pulls --jq '.[].title'
+```
+
+## Decision Logic
+
+```
+Is this a GitHub-hosted repo?
+  Check: git remote -v → shows github.com
+  → Yes: Use gh CLI (this skill)
+  → No: Is it Gitea-hosted?
+      → Yes: Use mcp-gitea tools (see mcp-gitea skill)
+      → Unknown: Ask the user
+
+For local-only git operations (commit, diff, log, stash, rebase):
+  → Always use git CLI directly — gh is for GitHub API operations
+
+Operation routing:
+  PRs (create, review, merge, list)  → gh pr ...
+  Issues (create, comment, close)    → gh issue ...
+  Releases (create, upload, list)    → gh release ...
+  CI/CD status, rerun, logs          → gh run ... / gh workflow ...
+  Search across GitHub               → gh search ...
+  Anything not in built-in commands  → gh api ...
+```
+
+## Common Workflows
+
+### Create a PR with Body via HEREDOC
+
+```bash
+gh pr create --title "feat: add gh-cli skill" --body "$(cat <<'EOF'
+## Summary
+- Added gh-cli skill for GitHub CLI operations
+- Replaces unreliable MCP GitHub integration
+
+## Test plan
+- [ ] Verify gh auth status
+- [ ] Test PR creation workflow
+EOF
+)"
+```
+
+### Check CI and Merge When Ready
+
+```bash
+# Check CI status
+gh pr checks 123
+
+# If all checks pass, merge
+gh pr merge 123 --squash --delete-branch
+```
+
+### Create a Release with Changelog
+
+```bash
+gh release create v2.12.0 \
+  --title "v2.12.0 — Add gh-cli skill" \
+  --generate-notes \
+  --latest
+```
+
+### Cross-Repo Issue Search
+
+```bash
+# Find all open bugs assigned to me across repos
+gh search issues "is:open assignee:@me label:bug" --limit 20
+
+# Find PRs awaiting my review
+gh search prs "is:open review-requested:@me" --limit 20
+```
+
+### View PR Comments (API)
+
+```bash
+# List PR review comments
+gh api repos/{owner}/{repo}/pulls/123/comments --jq '.[].body'
+
+# List issue/PR timeline comments
+gh api repos/{owner}/{repo}/issues/123/comments --jq '.[] | "\(.user.login): \(.body)"'
+```
+
+## Output Formatting
+
+The `gh` CLI supports structured output:
+
+```bash
+# JSON output
+gh pr list --json number,title,state
+
+# JSON + jq filter
+gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'
+
+# Table format (default for list commands)
+gh issue list
+
+# Web browser
+gh pr view 123 --web
+```
+
+## Cross-Repository Operations
+
+Use `--repo` or `-R` to target any GitHub repo:
+
+```bash
+gh pr list -R owner/other-repo
+gh issue create -R owner/other-repo --title "..."
+gh run list -R owner/other-repo
+```
+
+## When NOT to Use
+
+| Situation | Use Instead |
+|-----------|-------------|
+| Gitea-hosted repos | `mcp-gitea` tools |
+| Local git operations (commit, diff, stash) | `git` CLI directly |
+| Reading local files | Read tool |
+| Pushing/pulling code | `git push` / `git pull` |

package/plugins/ima-claude/skills/mcp-gitea/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: mcp-gitea
+description: >-
+  Gitea MCP for internal Git repository management — pull requests, issues, releases,
+  branches, tags, wikis, and CI/CD actions. Use when: creating/reviewing PRs, managing
+  issues, creating releases/tags, browsing repo contents, managing branches, wiki
+  operations, or any Gitea-hosted repository operation. Triggers on: Gitea, internal
+  repo, pull request, PR review, merge request, release, tag, branch, issue, milestone,
+  wiki, actions, CI/CD, timetracking. NOT for GitHub repos — use mcp-github for those.
+---
+
+# Gitea MCP - Internal Git Repository Management
+
+The team's internal Git platform. All tools prefixed `mcp__gitea__`.
+
+Gitea is the **primary** tool for daily development work (PRs, issues, releases).
+GitHub is FOSS publishing only — use `mcp-github` for GitHub operations.
+The `gh` CLI is GitHub-only; it does not work with Gitea.
+
+**Method-dispatch pattern:** Several tools (`pull_request_read`, `pull_request_write`, `pull_request_review_write`, `issue_read`, `issue_write`) use a required `method` parameter to select the operation. Always include `method` — omitting it causes a missing parameter error.
+
+## Tool Catalog
+
+### Identity & Discovery
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `get_me` | Current authenticated user | *(none)* |
+| `get_user_orgs` | User's organizations | *(none)* |
+| `search_users` | Search users by name/email | `query` |
+| `search_repos` | Search repositories across Gitea | `query`, `owner` |
+| `search_org_teams` | Find teams within an org | `org`, `query` |
+| `list_my_repos` | List authenticated user's repos | `page`, `perPage` |
+| `get_gitea_mcp_server_version` | Server version info | *(none)* |
+
+### Repository Operations
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `create_repo` | Create a new repository | `owner`, `name`, `description`, `private` |
+| `fork_repo` | Fork an existing repository | `owner`, `repo`, `organization` |
+| `get_file_contents` | Get file contents at a path | `owner`, `repo`, `filepath`, `ref` |
+| `get_dir_contents` | List directory contents | `owner`, `repo`, `filepath`, `ref` |
+| `create_or_update_file` | Create or update a file | `owner`, `repo`, `filepath`, `content`, `message`, `sha` (required for updates) |
+| `delete_file` | Delete a file | `owner`, `repo`, `filepath`, `message`, `sha` |
+
+### Branches
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `list_branches` | List all branches | `owner`, `repo`, `page`, `perPage` |
+| `create_branch` | Create a new branch | `owner`, `repo`, `new_branch_name`, `old_branch_name` |
+| `delete_branch` | Delete a branch | `owner`, `repo`, `branch` |
+
+### Pull Requests
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `list_pull_requests` | List PRs with filtering | `owner`, `repo`, `state` (open/closed/all), `sort`, `milestone`, `page`, `perPage` |
+| `pull_request_read` | Read PR data and reviews | `method` (get/get_diff/get_reviews/get_review/get_review_comments), `owner`, `repo`, `index`; `review_id` for get_review/get_review_comments |
+| `pull_request_write` | Create, update, merge PR; manage reviewers | `method` (create/update/merge/add_reviewers/remove_reviewers), `owner`, `repo`; `index` required except for create |
+| `pull_request_review_write` | Submit, delete, or dismiss a PR review | `method` (create/submit/delete/dismiss), `owner`, `repo`, `index`; `review_id` required for submit/delete/dismiss |
+
+**`pull_request_write` method details:**
+- `create`: `title` (req), `head` (req), `base` (req), `body`
+- `update`: `index` (req), `title`, `body`, `state`, `assignee`, `assignees`, `milestone`, `base`, `allow_maintainer_edit`
+- `merge`: `index` (req), `merge_style` (merge/rebase/rebase-merge/squash/fast-forward-only), `message`, `delete_branch`, `title`
+- `add_reviewers` / `remove_reviewers`: `index` (req), `reviewers` (string[]), `team_reviewers` (string[])
+
+**`pull_request_review_write` method details:**
+- `create`: `body`, `commit_id`, `comments` (inline array with `path`, `body`, `old_line_num`, `new_line_num`), `state`
+- `submit`: `review_id` (req), `body`, `state` (APPROVED/REQUEST_CHANGES/COMMENT/PENDING)
+- `delete`: `review_id` (req)
+- `dismiss`: `review_id` (req), `message`
+
+### Issues
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `list_issues` | List issues with filtering | `owner`, `repo`, `state` (default "all"), `page`, `perPage` |
+| `issue_read` | Get issue details, comments, or labels | `method` (get/get_comments/get_labels), `owner`, `repo`, `index` |
+| `issue_write` | Create, update, comment, or manage labels | `method` (create/update/add_comment/edit_comment/add_labels/remove_label/replace_labels/clear_labels), `owner`, `repo`; `index` required except for create |
+
+**`issue_write` method details:**
+- `create`: `title` (req), `body`, `assignees`, `labels` (number[]), `milestone`
+- `update`: `index` (req), `title`, `body`, `state`, `assignees`, `milestone`
+- `add_comment`: `index` (req), `body` (req)
+- `edit_comment`: `index` (req), `commentID` (req), `body` (req)
+- `add_labels` / `replace_labels`: `index` (req), `labels` (number[])
+- `remove_label`: `index` (req), `label_id` (number)
+- `clear_labels`: `index` (req)
+
+### Labels
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `label_read` | Get label details | `owner`, `repo`, `id` |
+| `label_write` | Create or update a label | `owner`, `repo`, `name`, `color` |
+
+### Milestones
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `milestone_read` | Get milestone details | `owner`, `repo`, `id` |
+| `milestone_write` | Create or update a milestone | `owner`, `repo`, `title`, `due_on`, `description` |
+
+### Releases & Tags
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `list_releases` | List all releases | `owner`, `repo`, `page`, `perPage` |
+| `get_release` | Get release by ID | `owner`, `repo`, `id` |
+| `get_latest_release` | Get the latest published release | `owner`, `repo` |
+| `create_release` | Create a new release | `owner`, `repo`, `tag_name`, `name`, `body`, `draft`, `prerelease` |
+| `delete_release` | Delete a release | `owner`, `repo`, `id` |
+| `list_tags` | List all tags | `owner`, `repo`, `page`, `perPage` |
+| `get_tag` | Get tag by name | `owner`, `repo`, `tag` |
+| `create_tag` | Create a new tag | `owner`, `repo`, `tag_name`, `message`, `target` |
+| `delete_tag` | Delete a tag | `owner`, `repo`, `tag` |
+
+### Commits
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `list_commits` | List commits on a branch | `owner`, `repo`, `sha`, `path`, `page`, `perPage` |
+
+### Wiki
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `wiki_read` | Read a wiki page | `owner`, `repo`, `pageName` |
+| `wiki_write` | Create or update a wiki page | `owner`, `repo`, `pageName`, `content`, `message` |
+
+### CI/CD Actions
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `actions_config_read` | Read workflow/actions config | `owner`, `repo` |
+| `actions_config_write` | Write workflow/actions config | `owner`, `repo`, `config` |
+| `actions_run_read` | Read action run details/logs | `owner`, `repo`, `run_id` |
+| `actions_run_write` | Trigger or manage action runs | `owner`, `repo`, `workflow_id`, `ref` |
+
+### Time Tracking
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `timetracking_read` | Read time entries on an issue | `owner`, `repo`, `index` |
+| `timetracking_write` | Log time on an issue | `owner`, `repo`, `index`, `time` (seconds) |
+
+## Common Workflows
+
+### Create a Pull Request
+
+```
+1. Ensure your feature branch is pushed:
+   git push origin feature/my-branch
+
+2. pull_request_write(
+     method: "create",
+     owner: "FLCCC",
+     repo: "my-repo",
+     title: "feat: add new feature",
+     body: "## Summary\n- What changed\n- Why it changed\n\n## Test plan\n- [ ] Tested locally",
+     head: "feature/my-branch",
+     base: "main"
+   )
+```
+
+### Review a Pull Request
+
+```
+1. pull_request_read(method: "get", owner: "FLCCC", repo: "my-repo", index: 42)
+   → Review title, description, and diff summary
+
+2. pull_request_read(method: "get_reviews", owner: "FLCCC", repo: "my-repo", index: 42)
+   → Check existing reviews
+
+3. pull_request_review_write(
+     method: "create",
+     owner: "FLCCC",
+     repo: "my-repo",
+     index: 42,
+     state: "APPROVED",
+     body: "LGTM — clean implementation, tests look solid"
+   )
+   → Then submit it:
+   pull_request_review_write(
+     method: "submit",
+     owner: "FLCCC",
+     repo: "my-repo",
+     index: 42,
+     review_id: <id from create response>,
+     state: "APPROVED"
+   )
+```
+
+### Merge a Pull Request
+
+```
+pull_request_write(
+  method: "merge",
+  owner: "FLCCC",
+  repo: "my-repo",
+  index: 42,
+  merge_style: "squash",
+  delete_branch: true
+)
+```
+
+### Create a Release
+
+```
+1. get_latest_release(owner: "FLCCC", repo: "my-repo")
+   → Note current version for bump reference
+
+2. create_tag(
+     owner: "FLCCC",
+     repo: "my-repo",
+     tag_name: "v2.1.0",
+     message: "Release v2.1.0",
+     target: "main"
+   )
+
+3. create_release(
+     owner: "FLCCC",
+     repo: "my-repo",
+     tag_name: "v2.1.0",
+     name: "v2.1.0 — Feature Name",
+     body: "## Changes\n- ...\n\n## Breaking Changes\n- none",
+     draft: false,
+     prerelease: false
+   )
+```
+
+### Manage Issues
+
+```
+# Create an issue
+issue_write(
+  method: "create",
+  owner: "FLCCC",
+  repo: "my-repo",
+  title: "Bug: description of problem",
+  body: "## Steps to reproduce\n1. ...\n\n## Expected\n...\n\n## Actual\n..."
+)
+
+# Update an existing issue
+issue_write(
+  method: "update",
+  owner: "FLCCC",
+  repo: "my-repo",
+  index: 15,
+  body: "<updated body>"
+)
+
+# Add a comment
+issue_write(
+  method: "add_comment",
+  owner: "FLCCC",
+  repo: "my-repo",
+  index: 15,
+  body: "Confirmed — reproduced on v2.9.1."
+)
+
+# Filter open issues
+list_issues(
+  owner: "FLCCC",
+  repo: "my-repo",
+  state: "open",
+  perPage: 20
+)
+```
+
+### Browse Repo Contents
+
+```
+# List files in a directory
+get_dir_contents(owner: "FLCCC", repo: "my-repo", filepath: "src/", ref: "main")
+
+# Read a specific file
+get_file_contents(owner: "FLCCC", repo: "my-repo", filepath: "package.json", ref: "main")
+```
+
+## Decision Logic
+
+```
+Is this a Gitea-hosted repo?
+(check: git remote -v shows gitea.* or internal hostname)
+  → Yes: Use mcp__gitea__* tools  ← PRIMARY for daily work
+
+  → No: Is it GitHub-hosted? (github.com in remote URL)
+      → Yes: Use mcp__github__* tools (see mcp-github skill)
+             or gh CLI for GitHub-specific operations
+
+For local-only git operations (commit, diff, log, stash, rebase):
+  → Always use git CLI directly — no MCP needed for local ops
+
+Operation decision tree:
+  Creating a PR                → pull_request_write(method: "create")
+  Reading PR details/diff      → pull_request_read(method: "get" | "get_diff")
+  Reviewing a PR               → pull_request_review_write(method: "create" then "submit")
+  Merging a PR                 → pull_request_write(method: "merge")
+  Issue triage/tracking        → issue_write(method: "create" | "update") / list_issues
+  Adding a comment             → issue_write(method: "add_comment")
+  Cutting a release            → create_tag → create_release
+  Browsing file contents       → get_file_contents / get_dir_contents
+  Editing a file via MCP       → create_or_update_file (need sha for updates)
+  Branch management            → create_branch / delete_branch
+  CI/CD pipeline status        → actions_run_read
+  Team documentation           → wiki_write / wiki_read
+  Time logging                 → timetracking_write
+```
+
+## Token-Saving Strategies
+
+### 1. Paginate Large Lists
+
+```
+list_issues(owner: "FLCCC", repo: "my-repo", perPage: 15, page: 1)
+# Default can return 30+ items. Set perPage to what you actually need.
+```
+
+### 2. Filter by State
+
+```
+list_pull_requests(owner: "FLCCC", repo: "my-repo", state: "open")    # "open" | "closed" | "all"
+list_issues(owner: "FLCCC", repo: "my-repo", state: "open")           # Skip closed unless historical review
+```
+
+### 3. Target Specific Refs
+
+```
+get_file_contents(ref: "main")                              # Avoid default branch ambiguity
+list_commits(sha: "feature-branch", perPage: 10, page: 1)  # Last 10 commits only
+```
+
+### 4. Avoid Redundant Discovery
+
+Cache within a session (these don't change):
+- Owner/org names from `get_me` or `get_user_orgs`
+- Repo names once confirmed via `search_repos`
+- Label IDs once fetched via `label_read`
+- Milestone IDs once fetched via `milestone_read`
+
+### 5. Read Before Write (Files)
+
+`create_or_update_file` requires the current file `sha` for updates. Always call
+`get_file_contents` first to extract the `sha` — skipping this causes a 409 conflict error.
+
+## When NOT to Use Gitea MCP
+
+| Situation | Use Instead |
+|-----------|-------------|
+| GitHub-hosted repo (github.com) | `mcp__github__*` tools or `gh` CLI |
+| Local git operations (commit, diff, stash, rebase, cherry-pick) | `git` CLI directly |
+| Pushing/pulling code | `git push` / `git pull` (git CLI) |
+| GitHub Actions (github.com CI) | `gh` CLI |
+| Cloning a repo | `git clone` (git CLI) |