refactor: Replace GitHub Actions mirroring with Gitea native pull mirror

- Remove sync-to-gitea.yml and mirror-check.yml GitHub Actions workflows
- Set up Gitea as pull mirror from GitHub (1h interval, via POST /repos/migrate)
- Rewrite MIRRORING-GUIDE.md with pull mirror setup and gotchas
- Update HANDOVER.md and lessons-learned.md with new approach

Gitea now automatically pulls from GitHub. No Actions, no dual-push,
no billing dependency. Push to GitHub only; Gitea syncs within 1 hour.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lessons-learned.md

@@ -107,4 +107,56 @@
 
 2. **Verify all code in articles against live systems** -- Both agents independently verified their code snippets against the actual codebase files. This caught zero errors because the source material (SKILL.md, test scripts) was already tested, but the verification step builds confidence.
 
-3. **Add gitea remote for direct push** -- Having both `origin` (GitHub) and `gitea` remotes allows manual sync when GitHub Actions is down. Command: `git remote add gitea https://git.terraphim.cloud/{org}/{repo}.git`
+3. **Superseded: Add gitea remote for direct push** -- This was the session 2 approach. Session 3 replaced it with Gitea's native pull mirror (see below).
+
+## Session: 2026-02-18 -- Replace GitHub Actions with Gitea Pull Mirror
+
+### Technical Discoveries
+
+1. **Gitea native pull mirror is the right approach**
+   - Gitea can poll GitHub and pull new commits automatically (configurable interval, minimum 10m)
+   - No GitHub Actions, no tokens in GitHub, no billing dependency
+   - Set up via `POST /api/v1/repos/migrate` with `"mirror": true`
+   - The Gitea repo becomes read-only; all pushes go to GitHub only
+
+2. **Existing repos cannot be converted to pull mirrors**
+   - There is no API to add `mirror: true` to an existing repo
+   - Must delete the repo and recreate via `POST /repos/migrate`
+   - This is documented in Gitea's official docs
+
+3. **The `service` field in migrate API matters for private repos**
+   - `service: "git"` tries `git clone` which fails with "terminal prompts disabled" for private repos
+   - `service: "github"` uses the GitHub API and handles auth correctly
+   - Always use `service: "github"` with `auth_token` for private GitHub repos
+
+4. **Failed migrations leave broken empty repos**
+   - If the async clone fails (bad token, network), Gitea creates the repo entry anyway (`mirror: true, empty: true`)
+   - The `POST /mirror-sync` endpoint returns "Repository is not a mirror" on these broken repos
+   - Must delete and recreate; cannot repair in place
+   - The migrate API returns empty JSON `{}` (null fields) even on success -- check repo status separately
+
+5. **The `github.personal.token` in 1Password is expired**
+   - `op://TerraphimPlatform/github.personal.token/token` returns a token rejected by GitHub (HTTP 401)
+   - `gh auth token` provides a working OAuth token as alternative
+   - Action item: update the 1Password item with a fresh GitHub PAT
+
+6. **Race condition between delete and create on Gitea**
+   - `DELETE /repos/{owner}/{repo}` returns 204 immediately
+   - But the repo name may not be freed yet -- `POST /repos/migrate` returns 409
+   - **Fix:** Always `sleep 10` between delete and create, then verify 404 before proceeding
+
+### Pitfalls to Avoid
+
+1. **Do not use GitHub Actions for Gitea sync** -- it adds unnecessary dependency on GitHub billing, requires storing secrets in GitHub, and consumes Actions minutes. Use Gitea's native pull mirror instead.
+
+2. **Do not use `service: "git"` for private GitHub repos** -- it cannot authenticate. Use `service: "github"` with `auth_token`.
+
+3. **Do not trust the migrate API response body** -- it returns null/empty JSON even on success. Always check repo status via `GET /repos/{owner}/{repo}` after waiting for the async clone.
+
+4. **Do not assume deleted repos are immediately gone** -- always wait and verify with a GET returning 404 before recreating.
+
+### Best Practices Discovered
+
+1. **Simplest mirroring wins** -- Gitea pull mirror is one API call to set up, zero maintenance, and replaces two GitHub Actions workflows plus a monitoring check.
+
+2. **Use `gh auth token` as GitHub token source** -- more reliable than maintaining a separate PAT in 1Password. The `gh` CLI handles token refresh automatically.