docs: add CLAUDE.md + provider example configs

- CLAUDE.md: project goals (advisory-only, real-bugs-not-nits, easy-to-enable,
  provider-agnostic, portable), architecture map, build/test/release, and
  maintenance rules — incl. "keep README + examples/ current with any env/flag/
  provider/trigger change" and the advisory-only invariant.
- examples/: local-ollama.yml, openai-compatible.yml, endpoint-aliases.yml +
  an examples/README index; README setup step points at them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

examples/README.md

@@ -0,0 +1,24 @@
+# Example consumer workflows
+
+Each file here is a complete, copy-paste **stub workflow**. Pick the one that matches your
+setup, copy it to `.gitea/workflows/adversarial-review.yml` in the repo you want reviewed, and
+set the secrets/vars it references. Gadfly is advisory only — it never blocks a merge.
+
+| File | Backend | Needs |
+|------|---------|-------|
+| [`adversarial-review.yml`](adversarial-review.yml) | **Ollama Cloud** (default) + inline notes for every provider | secret `OLLAMA_CLOUD_API_KEY` |
+| [`local-ollama.yml`](local-ollama.yml) | a **local/LAN Ollama** daemon | nothing (or `GADFLY_BASE_URL` for a remote host) |
+| [`openai-compatible.yml`](openai-compatible.yml) | any **OpenAI-compatible** endpoint (local Ollama `/v1`, gateway, vLLM, OpenRouter…) | `GADFLY_BASE_URL` (+ a key for most gateways) |
+| [`endpoint-aliases.yml`](endpoint-aliases.yml) | **several named backends** at once (one comment each) | repo vars `GADFLY_ENDPOINT_<NAME>` |
+
+Common to all:
+- **Triggers:** new/reopened/ready non-draft PR (auto), `@gadfly review` comment (allowed users),
+  or manual `workflow_dispatch` with a `pr_number`.
+- `GITEA_TOKEN` is provided automatically; comments post as `gitea-actions`.
+- Tested backends are the **Ollama** ones; OpenAI/Anthropic/Google are wired via majordomo but
+  untested. See the repo [README](../README.md#models--providers) for the full config reference
+  and the honest tested/untested status.
+
+> **Gitea note:** repo `vars`/`secrets` are not auto-exposed as env — anything you reference
+> via `${{ vars.X }}` / `${{ secrets.X }}` must appear in the step's `env:` block (already wired
+> in these examples).

examples/endpoint-aliases.yml

@@ -0,0 +1,54 @@
+# Gadfly with named ENDPOINT ALIASES — review with several backends at once,
+# each posting its own comment. Copy to .gitea/workflows/adversarial-review.yml.
+#
+# GADFLY_ENDPOINT_<NAME>="<provider>|<base-url>[|<key>]" registers a provider you
+# can then reference as "<name>/<model>" (NAME lowercases: BIGBOX -> bigbox).
+# The base URL is used verbatim, so plaintext http LAN endpoints work.
+#
+# Gitea note: vars/secrets aren't auto-exposed as env, so map each alias here.
+# Suggested repo vars:
+#   GADFLY_ENDPOINT_BIGBOX = ollama|http://192.168.1.50:11434
+#   GADFLY_ENDPOINT_GPU    = openai|http://gpu.lan:8000/v1
+
+name: Adversarial Review (Gadfly)
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number: { description: "PR number to review", required: true }
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: gadfly-${{ github.event.issue.number || github.event.pull_request.number || github.event.inputs.pr_number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: docker://gitea.stevedudenhoeffer.com/steve/gadfly:latest
+        env:
+          GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          # --- named endpoints (mapped from repo vars) ---
+          GADFLY_ENDPOINT_BIGBOX: ${{ vars.GADFLY_ENDPOINT_BIGBOX }}   # "ollama|http://192.168.1.50:11434"
+          GADFLY_ENDPOINT_GPU: ${{ vars.GADFLY_ENDPOINT_GPU }}         # "openai|http://gpu.lan:8000/v1"
+          # one reviewer (one comment) per model, across the aliased endpoints:
+          GADFLY_MODELS: "bigbox/qwen2.5-coder:7b,gpu/llama3.1"
+          # --- event context (leave as-is) ---
+          EVENT_NAME: ${{ github.event_name }}
+          PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+          PR_BRANCH: ${{ github.head_ref }}
+          IS_DRAFT: ${{ github.event.pull_request.draft }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          ACTOR: ${{ github.actor }}

examples/local-ollama.yml

@@ -0,0 +1,49 @@
+# Gadfly using a LOCAL Ollama daemon (no API key needed).
+# Copy to .gitea/workflows/adversarial-review.yml in your repo.
+#
+# The runner must be able to reach the Ollama host. For localhost on the runner,
+# leave GADFLY_BASE_URL unset; for a LAN box set it to http://<host>:11434.
+#
+# Pick a model you've pulled into Ollama (e.g. `ollama pull qwen2.5-coder:7b`).
+
+name: Adversarial Review (Gadfly)
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number: { description: "PR number to review", required: true }
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: gadfly-${{ github.event.issue.number || github.event.pull_request.number || github.event.inputs.pr_number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: docker://gitea.stevedudenhoeffer.com/steve/gadfly:latest
+        env:
+          GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          # --- local Ollama ---
+          GADFLY_PROVIDER: ollama
+          GADFLY_MODELS: qwen2.5-coder:7b
+          # GADFLY_BASE_URL: http://192.168.1.50:11434   # uncomment for a remote/LAN daemon
+          # --- event context (leave as-is) ---
+          EVENT_NAME: ${{ github.event_name }}
+          PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+          PR_BRANCH: ${{ github.head_ref }}
+          IS_DRAFT: ${{ github.event.pull_request.draft }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          ACTOR: ${{ github.actor }}

examples/openai-compatible.yml

@@ -0,0 +1,52 @@
+# Gadfly against an OpenAI-COMPATIBLE endpoint.
+# Copy to .gitea/workflows/adversarial-review.yml in your repo.
+#
+# Works for: a local Ollama's OpenAI bridge (http://localhost:11434/v1), an
+# in-house gateway, OpenRouter, vLLM, LM Studio, etc. This is the same code path
+# the real OpenAI API uses, so it's a free way to exercise the OpenAI provider.
+#
+# Set GADFLY_API_KEY (or OPENAI_API_KEY) — Ollama ignores it, but most gateways
+# require some value.
+
+name: Adversarial Review (Gadfly)
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number: { description: "PR number to review", required: true }
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: gadfly-${{ github.event.issue.number || github.event.pull_request.number || github.event.inputs.pr_number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: docker://gitea.stevedudenhoeffer.com/steve/gadfly:latest
+        env:
+          GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          # --- OpenAI-compatible endpoint ---
+          GADFLY_PROVIDER: openai
+          GADFLY_BASE_URL: http://localhost:11434/v1     # e.g. local Ollama /v1, or your gateway
+          GADFLY_API_KEY: ${{ secrets.OPENAI_API_KEY }}  # any non-empty value for Ollama
+          GADFLY_MODELS: qwen2.5-coder:7b
+          # --- event context (leave as-is) ---
+          EVENT_NAME: ${{ github.event_name }}
+          PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+          PR_BRANCH: ${{ github.head_ref }}
+          IS_DRAFT: ${{ github.event.pull_request.draft }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          ACTOR: ${{ github.actor }}