docs: add release fallback logic and troubleshooting section

Add ::warning:: annotation and fallback to fetch existing release
when tag already has a release. Add troubleshooting section for
re-triggering failed release workflows. Fix markdown lint warnings.

gitea-python-ci-cd.md

@@ -12,7 +12,7 @@ A reusable reference for building CI pipelines, release automation, and installe
 
 Two workflows, triggered by different events:
 
-```
+```text
 push/PR to master  ──►  test.yml   (lint + test)
 push tag v*        ──►  release.yml (build + release + Docker)
 ```
@@ -127,7 +127,14 @@ create-release:
             \"prerelease\": \$IS_PRE
           }")
 
+        # Fallback: if release already exists for this tag, fetch it instead
+        RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])" 2>/dev/null)
+        if [ -z "\$RELEASE_ID" ]; then
+          echo "::warning::Release already exists for tag \$TAG — reusing existing release"
+          RELEASE=$(curl -s "\$BASE_URL/releases/tags/\$TAG" \
+            -H "Authorization: token \$GITEA_TOKEN")
           RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+        fi
         echo "release_id=\$RELEASE_ID" >> "\$GITHUB_OUTPUT"
 ```
 
@@ -453,3 +460,28 @@ git push origin v0.2.0-alpha.1
 - [ ] Create `Dockerfile` for Docker builds (optional)
 - [ ] Configure `pyproject.toml` with `[tool.ruff]` and `[tool.pytest]`
 - [ ] Set up `.pre-commit-config.yaml` with ruff + black
+
+## 11. Troubleshooting
+
+### Release already exists for tag
+
+If the `create-release` job fails with `KeyError: 'id'`, the Gitea API returned an error
+because a release already exists for that tag (e.g., from a previous failed run).
+
+**Prevention:** The fallback logic in section 2.1 handles this automatically — if creation
+fails, it fetches the existing release by tag and reuses its ID. A `::warning::` annotation
+is emitted in the workflow log.
+
+**Re-triggering a failed release workflow:**
+
+```bash
+# Option A: Delete and re-push the same tag
+git push origin :refs/tags/v0.1.0-alpha.2   # delete remote tag
+# Delete the release in Gitea UI or via API
+git tag -f v0.1.0-alpha.2                    # recreate local tag
+git push origin v0.1.0-alpha.2               # push again
+
+# Option B: Just bump the version (simpler)
+git tag v0.1.0-alpha.3
+git push origin v0.1.0-alpha.3
+```