docs(gitea): backfill external workflow-convention research via context7

Existing gitea research docs were 100% code-derived from gitea-mcp
source with zero external content (the original docs.gitea.com fetch
timed out and was never retried). Adds workflow-conventions.md sourced
from context7 /websites/gitea and /git_gitea_com/gitea_tea: scoped/
exclusive label conventions, PR review/branch-protection rules,
release/tag semver conventions, and automatic issue/PR cross-reference
linking (validates the dependency-linking convention for issue #6).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

plugins/gitea/docs/research/docs/gitea/sources.md

@@ -20,3 +20,17 @@
 - **Description:** Gitea REST API swagger documentation covering underlying endpoints for issues, PRs, labels, milestones, and branches
 - **Contributing files:** (see notes below)
 - **Status:** `no content extracted` — source fetch timed out; all reference content derived from gitea-mcp source files which are authoritative for MCP tool usage
+
+## context7-websites-gitea
+
+- **URL:** context7:/websites/gitea
+- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions, branch protection and PR review/merge rules, release and webhook semantics, issue/PR automatic cross-reference linking. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout.
+- **Contributing files:** workflow-conventions.md
+- **Status:** `extracted`
+
+## context7-gitea-tea-cli
+
+- **URL:** context7:/git_gitea_com/gitea_tea
+- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for issues, PRs, and releases, including semver tag/release conventions, draft/prerelease flags, and release-notes-from-file conventions.
+- **Contributing files:** workflow-conventions.md
+- **Status:** `extracted`

plugins/gitea/docs/research/docs/gitea/workflow-conventions.md

@@ -0,0 +1,88 @@
+---
+topic: workflow-conventions
+source_keys:
+  - context7-websites-gitea
+  - context7-gitea-tea-cli
+---
+
+# Gitea Workflow Conventions
+
+Practitioner conventions and platform behavior that inform *how* to use the mechanics already
+documented in `api-reference.md` — not additional tool schemas.
+
+## Scoped, exclusive labels
+
+Gitea labels support a scoped-label convention: a `/` delimiter in the label name (e.g.
+`Priority/High`) plus an `exclusive: true` flag means only one label from that scope can be applied
+to an issue or PR at a time — applying a new `Priority/*` label automatically replaces the previous
+one. This is exactly the `Kind/*` / `Priority/*` / `Status/*` taxonomy already used in this repo's
+own label set, confirming the taxonomy follows Gitea's native scoped-label convention rather than an
+ad hoc naming scheme. When defining or inferring labels, a scope prefix implies mutual exclusivity —
+label inference logic should replace, not add to, existing labels in the same scope.
+
+Repositories can also seed a predefined label set at creation time from a YAML label file
+(`name`, `color`, `description`, `exclusive`), which is where the base `Kind/Priority/Status` sets
+typically originate.
+
+## Milestone and label state as first-class transitions
+
+Both issues and PRs treat labeling and milestoning as discrete state-transition events
+(`label_updated`/`label_cleared`, `milestoned`/`demilestoned`), not passive metadata fields. This
+reinforces treating `gitea-labels-milestones` as a shared skill: the same transition semantics apply
+whether the target is an issue or a PR.
+
+## Automatic cross-reference linking
+
+Gitea auto-renders issue/PR references in body text without any API call: `#1234` and `!1234` both
+resolve to issue/PR 1234 in the same repo (issues and PRs share one number space, consistent with
+`data-model.md`); cross-repo references use `owner/repo#1234` (issue) or `owner/repo!1234` (PR). This
+directly validates the dependency-linking convention decided for `gitea-issues` (issue #6, comment
+#848): writing `Depends on #N` in an issue body is not just a text convention — Gitea renders it as
+a real clickable cross-reference automatically, with no separate API call required. For
+external-issue-tracker repos, the same syntax renders as an external link instead, so the skill
+should assume same-repo internal linking unless told otherwise.
+
+## Pull request review workflow
+
+The reviewer flow is: comment, request changes, or approve; the author pushes updates to the same
+branch, which the PR auto-tracks; maintainers merge once approved. Protected branches can layer
+additional constraints on top of this base flow:
+
+- An allowlist of users/teams may be required to approve before merge is possible.
+- A minimum approval count can be enforced.
+- Stale approvals (approvals given before new commits were pushed) can be auto-dismissed or ignored.
+- Merge can be blocked if any review requests changes, if requested reviewers haven't reviewed yet,
+  or if the branch is outdated relative to its base.
+- Repository admins are not exempt from these rules by default — an explicit
+  "administrators must follow branch protection rules" setting is what removes their force-merge
+  bypass.
+
+A skill that merges PRs should treat "CI passing" and "reviews satisfied" as two independently
+checkable gates — `get_status` covers CI, but review/approval state and branch-protection
+constraints are a separate check the merge call itself will enforce server-side and return as an
+error if unmet.
+
+## Release and tag conventions
+
+Releases are conceptually separate from tags but always tied to one: a release wraps a tag with a
+title, notes, and optional binary assets. Practitioner convention (per the `tea` CLI, the reference
+Gitea client) is:
+
+- Tag names are semver-style, typically `v`-prefixed (`v1.2.0`, `v2.0.0-beta.1`).
+- Release notes are commonly sourced from a changelog file rather than typed inline.
+- Draft and prerelease are separate boolean flags, not states inferred from the tag name — a
+  prerelease is anything with a `-beta`/`-rc` style suffix by convention, but Gitea does not enforce
+  this; the skill should treat `draft`/`prerelease` as flags the caller sets explicitly rather than
+  something to infer from the tag string.
+- Deleting a release does not delete its tag by default — the two are separate destructive
+  operations (confirmed by `delete_release` taking a numeric release ID per `troubleshooting.md`,
+  distinct from `delete_tag`).
+
+## File editing: direct commit vs. PR
+
+Gitea's own UI defaults to prompting for a target branch when creating/editing a file directly
+through the web interface, and supports pre-filling a new file's path and content via query
+parameters — reflecting that direct-commit file edits are a first-class, expected workflow (not just
+an API escape hatch). This supports `create_or_update_file`/`delete_file` being used directly against
+a working branch as a normal editing action, with the SHA-currency requirement (`troubleshooting.md`)
+being the main gotcha rather than direct-commit being an anti-pattern to avoid.