argus-proof 0.2.2__tar.gz → 0.3.0__tar.gz

argus_proof-0.3.0/.cursor/rules/agent-coding-packs.mdc

@@ -0,0 +1,33 @@
+---
+description: Fetch ai-code-auditor coding packs for argus-proof before changing code
+alwaysApply: true
+---
+
+<!-- ai-audit:agent-packs:start -->
+# Agent coding packs
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-proof` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-proof`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   CLI equivalent: `ai-audit packs --bundle --repo argus-proof`.
+2. **Claim** the specialist pack you pick:
+   `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`; the token is in your environment, set for Claude Code
+   in `~/.claude/settings.json`. If it is empty or you get a 401, ask the user; don't search env files).
+3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
+   HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
+   or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
+4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-proof","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+**Search** before crawling: `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/search?q=<question>&repo=argus-proof&kind=wiki`
+(wiki sections and packs with links; CLI `ai-audit search "<question>" --repo argus-proof`).
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

{argus_proof-0.2.2 → argus_proof-0.3.0}/.env.example

@@ -18,8 +18,11 @@ PROOF_BACKEND=comfyui
 # given PATH-style (dir1:dir2), mirroring ComfyUI's extra_model_paths trees.
 PROOF_MODELS_DIR=~/models
 
-# ComfyUI workflow template (API-format graph with $placeholders). Unset = the
-# packaged SDXL+LoRA example (argus_proof/templates/comfyui_sdxl_lora.json).
+# ComfyUI workflow template (API-format graph with $placeholders), used for every
+# checkpoint. Unset = the packaged templates, picked by the checkpoint's family
+# folder: checkpoints/flux/... -> comfyui_flux_lora.json, anything else ->
+# comfyui_sdxl_lora.json. The Flux template loads t5xxl_fp8_e4m3fn, clip_l and ae
+# by name from ComfyUI's clip/ and vae/ folders.
 #PROOF_WORKFLOW_TEMPLATE=/path/to/workflow.json
 
 # ── Storage ──────────────────────────────────────────────────────────
@@ -37,6 +40,11 @@ PROOF_MODELS_DIR=~/models
 # at the seeded "tape" reports/runs when this is on. GET /health echoes the flag.
 #ARGUS_PROOF_READ_ONLY=1
 
+# Dev mode (issue #59): register POST /purge and POST /purge/{run_id}, which
+# delete runs and their reports (body {"confirm": "purge"}). Off by default —
+# reports are the evaluation record. Compose sets it from DEVMODE.
+#ARGUS_PROOF_DEVMODE=1
+
 # HTTP backends — the engine's base URL.
 COMFYUI_BASE_URL=http://127.0.0.1:8188
 A1111_BASE_URL=http://127.0.0.1:7860
@@ -51,3 +59,8 @@ A1111_BASE_URL=http://127.0.0.1:7860
 # remote (cloud) backend — the hosted generation endpoint + its bearer token.
 PROOF_REMOTE_URL=https://your-proof-gen.example.com
 PROOF_REMOTE_API_KEY=
+
+# ── Agent tooling (not read by this service) ──
+# ai-code-auditor audit API base that AGENTS.md tells coding agents to use.
+# Put the real host/IP in your local .env, never here.
+# AI_AUDIT_PUBLIC_BASE_URL=http://<AUDIT_HOST>:8765

{argus_proof-0.2.2 → argus_proof-0.3.0}/.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [dev, main]
   pull_request:
-    branches: [main]
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.ref }}

{argus_proof-0.2.2 → argus_proof-0.3.0}/.github/workflows/release.yml

@@ -6,6 +6,12 @@ name: Release to PyPI
 on:
   push:
     tags: ["v*"]
+  # Sent by argus-cortex's release workflow. The image installs argus-cortex
+  # from the pyproject range at build time, so rebuilding the newest release's
+  # image is how a new cortex reaches it. Only the image jobs run: PyPI and the
+  # GitHub Release for that tag already exist.
+  repository_dispatch:
+    types: [cortex-released]
 
 permissions:
   contents: read
@@ -13,6 +19,9 @@ permissions:
 
 jobs:
   build:
+    # Not on a cortex dispatch, so the PyPI and Release jobs that chain off it
+    # skip too.
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -79,15 +88,51 @@ jobs:
           path: dist/
       - uses: pypa/gh-action-pypi-publish@release/v1
 
+  release-tag:
+    # The tag the image jobs build: the pushed one, or on a cortex dispatch the
+    # newest final release. A pre-release never moved `latest`, so a dispatch
+    # does not rebuild one.
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+      sha: ${{ steps.tag.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        if: github.event_name == 'repository_dispatch'
+      - id: tag
+        env:
+          CORTEX_VERSION: ${{ github.event.client_payload.version }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" != repository_dispatch ]; then
+            echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
+            echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          refs=$(git ls-remote --tags origin 'refs/tags/v*')
+          tag=$(echo "$refs" | sed -n 's|.*refs/tags/\(v[0-9]*\.[0-9]*\.[0-9]*\)\(\^{}\)\{0,1\}$|\1|p' | sort -uV | tail -n1)
+          if [ -z "$tag" ]; then
+            echo "::notice::No release tag yet, so no image to rebuild for cortex $CORTEX_VERSION."
+            exit 0
+          fi
+          # An annotated tag lists its commit on the peeled ^{} line.
+          sha=$(echo "$refs" | awk -v t="refs/tags/$tag" '$2 == t {l = $1} $2 == t "^{}" {p = $1} END {print p ? p : l}')
+          echo "Rebuilding $tag ($sha) for cortex $CORTEX_VERSION."
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
   publish-image:
     runs-on: ubuntu-latest
-    needs: test-install
+    needs: [release-tag, test-install]
+    # On a cortex dispatch test-install is skipped (nothing was built for PyPI),
+    # so the job runs on the tag alone.
+    if: "!cancelled() && needs.release-tag.outputs.tag != '' && (needs.test-install.result == 'success' || github.event_name == 'repository_dispatch')"
     permissions:
       contents: read
       packages: write
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: ${{ needs.release-tag.outputs.tag }}
           fetch-depth: 0 # hatch-vcs reads the tag from git history
       - uses: docker/setup-buildx-action@v3
       - uses: docker/login-action@v3
@@ -99,9 +144,10 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: ghcr.io/${{ github.repository_owner }}/argus-proof
+          labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
           tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
             type=raw,value=latest
       - uses: docker/build-push-action@v6
         with:
@@ -110,6 +156,9 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          # A dispatch rebuilds an unchanged context, so a cached install layer
+          # would keep the old argus-cortex.
+          no-cache: ${{ github.event_name == 'repository_dispatch' }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 

argus_proof-0.3.0/.github/workflows/suite.yml

@@ -0,0 +1,11 @@
+name: Suite
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  suite:
+    uses: smk762/argus-ci/.github/workflows/suite-check.yml@v1

argus_proof-0.3.0/AGENTS.md

@@ -0,0 +1,28 @@
+<!-- ai-audit:agent-packs:start -->
+## Agent coding packs (ai-code-auditor)
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-proof` yourself.
+
+The audit API base URL is `$AI_AUDIT_PUBLIC_BASE_URL`. The real host/IP is in the local `.env`
+(see `.env.example`, placeholder `http://<AUDIT_HOST>:8765`); read it there, don't guess.
+
+1. **Bundle (one call):** `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/bundle?repo=argus-proof`
+   (world model + ranked specialist packs + token-capped `briefs_markdown`;
+   optional `&token_budget=2500&q=<keyword>&limit_specialists=5`).
+   CLI equivalent: `ai-audit packs --bundle --repo argus-proof`.
+2. **Claim** the specialist pack you pick:
+   `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>/status` `{"status":"claimed"}`
+   (send `X-API-Token: $AI_AUDIT_API_TOKEN`; the token is in your environment, set for Claude Code
+   in `~/.claude/settings.json`. If it is empty or you get a 401, ask the user; don't search env files).
+3. **Fix:** `ai-audit repair --pack-id <id>` (agent-composer repair loop; fetches the pack for you;
+   HTTP: `POST http://127.0.0.1:9150/api/repair/run` `{"pack_id":"<id>","mode":"review"}`),
+   or read `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/packs/<id>` / `.../brief` and implement it yourself.
+4. **Close:** `POST $AI_AUDIT_PUBLIC_BASE_URL/audit/validate_patch` `{"repo":"argus-proof","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+**Search** before crawling: `GET $AI_AUDIT_PUBLIC_BASE_URL/audit/search?q=<question>&repo=argus-proof&kind=wiki`
+(wiki sections and packs with links; CLI `ai-audit search "<question>" --repo argus-proof`).
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

{argus_proof-0.2.2 → argus_proof-0.3.0}/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-15
+
+### Added
+- **A new argus-cortex rebuilds the published image.** `release.yml` also runs on
+  the `cortex-released` dispatch argus-cortex's release sends: only the image job runs,
+  rebuilding the newest final `v*` tag without cache and republishing its tags, so the
+  image picks up the cortex its pyproject range now resolves to.
+- **`GET /report/{run_id}/manifest`** (#57) serves the `RunManifest` behind a
+  report (checkpoint, VAE, LoRAs, sampling, prompt, seeds), so studio can prefill
+  `/darkroom` from a passed run (argus-studio#125). It is `404` when there is no report,
+  `410 Gone` when the report was kept but its run dir was pruned, and `400` for an
+  unreadable manifest or one belonging to another run. `GET /health` gains a
+  `capabilities` list (`["report_manifest"]`) so a client can detect the route.
+- **Wire schema 1.4** (#58): `ReportSummary` and the `/run/stream` frames join
+  `schema/proof-wire.schema.json`. New `ScoringFrame` and `CompleteFrame` models, plus the
+  `RunStreamFrame` union discriminated by `type`, describe every NDJSON line, and the server
+  builds its frames from them. `ReportSummary` moved to `argus_proof.models` and is still
+  importable from `argus_proof.reports`.
+- **Flux LoRAs** (#60): `SamplingParams.guidance` (wire 1.4; same field as darkroom's)
+  and a `$guidance` template slot. A packaged `comfyui_flux_lora.json` is picked when
+  the base checkpoint sits under `checkpoints/flux/`, with SDXL's template for every
+  other family, unless `PROOF_WORKFLOW_TEMPLATE` overrides both. `/run/stream` and
+  `argus-proof run` take `guidance`, and leaving out `cfg`/`sampler`/`scheduler`/`guidance`
+  gets the family's defaults (Flux: cfg 1, `euler`/`simple`, guidance 3.5).
+- **Devmode purge** (#59): `POST /purge/{run_id}` deletes one run's report and run dir,
+  and `POST /purge` deletes all of them. They're registered only with `ARGUS_PROOF_DEVMODE=1`
+  (`serve --devmode`) and need a `{"confirm": "purge"}` body. A run still generating gets
+  `409`, and read-only mode refuses them. The HITL review and refinement go with the report.
+  `/health` gains `devmode`, and lists `purge` in `capabilities` when the routes work.
+  `/run/stream` now also refuses (`409`) a `run_id` that is already generating.
+- **Llama Guard 3 moderation adapters** (#67): `LlamaGuardImageDetector`
+  (Llama-Guard-3-11B-Vision) and `LlamaGuardTextDetector` (Llama-Guard-3-8B) now run
+  the model instead of raising `NotImplementedError`. They lazy-load, place the model
+  through cortex's `resolve_device`, and score each flagged category with P(unsafe) at
+  the verdict token. `parse_guard_output` reads the verdict. The checkpoints are gated
+  (`HF_TOKEN`); the README covers the licenses. `[moderation]` now needs
+  `transformers>=4.45`.
+
+### Changed
+- **The wire schema lists defaulted fields as required where proof always sends them**
+  (#58), like curator's `RESPONSE_ONLY`: the `EvalReport` tree, `RunManifest`, `ReportSummary`,
+  the stream frames, `GateResult`, `RejectArchive` and the grid plan. Models a client
+  builds (`RunSpec`, the configs, `SamplingParams`, `RejectReason`, `ProgressEvent`) are
+  unchanged. Payloads and validation are the same; generated client types get stricter.
+
+### Fixed
+- **A run is refused instead of silently dropping a value** (#60) when the template
+  has no slot for it: a non-empty negative prompt (`$negative`, which Flux templates
+  don't have), `guidance` (`$guidance`), or `clip_skip` above 2 (`$clip_skip`). The
+  `diffusers` and `a1111` backends refuse `guidance`. ComfyUI renders validate before
+  the first seed is queued.
+- **`clip_skip` 1 no longer selects CLIP's last layer** (#60, as darkroom #19): ComfyUI
+  gets `-max(clip_skip, 2)`, so 1 and 2 both mean the penultimate layer SDXL uses.
+  `-1` blanked some SDXL checkpoints. A rerun of an older `clip_skip: 1` manifest
+  now renders at layer -2.
+- **Moderation no longer reads as safe when a Guard model can't load** (#67).
+  `PolicyModerator` re-raises `ModerationError` (a gated checkpoint with no token, an
+  unreadable verdict) instead of skipping the detector as flaky. Other per-item errors
+  are still skipped.
+- README drift (#65): the policy-moderation section lists the `sexual` category;
+  the route list adds `/health`, `/scorers` and `/report/{run_id}/image_at/{index}`;
+  the CLI section documents `argus-proof schema [--check]`; the `gate` example is
+  copy-pasteable and mentions `--confidence`; the experiment sample cell id is
+  corrected; the diffusers limitations and the ImageReward-less default scorer set
+  are noted.
+
 ## [0.2.2] - 2026-10-26
 
 ### Added
@@ -87,7 +153,8 @@ First release: the MVP evaluation pipeline for trained LoRAs.
   `/run/stream`, report/HITL/refine endpoints, and model and export listings.
 - Container image `ghcr.io/smk762/argus-proof`.
 
-[Unreleased]: https://github.com/smk762/argus-proof/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/smk762/argus-proof/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/smk762/argus-proof/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/smk762/argus-proof/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/smk762/argus-proof/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/smk762/argus-proof/compare/v0.1.0...v0.2.0

{argus_proof-0.2.2 → argus_proof-0.3.0}/CLAUDE.md

@@ -13,6 +13,16 @@ argus-quarry -> argus-curator -> argus-lens -> argus-forge -> your trainer -> ar
 
 **The forge→proof handoff is a soft join, not an embed.** A `RunManifest` links back to the curator export via `source_manifest` (the `manifest.jsonl`) and, when the LoRA came through the suite, to forge's `training_run_id` (== forge `RunEvent.run_id`). Both are optional — a LoRA can be supplied ad hoc. Proof owns its own `run_id` (the eval run), distinct from the forge training run. README.md is the source of truth for behaviour; it is unusually detailed.
 
+## Argus suite
+<!-- argus-suite: keep this block; argus-ci checks for it -->
+This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
+building something a sibling may already do. **On every release, update this repo's row and capabilities in
+argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
+
+@../argus-core/SUITE.md
+
+Not checked out? Read https://github.com/smk762/argus-cortex/blob/main/SUITE.md
+
 ## Layout
 
 `src/argus_proof/`:
@@ -39,7 +49,7 @@ Run a single test: `uv run --no-sync pytest tests/test_scoring.py::test_name -q`
 
 ## Conventions & gotchas
 
-- **The wire schema is checked in CI** (`argus-proof schema --check` runs post-test). If you touch `WIRE_MODELS`/types in `models.py`, regenerate: `argus-proof schema > schema/proof-wire.schema.json`. Bump `PROOF_VERSION` (minor = additive field/metric, major = breaking) and mind `SUPPORTED_PROOF_MAJORS`.
+- **The wire schema is checked in CI** (`argus-proof schema --check` runs post-test). If you touch `WIRE_MODELS`/types in `models.py`, regenerate with `argus-proof schema` (it writes `schema/proof-wire.schema.json` itself; don't redirect stdout into it, which appends its status line). Bump `PROOF_VERSION` (minor = additive field/metric, major = breaking) and mind `SUPPORTED_PROOF_MAJORS`.
 - **Pass-rate is computed over near-duplicate *groups*, not raw frames** (`n_passed / n_groups`), so a Monte-Carlo cluster counts once. Never revert this to per-image — it's the core anti-inflation invariant. `n_groups == n_images` when no deduper ran.
 - **Scorers return normalised `[0,1]` (higher = better) or `None`** — never a fabricated `0.0` for an axis that didn't run. At most one scorer per metric (`METRIC_FIELDS`); the orchestrator raises if two target the same one. The `[0,1]` quality-scorer normalisation `lo`/`hi` defaults are **placeholders** — calibrate against real generations.
 - **Every model file is pinned by SHA256** in the `RunManifest`, not by filename — a run must reconstruct exactly. Backends resolve a requested name to a file and hash it; don't record a name without its digest. `RejectArchive`/`RejectRecord` are **image-free by construction** (keyed by `(run_id, seed)` — seed + manifest reconstructs the pixels); never add a path/thumbnail field there.
@@ -51,3 +61,7 @@ Run a single test: `uv run --no-sync pytest tests/test_scoring.py::test_name -q`
   - Concurrent report writes are serialised by a per-run `flock` sidecar (`reports.py`), so a streaming run's write and a reviewer's HITL save can't drop updates. On non-POSIX it degrades to a no-op — don't rely on it for multi-host.
 - Shared suite code (taxonomy, wire-schema tooling, the server write-guard/env-flag helpers, `RemoteBackend`) lives in **argus-cortex** (`argus-cortex[server]`) — reuse it, don't re-implement.
 - Versioning is git-tag-derived (`hatch-vcs`); `_version.py` is generated (gitignored). `structlog` logging, Pydantic v2, async server (`asyncio_mode = auto`), ruff line-length 120. Scaffolded from `argus-pkg-template` — `copier update` pulls tooling changes.
+
+## Branches
+
+`dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never open a PR against `main` or push work to it directly: `main` must never be ahead of `dev`. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected and needs a PR, merge the release PR, then immediately merge `main` back into `dev` so the merge commit is not left on `main` alone.

{argus_proof-0.2.2 → argus_proof-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-proof
-Version: 0.2.2
+Version: 0.3.0
 Summary: Post-training LoRA evaluation and optimisation: generate samples from a trained LoRA and score them against the curated dataset it was trained from
 Project-URL: Repository, https://github.com/smk762/argus-proof
 Author: smk762
@@ -46,7 +46,7 @@ Provides-Extra: moderation
 Requires-Dist: accelerate>=0.27; extra == 'moderation'
 Requires-Dist: pillow>=10.0; extra == 'moderation'
 Requires-Dist: torch>=2.0; extra == 'moderation'
-Requires-Dist: transformers>=4.43; extra == 'moderation'
+Requires-Dist: transformers>=4.45; extra == 'moderation'
 Provides-Extra: opt
 Requires-Dist: optuna>=3.0; extra == 'opt'
 Provides-Extra: score
@@ -68,7 +68,12 @@ Requires-Dist: krippendorff>=0.6; extra == 'stats'
 Requires-Dist: polars>=1.0; extra == 'stats'
 Description-Content-Type: text/markdown
 
-# argus-proof
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/proof/argus-proof-lockup-dark.svg">
+    <img alt="argus-proof" src="https://raw.githubusercontent.com/smk762/argus-cortex/dev/brand/packages/proof/argus-proof-lockup-light.svg" height="52">
+  </picture>
+</h1>
 
 Post-training LoRA evaluation and optimisation: generate samples from a trained LoRA and score them against the curated dataset it was trained from.
 
@@ -113,30 +118,56 @@ argus-proof report proof-l00-w00-p000 [--json]
 # Summarise an export dir (prompt sources) or a run dir (manifest + images):
 argus-proof inspect ./curated_export
 argus-proof inspect runs/proof-l00-w00-p000
+
+# Emit the wire-contract JSON Schema consumers codegen against (default
+# schema/proof-wire.schema.json; --check exits non-zero if the committed copy is stale):
+argus-proof schema [--output PATH] [--check]
 ```
 
+`gate`, `recommend`, `experiment` and `explore` are covered in their own sections below.
+
 ## Serve
 
 ```bash
 argus-proof serve --port 8104 --cors   # peer to lens :8100, curator :8101, quarry :8102, forge :8103
 argus-proof serve --read-only          # replay/demo mode: serve stored reports, 403 live eval + writes
-curl -s localhost:8104/health          # {"status":"ok","service":"argus-proof","version":"...","read_only":false}
+curl -s localhost:8104/health          # {"status":"ok","service":"argus-proof","version":"...","read_only":false,"capabilities":["report_manifest"]}
 ```
 
 Routes (the backend of the argus-studio `/proof` view):
 
 ```
+GET  /health                            liveness + version + read_only flag + capabilities
 GET  /exports                           curator export dirs available to evaluate against
 GET  /models                            checkpoints + LoRAs under $PROOF_MODELS_DIR
-POST /run/stream                        generate + score + store one run (NDJSON progress)
+GET  /scorers                           scorers a run applies + whether each is installed
+POST /run/stream                        generate + score + store one run (NDJSON RunStreamFrame lines)
 GET  /reports                           stored report digests (run browser)
 GET  /report/{run_id}                   full EvalReport            PUT to store one
+GET  /report/{run_id}/manifest          the RunManifest behind a report (410 if its run dir is gone)
 GET  /report/{run_id}/refined           passing subset, refined ranks first
 GET  /report/{run_id}/image/{image_id}  a generated sample (ids only — no path input)
+GET  /report/{run_id}/image_at/{index}  sample by position — seed-free URL for blind review
 POST /report/{run_id}/hitl              apply a review; recomputes pass-rate + verdict
 POST /report/{run_id}/refine            second-pass re-rank (rank: null retracts)
+POST /purge/{run_id}                    devmode only: delete one run's report + run dir
+POST /purge                             devmode only: delete every report + run dir
 ```
 
+`/report/{run_id}/manifest` serves the SHA256-pinned setup (checkpoint, VAE,
+LoRAs, sampling, prompt, seeds) so a client can carry a passed run forward, e.g.
+studio's proof → darkroom handoff. It is `404` when there is no report and `410
+Gone` when the report was kept but the run dir was pruned. `/health` lists
+`report_manifest` in `capabilities`, so a client can tell an older proof (route
+absent) from a run with no manifest.
+
+The `/purge` routes are a dev tool, since reports are the evaluation record. They exist
+only with `ARGUS_PROOF_DEVMODE=1` (or `serve --devmode`), need a `{"confirm": "purge"}`
+body, return `409` while the run (or, for `POST /purge`, any run) is still generating,
+and read-only mode refuses them. A run's HITL review and refinement are stored in its
+report, so they go with it. `/health` echoes `devmode` and lists `purge` in
+`capabilities` only when the routes will work.
+
 Concurrent reviews of the same run are serialised with a per-run file lock, so
 a streaming run's report write and a reviewer's HITL save can't drop updates.
 
@@ -178,6 +209,25 @@ checkpoint/LoRA by **SHA256** so the run reconstructs exactly. See
 [`templates/comfyui_sdxl_lora.json`](src/argus_proof/templates/comfyui_sdxl_lora.json)
 for the shipped example.
 
+**SDXL and Flux.** The template is chosen by the base checkpoint's *family*, its
+top-level folder under `checkpoints/`: `flux/…` renders
+[`templates/comfyui_flux_lora.json`](src/argus_proof/templates/comfyui_flux_lora.json)
+and every other family renders the SDXL template, so one server evaluates both.
+`PROOF_WORKFLOW_TEMPLATE` replaces both for every checkpoint. The Flux checkpoints
+are bare transformers, so the Flux template loads `t5xxl_fp8_e4m3fn.safetensors`
+and `clip_l.safetensors` (`DualCLIPLoader`, type `flux`) and `ae.safetensors`
+(`VAELoader`) by those names; they must be in ComfyUI's `clip/` and `vae/`
+folders. Flux takes no negative prompt (the template zeroes the positive) and runs
+at `cfg` 1 with `sampling.guidance` (the `$guidance` slot, a `FluxGuidance` node).
+A request that leaves `cfg`/`sampler`/`scheduler`/`guidance` out gets its family's
+defaults: SDXL cfg 7, `dpmpp_2m`/`karras`; Flux cfg 1, `euler`/`simple`, guidance 3.5.
+
+Nothing a run sets is silently dropped. A run is refused when it sets a value
+the template has no slot for: a VAE, a non-empty negative prompt, `guidance`,
+or a `clip_skip` above 2. The `diffusers` and `a1111` backends refuse `guidance`
+outright. `clip_skip` is sent to ComfyUI as `-max(clip_skip, 2)`: SDXL uses the
+penultimate layer, and `-1` blanks some checkpoints.
+
 **More backends.** `get_backend(name, ...)` selects the engine by config
 (`PROOF_BACKEND` in [`.env.example`](.env.example)); scoring/report code is
 unchanged regardless of which produced the run, and the `RunManifest` records the
@@ -185,6 +235,10 @@ engine + version:
 
 - **`diffusers`** — in-process diffusers SDXL pipeline: deterministic, no external
   service, weights hashed from disk (`pip install "argus-proof[diffusers]"`).
+  Limitations: `clip_skip` is not applied, and only a handful of samplers map to a
+  diffusers scheduler (`euler`, `euler_a`, `ddim`, `dpmpp_2m`, `unipc`; unknown
+  names fall back to the pipeline default). The manifest still records the
+  *requested* values, so compare across engines with care.
 - **`a1111`** — an AUTOMATIC1111 / SD.Next `/sdapi` server (checkpoint via
   `override_settings`, LoRAs via `<lora:…>` prompt syntax; models hashed from disk).
 - **`remote`** — a hosted/cloud endpoint that speaks the proof wire (`POST /generate`
@@ -222,6 +276,12 @@ skips it when the extra is absent). Shipped:
 - **quality / adherence** — `clip_score_scorer()` (CLIPScore), `pyiqa_scorer()` (CLIP-IQA), `image_reward_scorer()` (ImageReward), each normalising its raw score to `[0,1]`
 - **safety** — `SafetyScorer` (NudeNet ensemble, `1 - unsafe`); set a `safety` hard gate to auto-fail unsafe images. `safety_tail_aggregate()` surfaces the any-hit/min/percentile tail. NudeNet runs as a **server over HTTP** (`PROOF_NUDENET_URL`, via argus-cortex's `NudeNetClient`), never in-process (it is AGPL-3.0); without a URL the scorer is skipped. "Unsafe" is the suite's exposed-nudity set (exposed buttocks, breasts, genitalia, anus), the same as curator's
 
+The default scorer set used by `argus-proof run` / `score` and the server
+(`evaluate.default_scorers()`, plus phash dedup/diversity) is identity, CLIPScore,
+CLIP-IQA and safety — it does **not** include ImageReward, so the `preference`
+metric stays empty unless you pass `image_reward_scorer()` via the library API.
+`GET /scorers` reports which of the default set this install can actually run.
+
 ```python
 from argus_proof.scoring import score_run
 from argus_proof.scoring.scorers import (
@@ -270,15 +330,42 @@ best_first = refined_ranking(refined)   # passing subset, refined re-ranks on to
 ## Policy moderation (optional)
 
 The Phase-2 `safety` scorer catches **nudity**; `argus_proof.moderation` extends
-it to a **Guard-class policy taxonomy** (violence / hate / self-harm / weapons /
-illegal) — over both the **generated images** and the **input prompts /
-captions**, so a toxic prompt is flagged even when its output is clean
-(`pip install "argus-proof[moderation]"`, Llama Guard 3 Vision):
+it to a **Guard-class policy taxonomy** (sexual / violence / hate / self-harm /
+weapons / illegal) — over both the **generated images** and the **input prompts /
+captions**, so a toxic prompt is flagged even when its output is clean.
+
+The default detectors are **Llama Guard 3**: `LlamaGuardImageDetector`
+(`meta-llama/Llama-Guard-3-11B-Vision`, about 22 GB in bf16) for outputs and
+`LlamaGuardTextDetector` (`meta-llama/Llama-Guard-3-8B`, about 16 GB) for prompts and
+captions. Install `argus-proof[moderation]`. Both checkpoints are **gated** on Hugging
+Face: accept the license on each model page and set `HF_TOKEN`. The weights download
+at first use; nothing is bundled. Device placement goes through argus-cortex's
+`resolve_device` (`device="auto"` picks cuda, then mps, then cpu).
+
+Each verdict (`safe`, or `unsafe` plus hazard codes `S1`–`S14`) maps onto the taxonomy.
+A flagged category scores P(unsafe) at the verdict token rather than a hard 1.0.
+Moderation fails loud rather than reading as safe. A model that can't load (no
+token, license not accepted) or an unreadable verdict raises `ModerationError`, and an
+`unsafe` verdict naming no code flags every category. An image is sent with the
+neutral prompt `"Describe this image."`, so a flag comes from the image.
+
+> **Licenses.** Llama-Guard-3-8B is under the Llama 3.1 Community License, and
+> Llama-Guard-3-11B-Vision under the Llama 3.2 Community License. The 3.2 license
+> does **not** grant its rights for multimodal models to individuals domiciled in,
+> or companies with their principal place of business in, the European Union
+> (end users of a product built on them are exempt). Both carry Meta's acceptable
+> use policy. argus-proof only downloads the weights at runtime and doesn't
+> redistribute them. Check the terms against your use, and pass your own detectors
+> if they don't fit.
+
+Any object with `name`, `version`, `is_available()` and `moderate_image(path)` /
+`moderate_text(text)` returning per-category `[0,1]` scores can replace them:
 
 ```python
 from argus_proof.moderation import PolicyModerator, moderate_images, moderate_texts
 
-mod = PolicyModerator()                         # default: Llama Guard 3 (lazy, [moderation])
+mod = PolicyModerator()                          # Llama Guard 3 Vision + text
+# mod = PolicyModerator(image_detectors=[MyImageGuard()], text_detectors=[MyTextGuard()])
 out = moderate_images(image_paths, mod)         # per-category tails over the outputs
 inp = moderate_texts(prompt_grid_variants, mod) # ...and over the inputs
 out.flagged()                                   # e.g. ["violence", "hate"], worst first
@@ -288,8 +375,9 @@ report.scorers.append(mod.provenance("output")) # version-stamp the Guard model
 Each category gets a **tail** view (any-hit / max / 95th percentile — the extremes
 that matter, not the mean, same rule as `safety`), combined conservatively across
 an ensemble (most-unsafe detector wins). Detectors are pluggable and injectable, so
-the taxonomy/ensemble/tail logic is dependency-free and unit-tested; only the real
-Llama Guard adapter needs the extra. A reviewer's HITL flag attributes to a
+the taxonomy/ensemble/tail logic is dependency-free and unit-tested. Of the Llama
+Guard adapters, only the model call needs the `[moderation]` extra; verdict parsing
+and mapping are unit-tested. A reviewer's HITL flag attributes to a
 category via `RejectReason.category`. CSAM matching stays a **separate** policy gate
 (Thorn Safer / PhotoDNA), not an ML metric here.
 
@@ -300,11 +388,15 @@ gate` evaluates a scored `EvalReport` against declared thresholds and **exits
 non-zero when rejected**, so it drops straight into CI:
 
 ```bash
+# --min-pass-rate-ci-lower: Wilson lower bound — a lucky 3/3 won't pass
+# --confidence: confidence level for that bound (default 0.95)
+# exit 0 = accepted, 1 = rejected, 2 = unreadable report / invalid threshold
 argus-proof gate eval_report.json \
   --min-pass-rate 0.75 \
-  --min-pass-rate-ci-lower 0.7 \   # Wilson lower bound — a lucky 3/3 won't pass
+  --min-pass-rate-ci-lower 0.7 \
+  --confidence 0.95 \
   --min-identity 0.6 \
-  --max-unsafe-rate 0.0            # exit 0 = accepted, 1 = rejected, 2 = unreadable
+  --max-unsafe-rate 0.0
 ```
 
 The pass-rate lower bound uses a Wilson score interval (`argus_proof.stats`, no
@@ -375,7 +467,7 @@ with a `--max-gpu-hours` guardrail that refuses an intractable matrix:
 ```bash
 argus-proof experiment matrix.json --export ./curated_export --max-gpu-hours 40
 # experiment exp: 4 cells, 32 runs, 96 images
-#   [exp-c00sdxl-a-fast] 24 images (8 runs)
+#   [exp-c00-sdxl-a-fast] 24 images (8 runs)
 #   ...
 # est. 0.2 GPU-hours @ 6s/image
 ```