prxref 0.2.0__tar.gz

prxref-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.superpowers/
+.claude/
+docs/superpowers/

prxref-0.2.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-08-26
+
+First published release. 0.1.0 was never tagged or uploaded — its entry is kept
+below as the development baseline for the work it describes.
+
+### Changed
+
+- **Shipped defaults no longer point at anything.** `PRXREF_LLM_BASE_URL`,
+  `PRXREF_LLM_API_KEY` and `PRXREF_LLM_MODELS` now default to empty. They
+  previously defaulted to a private LAN endpoint (`http://127.0.0.1:8090/v1`,
+  model chain `flash,orch`), so a fresh install with no configuration issued a
+  request that could only fail, against infrastructure that was never yours.
+- **`prxref review` exits 2 when required configuration is missing**, raising
+  the new `prxref.llm.ConfigError` naming the exact variable to set. This is
+  narrow and deliberate: a missing endpoint is a usage error, not a review
+  outcome. Genuine review failures still exit 0 — non-blocking is a product
+  tenet and is unchanged. An empty `PRXREF_LLM_API_KEY` remains valid, since a
+  local no-auth server (Ollama, vLLM) needs none.
+
+### Fixed
+
+- **`PRXREF_ALLOW_UNSIGNED` was parsed two different ways.** `config.py`
+  accepted `1`, `true`, `yes` and `on`, while `webhooks._allow_unsigned` — the
+  only gate that runs — accepted the literal `1` alone, and nothing in the
+  package read the config value at all. Setting it to `true` made the config
+  dict report the bypass as enabled while signature verification stayed on.
+  This failed safe, so it was a correctness and documentation defect rather
+  than a hole. Both now parse identically, pinned by a test asserting they
+  agree across 15 inputs.
+- **The bundled `pull_request_target` review workflow could never install
+  prxref.** It used `uv pip install --system`, which fails on GitHub's Ubuntu
+  runners because their system interpreter is PEP 668 externally-managed, and
+  which additionally suppressed the virtualenv the setup action provisions.
+  The failure was invisible: `continue-on-error` masked it and the review step
+  was skipped rather than failed, so the run reported success without a review
+  having happened.
+
+### Added
+
+- A test pinning the packaging metadata version to `prxref.__version__`, so the
+  two version declarations cannot drift apart across a release.
+
+## [0.1.0] — 2026-08-26
+
+Development baseline. Never published to PyPI and never tagged; superseded by
+0.2.0 before release.
+
+### Added
+
+- **Three forges behind one command.** `prxref review --pr-url <url>` detects
+  Bitbucket Cloud, GitHub, GitHub Enterprise Server, GitLab SaaS, and self-hosted
+  GitLab from the URL alone, including arbitrarily nested GitLab subgroups. All
+  three adapters implement a single `Forge` Protocol.
+- **Review pipeline.** Parses one unified diff, partitions it into risk-ranked
+  chunks, fans out parallel single-shot LLM worker reviews, then gates findings
+  through deterministic quality passes (line alignment, dedup, confidence floor)
+  before posting.
+- **Provider-agnostic LLM access with a fallback chain.** `PRXREF_LLM_MODELS`
+  is tried left to right; a model that times out, refuses, or returns malformed
+  JSON is abandoned immediately for the next one, with no same-model retries.
+  Backends: plain-HTTP OpenAI-compatible (default, zero extra dependencies),
+  `litellm` (optional extra). prxref reads no upstream provider credentials.
+- **Inline comments plus a summary.** On GitHub and GitLab, summaries are
+  deduplicated across re-runs via a hidden `<!-- prxref-summary -->` marker — a
+  re-review updates the existing comment instead of stacking a new one.
+  Bitbucket posts a fresh summary each run. Every comment carries model
+  attribution.
+- **Webhook server.** `prxref serve` verifies HMAC-SHA256 (GitHub, Bitbucket) or
+  a shared token (GitLab) in constant time, returns `202 Accepted` immediately,
+  and processes reviews serially on one background worker. `GET /health` for
+  liveness.
+- **Graceful degradation per forge.** GitHub 422s on out-of-hunk lines are
+  skipped; GitLab position-anchoring failures fall back to a plain note;
+  Bitbucket inline 4xxs are non-fatal.
+- Docker image and compose file, systemd unit example, and CI templates for
+  GitHub Actions, GitLab CI, and Bitbucket Pipelines.
+- Docs: [deployment](docs/deploy.md), [forge specifics](docs/forges.md),
+  [LLM backends](docs/llm.md), [environment variables](docs/env-vars.md).
+
+### Security
+
+- `PRXREF_ALLOW_UNSIGNED` requires the literal string `1`. `true`, `yes`, and
+  `on` are deliberately rejected so a stray truthy value cannot silently disable
+  webhook signature verification. Even when enabled, a payload carrying a wrong
+  signature is still rejected — only a missing one is tolerated.
+- Per-forge token separation, so a self-hosted GitHub Enterprise token is never
+  sent to `github.com`.
+
+### Notes
+
+- `review` exits 0 even when the review fails. prxref is an advisor, not a merge
+  gate; do not build a security control on its exit code.
+- Diff content is sent to whichever OpenAI-compatible endpoint you configure.
+- Requires Python 3.12+. Tested on 3.12 and 3.13.
+
+[Unreleased]: https://github.com/sblattj/prxref/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/sblattj/prxref/releases/tag/v0.2.0

prxref-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to prxref
+
+Thanks for taking the time. Bug reports, forge quirks, and prompt improvements
+are all welcome.
+
+## Development Setup
+
+prxref uses [uv](https://docs.astral.sh/uv/) for environments and locking.
+
+```bash
+git clone https://github.com/sblattj/prxref
+cd prxref
+uv sync --extra dev
+```
+
+## The Checks
+
+Both must pass before a PR can merge. CI runs exactly these on Python 3.12 and
+3.13:
+
+```bash
+uv run pytest              # 236 tests, no network required
+uv run ruff check src tests
+```
+
+The suite is fully offline — every forge and LLM call is stubbed. If a change
+you make needs the network to test, that is a design smell worth raising in the
+issue first.
+
+To check that packaging still works:
+
+```bash
+uv build                   # must produce BOTH a .tar.gz and a .whl
+```
+
+## Architecture
+
+One unified diff in, inline comments out:
+
+```
+PR URL -> detect_forge -> Forge adapter -> unified diff -> risk-ranked chunks
+       -> parallel LLM workers (fallback chain) -> quality gate -> post
+```
+
+- `forges/base.py` defines a single `Forge` Protocol. `bitbucket.py`,
+  `github.py`, and `gitlab.py` implement it. **Adding a forge means implementing
+  that Protocol and nothing else** — the pipeline above is forge-agnostic.
+- `llm_backends.py` holds the interchangeable backends. Core code talks to the
+  protocol in `llm.py`, never to a vendor SDK.
+- `quality.py` is deterministic. Findings are dropped by rule, not by asking a
+  model to double-check.
+
+## Conventions
+
+These are load-bearing, not style preferences:
+
+- **stdlib + `requests` only in core.** Every LLM backend beyond the plain-HTTP
+  one is an optional extra. A core import of a heavy dependency is a bug.
+- **No provider credentials.** prxref reads no OpenAI/AWS/Google/Anthropic key.
+  It calls one OpenAI-compatible endpoint the user configures. Keep it that way.
+- **Single-shot LLM calls only.** All context is gathered before the call. No
+  agent loops, no tool use, no multi-turn negotiation with the model.
+- **Non-blocking by design.** `review` exits 0 even when the review fails.
+  prxref advises; it does not gate merges. Do not add a failure exit code.
+- **Every posted comment carries model attribution.**
+- Docstrings on public API. No inline commentary restating the code.
+
+## Prompt Changes
+
+`src/prxref/prompts/*.md` are packaged data files loaded via
+`importlib.resources`. If you add one, confirm it survives packaging:
+
+```bash
+uv build && python -c "
+import zipfile, glob
+print([n for n in zipfile.ZipFile(glob.glob('dist/*.whl')[0]).namelist() if 'prompts' in n])"
+```
+
+Prompt edits change review output in ways tests cannot fully capture. Say in the
+PR what you ran it against and what changed in the findings.
+
+## Pull Requests
+
+- Branch off `main`, one logical change per PR.
+- Say what breaks without the change, not just what the change does.
+- New behavior needs a test. Bug fixes need a test that fails before the fix.
+- prxref reviews its own PRs — it is an advisor, so feel free to disagree with it
+  in a comment.
+
+## Reporting Bugs
+
+Include the forge, the URL shape that failed (redacted is fine), the backend and
+model chain, and the output of `prxref review --pr-url ... -v`. Forge API quirks
+are the most common cause, and the verbose output usually shows which call
+returned what.
+
+For security issues, do **not** open an issue — see [SECURITY.md](SECURITY.md).
+
+## License
+
+Contributions are licensed under the MIT License, matching the project.

prxref-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Blatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prxref-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: prxref
+Version: 0.2.0
+Summary: Fast automated AI code review for Bitbucket, GitLab, and GitHub
+Project-URL: Homepage, https://github.com/sblattj/prxref
+Project-URL: Repository, https://github.com/sblattj/prxref
+Project-URL: Issues, https://github.com/sblattj/prxref/issues
+Project-URL: Changelog, https://github.com/sblattj/prxref/blob/main/CHANGELOG.md
+Author: Stephen Blatt
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'
+Description-Content-Type: text/markdown
+
+# prxref
+
+Fast automated AI code review for Bitbucket, GitLab, and GitHub.
+
+prxref inspects pull and merge requests across the three major code hosting forges in sub-minute review cycles. It parses unified diffs, partitions changes into risk-ranked chunks, fans out parallel single-shot LLM reviews across a cheap-first model fallback chain, filters findings through deterministic quality gates, and publishes inline comments alongside an executive summary.
+
+```
+                  ┌──────────────────────┐
+                  │    Pull / MR URL     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     detect_forge     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │    Forge Adapter     │
+                  │ (BB / GitHub / GL)   │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     Unified Diff     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Risk-Ranked Chunking │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Parallel LLM Workers │
+                  │  (Fallback Chain)    │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     Quality Gate     │
+                  │ Line Align / Dedup   │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Post Inline Comments │
+                  │     + Summary        │
+                  └──────────────────────┘
+```
+
+## Quickstart
+
+Run reviews instantly without local installation using `uvx`, or install the CLI globally:
+
+```bash
+# Run one-shot review via uvx
+uvx prxref review --pr-url https://github.com/org/repo/pull/123
+
+# Or install tool globally
+uv tool install prxref
+prxref review --pr-url https://github.com/org/repo/pull/123
+
+# Or install straight from source (works before the first PyPI release)
+uv tool install git+https://github.com/sblattj/prxref
+```
+
+### Review Any Forge
+
+Pass any PR or MR URL directly. Forge type, repository namespace, and pull request ID are detected automatically:
+
+```bash
+# Bitbucket Cloud
+prxref review --pr-url https://bitbucket.org/workspace/repo/pull-requests/42
+
+# GitHub & GitHub Enterprise
+prxref review --pr-url https://github.com/owner/repository/pull/108
+
+# GitLab & Self-Hosted GitLab (including nested subgroups)
+prxref review --pr-url https://gitlab.com/group/subgroup/project/-/merge_requests/15
+```
+
+## LLM Configuration
+
+prxref operates without direct cloud provider SDK keys (no Anthropic API keys). It ships with **no default endpoint and no default model chain**: point it at any OpenAI-compatible `/chat/completions` server (OpenRouter, Together, Groq, vLLM, Ollama, a self-hosted gateway), or install the optional `litellm` extra. `PRXREF_LLM_BASE_URL` and `PRXREF_LLM_MODELS` are required — leaving either unset exits `2` with an error naming the variable.
+
+```bash
+# Default backend: plain HTTP to any OpenAI-compatible endpoint
+export PRXREF_LLM_BACKEND=http
+export PRXREF_LLM_BASE_URL="https://openrouter.ai/api/v1"
+export PRXREF_LLM_API_KEY="$OPENROUTER_API_KEY"
+export PRXREF_LLM_MODELS="z-ai/glm-5.3-flash"
+export PRXREF_LLM_REASONING_EFFORT=low
+
+# Optional: in-process litellm extra
+# pip install 'prxref[litellm]'
+export PRXREF_LLM_BACKEND=litellm
+export PRXREF_LLM_MODELS="openrouter/meta-llama/llama-3.3-70b-instruct,bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0"
+```
+
+See [docs/llm.md](docs/llm.md) for architecture, failover behavior, and backend setup.
+
+## Forge Authentication
+
+Configure the authentication token matching your forge:
+
+| Forge | Environment Variable | Notes |
+|---|---|---|
+| **Bitbucket** | `PRXREF_BITBUCKET_TOKEN` | Bearer token (workspace or repo access token) |
+| **Bitbucket (Basic)** | `PRXREF_BITBUCKET_USER` + `PRXREF_BITBUCKET_APP_PASSWORD` | App password fallback |
+| **GitHub** | `PRXREF_GITHUB_TOKEN` | Personal Access Token (PAT) or GitHub App token |
+| **GitHub Enterprise** | `PRXREF_GITHUB_ENTERPRISE_TOKEN` | Used when host is not `github.com` (falls back to `PRXREF_GITHUB_TOKEN`) |
+| **GitLab** | `PRXREF_GITLAB_TOKEN` | Personal, project, or group access token (`PRIVATE-TOKEN`) |
+
+See [docs/env-vars.md](docs/env-vars.md) for the full configuration reference and [docs/forges.md](docs/forges.md) for forge specifics.
+
+## Webhook Server
+
+Run prxref as a persistent daemon to handle webhook events from GitHub, Bitbucket, and GitLab:
+
+```bash
+prxref serve --port 8080 --host 0.0.0.0
+```
+
+The service exposes:
+- `POST /webhook` — verifies HMAC or token signatures per forge, enqueues incoming PR events, and responds immediately with `202 Accepted`. A background worker processes reviews serially.
+- `GET /health` — liveness probe returning `{"ok": true}`.
+
+## CLI Flags
+
+- `--pr-url URL` — full web URL of the PR or MR (required for `review`).
+- `--no-post` — dry run; run review analysis and quality passes without writing comments to the forge.
+- `--max-chunks N` — override maximum diff chunks evaluated (default `8`).
+- `-v, --verbose` — output run timing, token counts, and finding breakdowns to stdout.

prxref-0.2.0/README.md

@@ -0,0 +1,134 @@
+# prxref
+
+Fast automated AI code review for Bitbucket, GitLab, and GitHub.
+
+prxref inspects pull and merge requests across the three major code hosting forges in sub-minute review cycles. It parses unified diffs, partitions changes into risk-ranked chunks, fans out parallel single-shot LLM reviews across a cheap-first model fallback chain, filters findings through deterministic quality gates, and publishes inline comments alongside an executive summary.
+
+```
+                  ┌──────────────────────┐
+                  │    Pull / MR URL     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     detect_forge     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │    Forge Adapter     │
+                  │ (BB / GitHub / GL)   │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     Unified Diff     │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Risk-Ranked Chunking │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Parallel LLM Workers │
+                  │  (Fallback Chain)    │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │     Quality Gate     │
+                  │ Line Align / Dedup   │
+                  └──────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Post Inline Comments │
+                  │     + Summary        │
+                  └──────────────────────┘
+```
+
+## Quickstart
+
+Run reviews instantly without local installation using `uvx`, or install the CLI globally:
+
+```bash
+# Run one-shot review via uvx
+uvx prxref review --pr-url https://github.com/org/repo/pull/123
+
+# Or install tool globally
+uv tool install prxref
+prxref review --pr-url https://github.com/org/repo/pull/123
+
+# Or install straight from source (works before the first PyPI release)
+uv tool install git+https://github.com/sblattj/prxref
+```
+
+### Review Any Forge
+
+Pass any PR or MR URL directly. Forge type, repository namespace, and pull request ID are detected automatically:
+
+```bash
+# Bitbucket Cloud
+prxref review --pr-url https://bitbucket.org/workspace/repo/pull-requests/42
+
+# GitHub & GitHub Enterprise
+prxref review --pr-url https://github.com/owner/repository/pull/108
+
+# GitLab & Self-Hosted GitLab (including nested subgroups)
+prxref review --pr-url https://gitlab.com/group/subgroup/project/-/merge_requests/15
+```
+
+## LLM Configuration
+
+prxref operates without direct cloud provider SDK keys (no Anthropic API keys). It ships with **no default endpoint and no default model chain**: point it at any OpenAI-compatible `/chat/completions` server (OpenRouter, Together, Groq, vLLM, Ollama, a self-hosted gateway), or install the optional `litellm` extra. `PRXREF_LLM_BASE_URL` and `PRXREF_LLM_MODELS` are required — leaving either unset exits `2` with an error naming the variable.
+
+```bash
+# Default backend: plain HTTP to any OpenAI-compatible endpoint
+export PRXREF_LLM_BACKEND=http
+export PRXREF_LLM_BASE_URL="https://openrouter.ai/api/v1"
+export PRXREF_LLM_API_KEY="$OPENROUTER_API_KEY"
+export PRXREF_LLM_MODELS="z-ai/glm-5.3-flash"
+export PRXREF_LLM_REASONING_EFFORT=low
+
+# Optional: in-process litellm extra
+# pip install 'prxref[litellm]'
+export PRXREF_LLM_BACKEND=litellm
+export PRXREF_LLM_MODELS="openrouter/meta-llama/llama-3.3-70b-instruct,bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0"
+```
+
+See [docs/llm.md](docs/llm.md) for architecture, failover behavior, and backend setup.
+
+## Forge Authentication
+
+Configure the authentication token matching your forge:
+
+| Forge | Environment Variable | Notes |
+|---|---|---|
+| **Bitbucket** | `PRXREF_BITBUCKET_TOKEN` | Bearer token (workspace or repo access token) |
+| **Bitbucket (Basic)** | `PRXREF_BITBUCKET_USER` + `PRXREF_BITBUCKET_APP_PASSWORD` | App password fallback |
+| **GitHub** | `PRXREF_GITHUB_TOKEN` | Personal Access Token (PAT) or GitHub App token |
+| **GitHub Enterprise** | `PRXREF_GITHUB_ENTERPRISE_TOKEN` | Used when host is not `github.com` (falls back to `PRXREF_GITHUB_TOKEN`) |
+| **GitLab** | `PRXREF_GITLAB_TOKEN` | Personal, project, or group access token (`PRIVATE-TOKEN`) |
+
+See [docs/env-vars.md](docs/env-vars.md) for the full configuration reference and [docs/forges.md](docs/forges.md) for forge specifics.
+
+## Webhook Server
+
+Run prxref as a persistent daemon to handle webhook events from GitHub, Bitbucket, and GitLab:
+
+```bash
+prxref serve --port 8080 --host 0.0.0.0
+```
+
+The service exposes:
+- `POST /webhook` — verifies HMAC or token signatures per forge, enqueues incoming PR events, and responds immediately with `202 Accepted`. A background worker processes reviews serially.
+- `GET /health` — liveness probe returning `{"ok": true}`.
+
+## CLI Flags
+
+- `--pr-url URL` — full web URL of the PR or MR (required for `review`).
+- `--no-post` — dry run; run review analysis and quality passes without writing comments to the forge.
+- `--max-chunks N` — override maximum diff chunks evaluated (default `8`).
+- `-v, --verbose` — output run timing, token counts, and finding breakdowns to stdout.

prxref-0.2.0/SECURITY.md

@@ -0,0 +1,73 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues privately through GitHub's
+[private vulnerability reporting](https://github.com/sblattj/prxref/security/advisories/new)
+rather than opening a public issue.
+
+Include the version, the forge and backend involved, and the smallest set of
+steps that reproduces the problem. You should get an initial response within a
+week.
+
+## Supported Versions
+
+prxref is pre-1.0. Only the latest release receives security fixes.
+
+## Security Model
+
+prxref holds credentials for third-party code forges and accepts unauthenticated
+network input on its webhook endpoint. The properties below are the ones worth
+attacking, and the ones worth reporting if you can break them.
+
+### Credentials
+
+- Every credential is read from the environment at call time. prxref writes no
+  credential file and has no config file that can hold one.
+- prxref reads **no upstream LLM provider credentials** — no OpenAI, AWS, Google,
+  or Anthropic keys. It talks to one OpenAI-compatible endpoint whose URL and key
+  you supply. Provider credentials live behind that endpoint, not here.
+- Forge tokens are scoped per forge (`PRXREF_BITBUCKET_TOKEN`,
+  `PRXREF_GITHUB_TOKEN`, `PRXREF_GITHUB_ENTERPRISE_TOKEN`, `PRXREF_GITLAB_TOKEN`).
+  Grant only pull-request write scope.
+- `PRXREF_GITHUB_ENTERPRISE_TOKEN` exists so a self-hosted GHES token is not sent
+  to `github.com`. Host determines which token is used.
+
+See [docs/env-vars.md](docs/env-vars.md) for the full variable table.
+
+### Webhook signature verification
+
+`prxref serve` verifies every payload before acting on it:
+
+| Forge | Header | Scheme |
+|---|---|---|
+| GitHub | `X-Hub-Signature-256` | HMAC-SHA256, constant-time compare |
+| Bitbucket | `X-Hub-Signature` | HMAC-SHA256, constant-time compare |
+| GitLab | `X-Gitlab-Token` | shared secret, constant-time compare |
+
+A payload that fails verification is rejected and never reaches the review
+pipeline. A correctly-signed payload for an event prxref does not handle is
+ignored rather than queued.
+
+### `PRXREF_ALLOW_UNSIGNED`
+
+This flag disables signature verification and is for local development only.
+**Do not set it in production.**
+
+It requires the **literal string `1`**. `true`, `yes`, and `on` are deliberately
+rejected so that a stray truthy value cannot silently disable verification. When
+it is on, prxref logs a warning at startup and marks each bypassed response with
+an `X-Prxref-Warning` header.
+
+Even with the bypass on, a payload carrying a *wrong* signature is still
+rejected — the bypass only tolerates a *missing* one.
+
+### Deliberate non-goals
+
+- **prxref does not gate merges.** `review` exits 0 even when the review fails.
+  It is an advisor. Do not build a security control on its exit code.
+- **Diff content is sent to the LLM endpoint you configure.** If your diffs are
+  sensitive, point prxref at an endpoint you trust. prxref does not choose or
+  contact any provider on its own.
+- **Review output is model-generated and not authoritative.** Findings can be
+  wrong. Treat them as review comments, not as verified vulnerability reports.