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).