Dogfood: run Gatekeep on this repo's PRs

Add .github/workflows/gatekeep-pr.yml with uses: ./ and
OPENROUTER_API_KEY from secrets. Forge-agnostic API helper for Gitea.

docs/remote-uses.md

@@ -0,0 +1,68 @@
+# Remote `uses:` — limitations & workarounds
+
+Gatekeep is a **self-contained composite Action** (`action.yml` at repo root + `scripts/` + `defaults/`). Consumers should prefer:
+
+```yaml
+uses: https://git.example.com/OWNER/gatekeep@v1
+# Project example:
+uses: https://git.potatolab.uk/layue13/gatekeep@main
+```
+
+No copy of Action sources into the consumer repo is required. Optional `.github/gatekeep/` overrides still work via `config-dir`.
+
+## What must be true
+
+| Requirement | Notes |
+| --- | --- |
+| Runner can fetch the Action git repo | Network + credentials if the Action repo is private |
+| Runner can reach OpenRouter | `OPENROUTER_API_KEY` secret |
+| `GITHUB_TOKEN` permissions | `pull-requests: write`, `checks: write` (see sample workflow) |
+| Org / repo Actions policy | External Actions allowed |
+
+## GitHub.com-hosted consumers + Gitea-hosted Action
+
+**Honest status:** GitHub Actions’ first-class `uses: owner/repo@ref` syntax is for **github.com**. Full URL `uses: https://…@ref` is documented for public Actions, but **enterprise / org allowlists** often restrict non-`github.com` Action sources. Behavior can also differ by plan and policy version.
+
+If `uses: https://git.potatolab.uk/layue13/gatekeep@main` fails on github.com runners with an allowlist / “not permitted” / fetch error:
+
+### Workaround A — GitHub mirror (recommended)
+
+1. Mirror `layue13/gatekeep` to a github.com repo you control (e.g. `your-org/gatekeep`).
+2. Point consumers at:
+   ```yaml
+   uses: your-org/gatekeep@main
+   # or: uses: your-org/gatekeep@v1
+   ```
+3. Keep the Gitea repo as source of truth; sync tags on release.
+
+### Workaround B — Vendor checkout (still no Marketplace)
+
+If remotes are fully blocked, checkout Gatekeep into the job and run the composite via local path:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    repository: layue13/gatekeep   # or mirror
+    # For Gitea, use a custom remote + token:
+    # (or actions/checkout with sparse / git mirror step)
+    path: .gatekeep-action
+    ref: main
+- uses: ./.gatekeep-action
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    openrouter-api-key: ${{ secrets.OPENROUTER_API_KEY }}
+```
+
+For a pure Gitea URL when `actions/checkout` only speaks github.com, use an explicit `git clone` step with a deploy token, then `uses: ./.gatekeep-action`.
+
+### Workaround C — Copy-in (appendix)
+
+Copy Action files into `.github/actions/gatekeep` (see README appendix). Same runtime; more drift risk.
+
+## Gitea / Forgejo Actions runners
+
+If the **consumer** also runs on Gitea Actions (not GitHub-hosted), use that forge’s documented `uses:` / local action syntax. Paths remain `github.action_path`-relative so the same Action tree works once the runner can resolve it.
+
+## Secrets never travel with the Action
+
+Remote fetch does **not** include consumer secrets. Always set `OPENROUTER_API_KEY` (and any forge token for private Action clones) on the **consumer** repo/org.