Compress agent skills

gitea-transfer/references/deploy-porting.md

@@ -0,0 +1,28 @@
+# Deploy Workflow Porting
+
+Port deploy workflows after tests pass. Deploys often need secrets and remote side effects.
+
+Guard required secrets explicitly and skip deploy-only steps when secrets are absent so the default branch remains green while configuration is pending.
+
+```bash
+missing=()
+
+for required_var in SPARK_EMAIL SPARK_KEY TIPTAP_PRO_KEY DO_SPACES_KEY DO_SPACES_SECRET DO_SPACES_ENDPOINT DO_SPACES_REGION; do
+  if [ -z "${!required_var}" ]; then
+    missing+=("$required_var")
+  fi
+done
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  echo "Skipping deploy because required secrets are missing: ${missing[*]}"
+  echo "SKIP_DEPLOY=true" >> "$GITHUB_ENV"
+fi
+```
+
+Gate deploy steps:
+
+```yaml
+if: env.SKIP_DEPLOY != 'true'
+```
+
+File follow-up work for missing secrets. Do not manually dispatch deploy workflows that upload assets or mutate production unless the user explicitly approves.

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}
+```

gitea-transfer/references/opencode-review.md

@@ -0,0 +1,41 @@
+# OpenCode PR Review Workflow
+
+Use this pattern when adding a repo-scoped OpenCode reviewer to Gitea Actions.
+
+Core behavior:
+
+- Trigger only from PR comments containing `/review` and optional `workflow_dispatch`.
+- Do not auto-review on PR open or synchronize for the first version.
+- Run OpenCode read-only.
+- Post or update one aggregate PR comment using a stable marker such as `<!-- opencode-review -->`.
+- Checkout the PR head tree shallowly for repository context.
+- Do not expose Gitea API tokens to OpenCode.
+
+Required secrets:
+
+- `REVIEW_BOT_TOKEN`: Gitea token with `read:repository`, `read:issue`, and `write:issue`.
+- `OPENCODE_GO_TOKEN`: OpenCode Go API token.
+
+Preparation step should:
+
+- Read `$GITHUB_EVENT_PATH` with `jq`.
+- Skip unless action is `created`, issue is a PR, and comment contains `/review`.
+- Fetch PR metadata from `GET /repos/{owner}/{repo}/pulls/{number}`.
+- Fetch diff from `GET /repos/{owner}/{repo}/pulls/{number}.diff`.
+- Export `PR_NUMBER`, `REPO`, `BASE_BRANCH`, `HEAD_BRANCH`, and `HEAD_SHA`.
+
+Checkout pattern:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    ref: ${{ env.HEAD_SHA }}
+    fetch-depth: 1
+    persist-credentials: false
+```
+
+Avoid `fetch-depth: 0` unless full history is required.
+
+Before invoking OpenCode, generate auth from `OPENCODE_GO_TOKEN`, disable mutation tools, and unset repository tokens from the environment.
+
+Gitea Actions logs can be awkward before Gitea 1.26; if `tea actions runs logs` is unavailable or incomplete, inspect run/task state through the Gitea API.

gitea-transfer/references/runner-images.md

@@ -0,0 +1,47 @@
+# Gitea Runner Images
+
+Prefer job containers over custom runner labels for language/runtime selection. Labels select eligible runners; containers select runtime images.
+
+Use generic runner labels such as `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04`. Verify actual runner labels with:
+
+```bash
+tea api admin/actions/runners
+```
+
+Shared PHP/Laravel image family:
+
+```text
+git.bayliss.cloud/harry/gitea-ci-runner:php8.2
+git.bayliss.cloud/harry/gitea-ci-runner:php8.3
+git.bayliss.cloud/harry/gitea-ci-runner:php8.4
+git.bayliss.cloud/harry/gitea-ci-runner:php8.5
+git.bayliss.cloud/harry/gitea-ci-runner:latest
+```
+
+`latest` points to PHP 8.5. Repositories should usually pin the PHP tag they require.
+
+```yaml
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    container:
+      image: git.bayliss.cloud/harry/gitea-ci-runner:php8.2
+```
+
+Shared image repository:
+
+```text
+ssh://git@git.bayliss.cloud:30009/harry/gitea-ci-runner.git
+https://git.bayliss.cloud/harry/gitea-ci-runner
+```
+
+Current shared image contents include PHP CLI, Composer 2, Bun, Node.js/npm/npx, Go, Python/pip/venv, `jq`, database/cache clients, and common PHP extensions. Do not add MongoDB unless a repository has a real CI/runtime need.
+
+If the runner host exposes the registry locally, job containers may use the runner-local endpoint for faster pulls:
+
+```yaml
+container:
+  image: localhost:30008/harry/gitea-ci-runner:php8.2
+```
+
+Do not include `http://` in Docker image references. Configure insecure/local registry trust at the Docker daemon level if needed.