Compress agent skills

gitea-transfer/references/failure-modes.md

@@ -0,0 +1,47 @@
+# Common Gitea Transfer Failure Modes
+
+## Dot Paths 403 In Gitea UI
+
+Cause: reverse proxy blocks dot directories.
+
+Fix: adjust the proxy rule for Gitea. Do not rename workflow directories.
+
+## Postgres Connection Refused
+
+Cause: CI app connects to `127.0.0.1` while Postgres runs as a service container.
+
+Fix: use service hostname such as `postgres` and add readiness checks.
+
+## Runner Job Never Starts
+
+Cause: workflow `runs-on` label does not match registered runner labels.
+
+Fix: use generic labels and verify with `tea api admin/actions/runners`.
+
+## Image Pull Fails
+
+Cause: wrong registry hostname, missing Docker daemon trust, or private package auth issue.
+
+Fix: verify image reference by pulling on the runner host, then use the same host/port in the workflow.
+
+## Deploy Fails For Missing Secrets
+
+Cause: Gitea Actions secrets are not configured yet.
+
+Fix: add a preflight skip or configure secrets. File follow-up work instead of leaving the default branch red.
+
+## OpenCode Review Has No Context
+
+Cause: workflow passed only a diff and did not checkout the PR head tree.
+
+Fix: fetch the PR diff through the Gitea API, then shallow-checkout the PR head SHA with `fetch-depth: 1` and `persist-credentials: false`.
+
+## Branch Tracks Old GitHub Remote
+
+Cause: local branch upstream still points to `github/{branch}` after remote cutover.
+
+Fix only if requested or useful:
+
+```bash
+git branch --set-upstream-to=origin/{branch} {branch}
+```