argus-cortex 0.4.6__tar.gz → 0.5.0__tar.gz

argus_cortex-0.5.0/.cursor/rules/agent-coding-packs.mdc

@@ -0,0 +1,29 @@
+---
+description: Fetch ai-code-auditor coding packs for argus-cortex 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-cortex` 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-cortex`
+   (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-cortex`.
+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`).
+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-cortex","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/.env.example

@@ -19,3 +19,8 @@ CORTEX_S3_ACCESS_KEY=
 CORTEX_S3_SECRET_KEY=
 CORTEX_S3_BUCKET=argus
 CORTEX_S3_REGION=us-east-1
+
+# ── 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_cortex-0.4.6 → argus_cortex-0.5.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_cortex-0.5.0/AGENTS.md

@@ -0,0 +1,24 @@
+<!-- ai-audit:agent-packs:start -->
+## Agent coding packs (ai-code-auditor)
+
+Do not wait for a pasted brief — fetch the audit packs for `argus-cortex` 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-cortex`
+   (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-cortex`.
+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`).
+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-cortex","patch":"<diff>","pack_id":"<id>"}`
+   — a passing run marks the pack `resolved`.
+
+World-model constraints (ownership, boundaries, scan branch `dev`) win over guesswork.
+Full flow: ai-code-auditor `AGENTS.md`.
+<!-- ai-audit:agent-packs:end -->

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-14
+
+### Added
+- **`argus_cortex.provenance`.** `Provenance`, `ProvenanceKind` and `CLEARED_KINDS`, hoisted from
+  argus-mask so every package that stores where a face, voice or image came from reads one shape,
+  with a committed `provenance-schema.json` (#35).
+- **`argus_cortex.consent`.** `ConsentRecord`, a real person's likeness release as argus-mask#26
+  defined it, keyed by the `release_sha256` a `consented` `Provenance` names. `consent_valid()`
+  returns a `ConsentVerdict` with one of a closed set of refusal codes, checked in a fixed order
+  (`revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`,
+  `delivery-not-covered`), so every stage refuses for the same reasons. `consent_matches()` checks
+  that a record is the release and subject a provenance names. Committed `consent-schema.json` (#53).
+  A record is frozen and its sequences are tuples, so it cannot be changed after its checks pass.
+  It is refused when the age check names nobody or comes after signing, when a revocation is
+  requested before signing, or when a listed voice delivery is blank (#56).
+- **`Provenance.generator`.** An optional `model`, `model_sha256`, `seed` and `prompt` for how a
+  generated source was made, allowed only on `synthetic` and `personal` sources (#53).
+
+### Changed
+- **`Provenance` is strict, as argus-mask's is (argus-mask#64).** Unknown fields are refused instead
+  of dropped (`additionalProperties: false` in the schema). `licence` is read as `license`; both given
+  and different is refused. A `source` of only whitespace is refused. The derived `cleared` in a dumped
+  record is dropped on read and recomputed.
+- **README:** lists the `[images]` and `[gpu]` extras, `ARGUS_GPU_DEVICE`, and the moderation policy
+  names with their illegal-rule letters (#42).
+
+## [0.4.7] - 2026-11-13
+
+### Added
+- **`concept` target category.** `TargetCategory` gains `concept`, a style or
+  visual-concept LoRA, matching argus-quarry's `concept` subjects. It is
+  additive, but a stage that keys tables by category (forge's heuristics, curator's
+  scanner) must add an entry before it accepts it.
+- **Committed `taxonomy-schema.json`.** Generated from `TargetProfile` by the new
+  `taxonomy_schema()` (`make schema`), with a test that fails when it drifts from
+  `taxonomy.py`, so non-Python clients such as studio generate their types instead
+  of copying the literals (#29).
+- **`SUITE.md`, the suite map for agents.** Every Argus repo, its port and purpose,
+  and a "Need it? Use it" index. Each repo's `CLAUDE.md` imports it (#33).
+
 ## [0.4.6] - 2026-11-06
 
 ### Changed
@@ -215,7 +255,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     (`LocalBackend`, `RemoteBackend`, `RemoteProvider`, `with_retries`
     retrying only transient errors, `resolve_device`).
 
-[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.4.6...HEAD
+[Unreleased]: https://github.com/smk762/argus-cortex/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/smk762/argus-cortex/compare/v0.4.7...v0.5.0
+[0.4.7]: https://github.com/smk762/argus-cortex/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/smk762/argus-cortex/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/smk762/argus-cortex/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/smk762/argus-cortex/compare/v0.4.3...v0.4.4

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/CLAUDE.md

@@ -4,17 +4,27 @@ Guidance for AI agents working in this repo. Human-facing usage lives in [README
 
 ## What this is
 
-The **shared foundation library** of the Argus suite (quarry → curator → lens → forge → proof). It holds the code the stages *share* so it lives in one place instead of copy-pasted per repo: the target taxonomy, the wire-schema versioning discipline, the local/remote AI-backend contract, and the optional stateful-services layer.
+The **shared foundation library** of the Argus suite. It holds the code the stages *share* so it lives in one place instead of copy-pasted per repo: the target taxonomy, the wire-schema versioning discipline, the local/remote AI-backend contract, and the optional stateful-services layer.
 
 Naming: the working directory is `argus-core`, but the GitHub repo, the PyPI package, and the import name are all **`argus-cortex`** (`src/argus_cortex/`). Don't "fix" the mismatch.
 
 Because everything here is imported by the downstream stages, **a change ripples across the whole suite** — treat this repo as an API, not a leaf. Read [README.md](README.md) for the *why* and worked examples; it is the source of truth for behaviour.
 
+## Argus suite
+<!-- argus-suite: keep this block; argus-ci checks for it -->
+Cortex owns the suite map, [SUITE.md](SUITE.md), which every repo's CLAUDE.md imports. **Keep it accurate:** a cortex
+release that adds or changes a shared module updates its "Need it? Use it" row, and PRs from other repos that update
+their own rows land here. Keep it short, because it is loaded into every session in every repo.
+
+@SUITE.md
+
 ## Layout
 
 `src/argus_cortex/` (top level is pydantic-only; everything heavier is behind an extra and lazily imported):
 
-- `taxonomy.py` — the "moat" types every stage inherits verbatim: `TargetProfile`, `TargetStyle`/`TargetCategory` literals. Keep it dependency-light; a change here retrains everyone's expectations.
+- `taxonomy.py` — the "moat" types every stage inherits verbatim: `TargetProfile`, `TargetStyle`/`TargetCategory` literals, and `taxonomy_schema()` (the source of the committed `taxonomy-schema.json`). Keep it dependency-light; a change here retrains everyone's expectations.
+- `provenance.py` — `Provenance`/`ProvenanceKind`/`CLEARED_KINDS` for face, voice and image sources, hoisted from argus-mask (#19/#57): `personal` (never cleared) vs cleared `stock`/`synthetic`/`consented` (licence required; `consented` needs `subject` + `release_sha256`); `curated` reserved. **argus-mask owns the meaning of each field — change it only in step with mask.** Optional `generator` (model, sha256, seed, prompt) on `synthetic`/`personal` only. `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; drift-tested).
+- `consent.py` — `ConsentRecord` (keyed by `release_sha256`, the join to a `consented` `Provenance`), `consent_valid()` → `ConsentVerdict` with a closed `ConsentRefusal` reason (checks in a fixed order; the first failure wins), `consent_matches()`, and `consent_schema()` → the committed `consent-schema.json`. Defined in argus-mask#26; **mask owns the meaning — change it only in step with mask.** `consent_valid` takes `at` from the caller (tz-aware, compared as a UTC day) and never reads the clock; an unknown use is refused, not raised. A record names a person: services return verdicts, never records.
 - `wire.py` — the versioned wire-schema toolkit consumers build their contracts on: `make_versioned_base(field_name, current, majors)` (a Pydantic base that stamps + version-checks a field like `proof_version`/`manifest_version`), `check_version()` (the major-compatibility gate), `render_schema()`/`wire_schema()` (the canonical committed-schema string behind each consumer's `schema --check` CLI), and `VersionError`.
 - `backends.py` — the AI-backend contract: `Backend`/`LocalBackend`/`RemoteBackend` (point at a hosted service via `from_host(host, port)` or `from_provider(RemoteProvider.…)`), plus `with_retries()` and `resolve_device()`. httpx is lazy, behind `[remote]`.
 - `server.py` — the shared FastAPI/ASGI scaffolding other repos' micro-servers mount: `WriteGuard` (pure-ASGI method gate), the `constant_refuse()` (read-only/replay) and `cross_site_refuse()` (cross-origin write) predicates, `env_flag()`, and the `UNSAFE_METHODS`/`TRUTHY`/`FALSY` constants. Starlette is behind `[server]`.
@@ -23,7 +33,7 @@ Because everything here is imported by the downstream stages, **a change ripples
 - `moderation/` — content-moderation clients over HTTP: `nudenet.py` (`NudeNetClient`, `NsfwResult`, `DEFAULT_EXPOSED_LABELS` — **the suite's one definition of nudity; don't widen it casually**, every stage's NSFW numbers move with it), `singguard.py` (`SingGuardClient` incl. text-only `check_text()`, `GuardResult`, `rule_matches`), `policies.py` (the named policy texts, the per-policy illegal-rule table and `mode()`: `default`/`sfw-*` are SFW — **a policy's text and its illegal letters change together**), `_http.py` (shared POST, proxy-free opener, `CheckFailed`/`ModerationConfigError`). Stdlib + pydantic; Pillow lazily, behind `[images]`. Never import NudeNet (AGPL) — HTTP only. URLs are passed in; stages own their env config.
 - `store/` — the optional stateful-services layer, opt-in per `CORTEX_*` env var: `lineage.py` (Phase 1 Postgres DAG, `open_lineage_store()`), `vector.py` (Phase 2 Qdrant, `open_vector_store()`), `blob.py` (Phase 3 MinIO/S3, `open_blob_store()`), over `config.py`/`models.py`/`errors.py`. Each `open_*()` returns a `Null*` no-op when its URL is unset. Drivers are behind `[postgres]`/`[qdrant]`/`[s3]`.
 
-There is **no CLI and no committed schema in this repo** — the `schema`/`schema --check` pattern is something `wire.py` *enables* for downstream repos, not something cortex runs on itself.
+There is **no CLI in this repo**. The committed schemas are `taxonomy-schema.json` (from `taxonomy_schema()`), `provenance-schema.json` (from `provenance_schema()`) and `consent-schema.json` (from `consent_schema()`); `make schema` regenerates all three and `tests/test_taxonomy.py` / `tests/test_provenance.py` / `tests/test_consent.py` fail when one is stale. Studio generates its taxonomy types from the first, so a `taxonomy.py`, `provenance.py` or `consent.py` change needs `make schema` in the same commit.
 
 ## Commands
 
@@ -45,6 +55,10 @@ Run one test: `uv run --no-sync pytest tests/test_wire.py::test_name -q`.
 - **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_cortex/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
 - Pydantic v2 everywhere; async tests via `asyncio_mode = auto`. Ruff pinned **0.15.16**, line-length 120, target py311.
 
+## 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 push work to `main` or open a PR against it, except the release PR from `dev`: `main` must never be ahead of `dev`, with one exception. 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, the release is a reviewed PR from `dev` into `main`, and merging it leaves a merge commit on `main` alone. That merge commit is the one exception to the rule: it leaves `main` one commit ahead of `dev` with an identical tree. Leave it there and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty). Once `main` carries such a commit it can't be fast-forwarded, so later releases are PRs too.
+
 ## CI / release
 
 CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow (ruff + pytest with the `dev` extra — which installs the real psycopg/qdrant/minio/starlette clients so each store's live driver path is exercised, not just fakes). Release publishes to PyPI (OIDC trusted publishing) on `v*` tags — **no container image, this is a library**. Scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template); run `copier update` to pull tooling changes.

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/Makefile

@@ -1,6 +1,6 @@
 UV ?= uv
 
-.PHONY: help install lint format test build clean
+.PHONY: help install lint format test schema build clean
 
 help:  ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
@@ -20,6 +20,9 @@ format:  ## Ruff autoformat + autofix
 test:  ## Run the test suite
 	$(UV) run --no-sync pytest --tb=short -q
 
+schema:  ## Regenerate the committed taxonomy-schema.json, provenance-schema.json and consent-schema.json
+	$(UV) run --no-sync python -c "from pathlib import Path; from argus_cortex.taxonomy import taxonomy_schema; from argus_cortex.provenance import provenance_schema; from argus_cortex.consent import consent_schema; [Path(f).write_text(r(), encoding='utf-8') for f, r in (('taxonomy-schema.json', taxonomy_schema), ('provenance-schema.json', provenance_schema), ('consent-schema.json', consent_schema))]"
+
 build:  ## Build sdist + wheel
 	$(UV) build
 

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-cortex
-Version: 0.4.6
+Version: 0.5.0
 Summary: Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract
 Project-URL: Repository, https://github.com/smk762/argus-cortex
 Author: smk762
@@ -51,17 +51,19 @@ Description-Content-Type: text/markdown
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
-Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (quarry → curator → lens → forge → proof). This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
+Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/dev/SUITE.md) lists every repo, what it owns, and how they fit together. This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
 
 ## What's here
 
-- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim. `taxonomy_schema()` renders them into the committed `taxonomy-schema.json` (`make schema` regenerates it; a test fails when it is stale), so non-Python clients generate their types instead of copying the literals.
+- **`argus_cortex.provenance`**: `Provenance` / `ProvenanceKind`, where a face, voice or image came from (the shape argus-mask#19 defined). `personal` needs only a `source` and is never `cleared`; `stock`, `synthetic` and `consented` are cleared, each states its licence, and `consented` also names its `subject` and the `release_sha256` of the signed release (never the document). `curated` is reserved and not cleared. Strict: unknown fields and a blank `source` are refused, `licence` is read as `license`, and a stored `cleared` is recomputed. A `synthetic` or `personal` source may name its `generator` (`model`, `model_sha256`, `seed`, `prompt`; optional, refused on other kinds). `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; a test fails when it is stale).
+- **`argus_cortex.consent`**: a real person's likeness release, as argus-mask#26 defined it. `ConsentRecord` is keyed by the `release_sha256` a `consented` `Provenance` names, and holds the subject, who collected it, signing and expiry dates (expiry must be stated, `null` for none), the age check (who and when, never the ID), the `face`/`voice` opt-ins, voice `deliveries`, `uses` (`avatar`, `video`, `speech`, `training`; training is off unless listed), sha256s of the reference images and recordings, revocation terms and any `revocation`. `consent_valid(record, use=, likeness=, at=, delivery=)` returns a `ConsentVerdict` (`ok`, `reason`, `detail`), checking in order `revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`, `delivery-not-covered`; `at` must be timezone-aware and dates compare as UTC days, so the check never reads the clock. `consent_matches(record, provenance)` checks the record is the release and subject a provenance names. A record names a person, so services return only verdicts, never records. `consent_schema()` renders the committed `consent-schema.json`.
 - **`argus_cortex.wire`** — the versioned wire-schema toolkit: `check_version()` (major-compatibility gate), `make_versioned_base()` (a Pydantic base that stamps + checks a version field like `proof_version` / `manifest_version`), and `wire_schema()` / `render_schema()` for the committed-schema `schema --check` CLI pattern.
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
-- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib + pydantic only.
 - **`argus_cortex.moderation`** — the suite's content-moderation clients, over HTTP to servers the deployer runs (nothing here imports a detector): `NudeNetClient` (a NudeNet server's `/infer` → `NsfwResult`: detections, per-class maxima, and an **exposed score**) and `SingGuardClient` (a SingGuard server's `/api/guard/check` → `GuardResult`: verdict, the policy rules that fired, explanation; optional custom policy text). `DEFAULT_EXPOSED_LABELS` is the suite's **one definition of nudity**: the five exposed buttocks/breast/genitalia/anus classes — faces, covered parts, and bare feet, belly, armpits or male chest never count. Stdlib + pydantic; Pillow (for SingGuard's downscaling of large images, on by default) is behind `[images]`: without it `SingGuardClient(...)` raises `ModerationConfigError` at construction unless given `downscale=False`. A `user:password@` in a URL is sent as HTTP Basic auth. URLs are passed in, never read from the environment here: each stage owns its config. NudeNet itself is AGPL-3.0, which is why it stays behind an HTTP boundary.
-- **`argus_cortex.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing.
+- **`argus_cortex.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing. `ARGUS_GPU_DEVICE` (default `0`; an invalid value warns and falls back to `0`) picks which card NVML probes for free VRAM; the lock stays host-wide.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -75,7 +77,7 @@ from argus_cortex.backends import RemoteBackend, RemoteProvider
 _Versioned = make_versioned_base("proof_version", "1.0", ("1",))
 
 # reach a hosted scorer by IP/port, or a known provider
-scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
+scorer = RemoteBackend.from_host("<LAN_HOST>", 9000, api_key="…")  # real host/IP: local .env
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 
@@ -121,7 +123,17 @@ illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]
 policies.mode("adult-granular"), policies.mode("default")   # "nsfw", "sfw"
 ```
 
-Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW).
+Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW). The known names are `policies.POLICIES`; any other name raises `ModerationConfigError` (an `sfw-*` name gets mode `sfw` but has no text):
+
+| Policy | Mode | Illegal rules |
+|---|---|---|
+| `default` (SingGuard's own rules, no text sent) | sfw | none |
+| `adult` | nsfw | A |
+| `adult-granular` | nsfw | A, H, I |
+| `adult-cautious` | nsfw | A |
+| `adult-cinematic` | nsfw | A |
+
+`adult-granular`, `adult-cautious` and `adult-cinematic` are under evaluation against `adult`; one adult policy remains at release, beside `default`.
 
 ```python
 from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
@@ -191,6 +203,8 @@ uv pip install "argus-cortex[server]"    # + starlette for argus_cortex.server (
 uv pip install "argus-cortex[postgres]"  # + psycopg for the lineage store
 uv pip install "argus-cortex[qdrant]"    # + qdrant-client for the vector store
 uv pip install "argus-cortex[s3]"        # + minio for the blob store
+uv pip install "argus-cortex[images]"    # + Pillow for SingGuardClient downscaling (on by default)
+uv pip install "argus-cortex[gpu]"       # + nvidia-ml-py for the GPU lease's free-VRAM probe
 ```
 
 The stateful services are configured via `CORTEX_*` env vars — see [`.env.example`](.env.example). Each is optional: leave a URL unset and that feature degrades to a no-op.

{argus_cortex-0.4.6 → argus_cortex-0.5.0}/README.md

@@ -2,17 +2,19 @@
 
 Shared foundation for the Argus suite: taxonomy, versioned wire-schema tooling, and the local/remote AI backend contract.
 
-Part of the [Argus suite](https://github.com/smk762?tab=repositories&q=argus) (quarry → curator → lens → forge → proof). This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
+Part of the Argus suite; [SUITE.md](https://github.com/smk762/argus-cortex/blob/dev/SUITE.md) lists every repo, what it owns, and how they fit together. This is the library the stages import so the code they *share* — the target taxonomy, the wire-schema versioning discipline, and the way they call local or hosted models — lives in one place instead of being copy-pasted per repo.
 
 ## What's here
 
-- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim.
+- **`argus_cortex.taxonomy`** — `TargetProfile` / `TargetStyle` / `TargetCategory`, the "moat" types every stage inherits verbatim. `taxonomy_schema()` renders them into the committed `taxonomy-schema.json` (`make schema` regenerates it; a test fails when it is stale), so non-Python clients generate their types instead of copying the literals.
+- **`argus_cortex.provenance`**: `Provenance` / `ProvenanceKind`, where a face, voice or image came from (the shape argus-mask#19 defined). `personal` needs only a `source` and is never `cleared`; `stock`, `synthetic` and `consented` are cleared, each states its licence, and `consented` also names its `subject` and the `release_sha256` of the signed release (never the document). `curated` is reserved and not cleared. Strict: unknown fields and a blank `source` are refused, `licence` is read as `license`, and a stored `cleared` is recomputed. A `synthetic` or `personal` source may name its `generator` (`model`, `model_sha256`, `seed`, `prompt`; optional, refused on other kinds). `provenance_schema()` renders the committed `provenance-schema.json` (`make schema`; a test fails when it is stale).
+- **`argus_cortex.consent`**: a real person's likeness release, as argus-mask#26 defined it. `ConsentRecord` is keyed by the `release_sha256` a `consented` `Provenance` names, and holds the subject, who collected it, signing and expiry dates (expiry must be stated, `null` for none), the age check (who and when, never the ID), the `face`/`voice` opt-ins, voice `deliveries`, `uses` (`avatar`, `video`, `speech`, `training`; training is off unless listed), sha256s of the reference images and recordings, revocation terms and any `revocation`. `consent_valid(record, use=, likeness=, at=, delivery=)` returns a `ConsentVerdict` (`ok`, `reason`, `detail`), checking in order `revoked`, `not-yet-signed`, `expired`, `likeness-not-covered`, `use-not-covered`, `delivery-not-covered`; `at` must be timezone-aware and dates compare as UTC days, so the check never reads the clock. `consent_matches(record, provenance)` checks the record is the release and subject a provenance names. A record names a person, so services return only verdicts, never records. `consent_schema()` renders the committed `consent-schema.json`.
 - **`argus_cortex.wire`** — the versioned wire-schema toolkit: `check_version()` (major-compatibility gate), `make_versioned_base()` (a Pydantic base that stamps + checks a version field like `proof_version` / `manifest_version`), and `wire_schema()` / `render_schema()` for the committed-schema `schema --check` CLI pattern.
 - **`argus_cortex.backends`** — the AI-backend contract generalised from argus-lens: `Backend` / `LocalBackend` / `RemoteBackend` (point at a hosted service by `base_url`, `host`/`port`, or a known `RemoteProvider`), plus `with_retries()` and `resolve_device()`. httpx lives behind the `[remote]` extra.
 - **`argus_cortex.server`** — shared write-guard + env-flag scaffolding for the suite's FastAPI micro-servers: `WriteGuard` (a pure-ASGI method-gate that never buffers streaming responses), the `constant_refuse()` / `cross_site_refuse()` predicates (read-only/replay mode and cross-site-write protection are two configs of the one guard), the `UNSAFE_METHODS` / `TRUTHY` / `FALSY` constants, and `env_flag()` (warns on a mistyped protection flag rather than silently disabling it). Starlette lives behind the `[server]` extra.
-- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib only.
+- **`argus_cortex.xmp`** — the suite's one XMP sidecar implementation (hoisted from argus-lens): `write_xmp()` / `read_xmp()` / `merge_xmp()` / `parse_xmp()` over an `XmpData` model covering `dc` (keywords, description), `xmp` (Rating, Label), `lr` (hierarchical keywords), `Iptc4xmpExt` (PersonInImage), `mwg-rs` face/pet regions, and `argus:ContentRating`. Writes **merge**: each property you set replaces that property (latest write wins), everything else in the sidecar — Lightroom develop settings, GPS, another stage's fields — is preserved. `None` leaves a property alone, an empty value removes it. Writes are atomic; an unparseable existing sidecar raises `XmpError` instead of being clobbered. Stdlib + pydantic only.
 - **`argus_cortex.moderation`** — the suite's content-moderation clients, over HTTP to servers the deployer runs (nothing here imports a detector): `NudeNetClient` (a NudeNet server's `/infer` → `NsfwResult`: detections, per-class maxima, and an **exposed score**) and `SingGuardClient` (a SingGuard server's `/api/guard/check` → `GuardResult`: verdict, the policy rules that fired, explanation; optional custom policy text). `DEFAULT_EXPOSED_LABELS` is the suite's **one definition of nudity**: the five exposed buttocks/breast/genitalia/anus classes — faces, covered parts, and bare feet, belly, armpits or male chest never count. Stdlib + pydantic; Pillow (for SingGuard's downscaling of large images, on by default) is behind `[images]`: without it `SingGuardClient(...)` raises `ModerationConfigError` at construction unless given `downscale=False`. A `user:password@` in a URL is sent as HTTP Basic auth. URLs are passed in, never read from the environment here: each stage owns its config. NudeNet itself is AGPL-3.0, which is why it stays behind an HTTP boundary.
-- **`argus_cortex.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing.
+- **`argus_cortex.gpu`**: GPU tenancy, generalised from argus-lens. `coordinator_from_env()` returns a coordinator whose `lease(caller=, min_vram_mb=)` holds a GPU slot for a block of work. `none` (the default) grants every lease at once. `lease` takes an exclusive `flock` that every argus process on the host shares (one lock for the host, not per GPU), then waits until `free_vram_mb()` (NVML, behind `[gpu]`) reports `min_vram_mb` free across *every* process on the card, ComfyUI and Ollama included, which never take the lock. It raises `GpuLeaseTimeout` after `ARGUS_GPU_LEASE_TIMEOUT_S` (300 s). The VRAM check is a snapshot, not a reservation, and a probe that cannot run lets the lease through. Containers each have their own `/tmp`, so set `ARGUS_GPU_LEASE_PATH` to a file on a volume every GPU service mounts, or the lock coordinates nothing. `ARGUS_GPU_DEVICE` (default `0`; an invalid value warns and falls back to `0`) picks which card NVML probes for free VRAM; the lock stays host-wide.
 - **`argus_cortex.store`** — the optional **stateful services layer** (the suite's persistent "memory"). External and opt-in — every store is configured by `CORTEX_*` env vars and no-ops when its URL is unset.
   - **Phase 1 — Postgres lineage store.** Persists the `source_asset → caption → human_edit → dataset_membership → training_run` DAG for LoRA reproducibility, edit capture, and the feedback loop. Backed by a psycopg connection **pool** (concurrent `asyncio.to_thread` calls are safe; a dropped connection is replaced), with a `transaction()` boundary for atomic multi-step writes. `open_lineage_store()` returns a no-op store when `CORTEX_PG_URL` is unset; psycopg lives behind the `[postgres]` extra.
   - **Phase 2 — Qdrant vector store.** Stores image + tag-set embeddings for retrieval-augmented few-shot and near-duplicate curation; put a `caption_id`/`asset_id` in a point's payload and a search hit joins straight back to the lineage. `open_vector_store()` no-ops when `CORTEX_QDRANT_URL` is unset; qdrant-client lives behind the `[qdrant]` extra. cortex stores vectors it's *handed* — computing embeddings is the caller's job.
@@ -26,7 +28,7 @@ from argus_cortex.backends import RemoteBackend, RemoteProvider
 _Versioned = make_versioned_base("proof_version", "1.0", ("1",))
 
 # reach a hosted scorer by IP/port, or a known provider
-scorer = RemoteBackend.from_host("192.168.1.20", 9000, api_key="…")
+scorer = RemoteBackend.from_host("<LAN_HOST>", 9000, api_key="…")  # real host/IP: local .env
 nim = RemoteBackend.from_provider(RemoteProvider.NVIDIA_NIM, api_key="…")
 ```
 
@@ -72,7 +74,17 @@ illegal = [r for r in verdict.rules if policies.is_illegal("adult-granular", r)]
 policies.mode("adult-granular"), policies.mode("default")   # "nsfw", "sfw"
 ```
 
-Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW).
+Stages ask for a policy by name; `policies` holds each one's text, the rules that mean illegal content under it, and its SFW/NSFW mode (`default` and `sfw-*` are SFW). The known names are `policies.POLICIES`; any other name raises `ModerationConfigError` (an `sfw-*` name gets mode `sfw` but has no text):
+
+| Policy | Mode | Illegal rules |
+|---|---|---|
+| `default` (SingGuard's own rules, no text sent) | sfw | none |
+| `adult` | nsfw | A |
+| `adult-granular` | nsfw | A, H, I |
+| `adult-cautious` | nsfw | A |
+| `adult-cinematic` | nsfw | A |
+
+`adult-granular`, `adult-cautious` and `adult-cinematic` are under evaluation against `adult`; one adult policy remains at release, beside `default`.
 
 ```python
 from argus_cortex.gpu import GpuLeaseTimeout, coordinator_from_env
@@ -142,6 +154,8 @@ uv pip install "argus-cortex[server]"    # + starlette for argus_cortex.server (
 uv pip install "argus-cortex[postgres]"  # + psycopg for the lineage store
 uv pip install "argus-cortex[qdrant]"    # + qdrant-client for the vector store
 uv pip install "argus-cortex[s3]"        # + minio for the blob store
+uv pip install "argus-cortex[images]"    # + Pillow for SingGuardClient downscaling (on by default)
+uv pip install "argus-cortex[gpu]"       # + nvidia-ml-py for the GPU lease's free-VRAM probe
 ```
 
 The stateful services are configured via `CORTEX_*` env vars — see [`.env.example`](.env.example). Each is optional: leave a URL unset and that feature degrades to a no-op.

argus_cortex-0.5.0/SUITE.md

@@ -0,0 +1,102 @@
+# The Argus suite: map for agents
+
+The canonical list of every Argus repo: what each one is for, and which one already does the thing you are about to build.
+Every repo's `CLAUDE.md` imports this file. **Before designing a feature, check the "Need it? Use it" index.** If a
+sibling already does it, call that sibling (HTTP, or its library) instead of rebuilding it.
+
+**Keep it current. Every release of any Argus repo checks its row here.** If a release adds, removes or renames a
+capability, endpoint, port, UI pairing or dependency, open a PR to `argus-cortex` that updates this file in the same
+release. A new repo adds a row and the import block (see the end of this file) before its first release.
+
+## Repos
+
+GitHub: `smk762/<repo>`. Ports are each service's default.
+
+| Repo | Kind | Port | What it is for |
+|---|---|---|---|
+| **argus-cortex** | library | n/a | Shared foundation: taxonomy, wire-schema versioning, AI-backend contract, server guards, GPU lease, XMP, moderation clients, likeness provenance and consent records, optional lineage/vector/blob stores. |
+| **argus-quarry** | service | 8102 | Acquire public-domain / CC0 images with provenance and licence into a category-sorted raw pool. Searches local metadata archives of PD12M and Megalith-10m (filters, plus CLIP semantic and "more like this" search over PD12M) and lands chosen slices, with Megalith's Drawthings mirror as a fallback for photos gone from Flickr. Acquisition only. |
+| **argus-curator** | service | 8101 | Decide which images belong in a LoRA training set (quality, near-dup, faces, NSFW, diversity) and export them with a `manifest.jsonl`. |
+| **argus-lens** | service | 8100 (8080 standalone) | Structured, category-bucketed captions, `.txt` sidecars and XMP keywords. Records live captions to the cortex lineage store (the tape lightbox and replay read); runs read-only with `LENS_READ_ONLY`. |
+| **argus-forge** | service | 8103 | Turn a curated, captioned export into runnable kohya_ss / OneTrainer / diffusers configs. |
+| **argus-proof** | service | 8104 | Evaluate a trained LoRA against its dataset: sample grid, scores, pass/fail. |
+| **argus-atlas** | service | 8105 | Bake georeferenced fantasy-map overlays from real terrain (GDAL controls plus a cartography LoRA), to GeoTIFF / PMTiles. |
+| **argus-darkroom** | service | 8106 | Guarded image generation: checks the prompt, generates via ComfyUI, checks each output, and keeps a record of every attempt. |
+| **argus-survey** | service | 8107 | Point-cloud deliverables for land surveyors (LAS/LAZ/COPC/E57 in): QA, ground, DTM/DSM/CHM, contours, stockpile volumes and cut/fill (grid and ground-scaled), change between epochs, profiles, ASPRS Edition 2 (v2, 2024) accuracy, LAS 1.4 / E57 export for ReCap and Civil 3D. Explicit datum operations (MGA2020, AHD via AUSGeoid2020), every command recorded in `job.json`. PyPI `argus-survey`, image `ghcr.io/smk762/argus-survey`. |
+| **argus-mint** | service | 8108 | Provenance tokens for game assets: renders reviewed templates (fixed variable lists, no free prompts) through darkroom, checks each template against darkroom's checkpoints and workflows before approval, frames cards and writes their bios, and has the moderator and owner (SIWE) approve every image before it is pinned to IPFS. Mints ERC-721 cards and soulbound deeds whose metadata records the render's template, variables, checkpoint, LoRAs and seed, and anchors Merkle roots and commit/reveal secrets (Base). PyPI `argus-mint`, image `ghcr.io/smk762/argus-mint`. |
+| **argus-mask** | service | 8109 | A talking face: audio in (or text through a TTS service), ARKit facial-animation frames out (an energy driver on CPU, or NVIDIA Audio2Face-3D as a separate image), rendered in a browser on any LAN screen. Mesh (`.glb`) and LAM Gaussian-splat heads, each with provenance (`personal` or cleared); an optional face editor builds MakeHuman heads with Blender. PyPI `argus-mask`, image `ghcr.io/smk762/argus-mask`. |
+| **argus-studio** | UI + compose | 3000 | The suite web UI, and the compose stack that runs the services from GHCR images. No backend code. |
+| **argus-safelight** | UI | 3097 | Demo UI for darkroom: prompt and pre-flight, text-to-image, image-to-image and inpainting over SSE, the per-policy shield grid, history, and darkroom's docs in `/docs` with in-context help. Follows darkroom's `dev` at a recorded commit (`web/schema/pins.json`: docs, wire types and fixture move together), not a release; built from source by darkroom's compose, no image. |
+| **argus-cull** | UI + compose | 3000 | Demo UI for curator: which images make the set and why, plus the paths to act on. Its compose runs curator with NudeNet, EraX-NSFW and watermark sidecars (NudeNet-shaped `POST /infer`); SingGuard is darkroom's agent-composer. Follows curator's `dev` at a recorded commit, not a release; web image `ghcr.io/smk762/argus-cull`. |
+| **argus-lightbox** | UI (static) + compose | 3000 | Demo gallery navigated by lens captions. Bakes the recorded tape from cortex stores into a static site (the hosted demo), or captions a photo folder through lens in its compose stack, where a small server also lets you pick each photo's final caption. `/docs` links lens's docs at the baked version. |
+| **argus-sightline** | UI | 3107 | Workspace UI for survey: every step over SSE, a map of the derived views with drawing tools, a COPC point view, datums always on screen, a guided demo measured against analytic truth, and a "Made with" line per step from `job.json`. Follows survey's `dev` at a recorded commit (`schema/pins.json`: wire types, demo numbers and docs links move together), not a release; built from source by its compose, no published image yet. |
+| **argus-assay** | UI | 3108 | Review UI for mint. The moderator (token) approves or rejects every card; the owner signs for theirs (EIP-4361 via the wallet) and can change its text and style with a live preview, which both then review again. Templates, frames and bio templates are approved in its catalogue, with sample runs. New drafts render through darkroom on a reviewed checkpoint and LoRAs, or come from mint's pre-rendered portrait library with no GPU, shown as a checkpoint comparison grid. A mock serves mint's recorded fixture for demo mode (`make mock`). Pins a mint release (`web/schema/pins.json`, now v0.2.0: wire types and fixture move together); built from source by its compose, no image. |
+| **argus-halo** | infra | n/a | Terraform for the public demo (`argus.dragonhound.dev`): read-only replay services plus a private data host. |
+| **argus-ci** | infra | n/a | Reusable GitHub Actions workflows (uv, ruff, pytest, build, release). |
+| **argus-pkg-template** | infra | n/a | Copier template for new Argus Python packages; `copier update` pulls tooling changes. |
+
+**How they fit.** The LoRA pipeline is `quarry → curator → lens → forge → (trainer) → proof → atlas`; curator, lens,
+forge and proof carry the same `TargetProfile` from cortex. Darkroom is the suite's way to generate an image: mint
+renders through it, and anything new that needs a picture (mask backgrounds, game art) should too. Proof's sample grids
+and atlas's bakes predate it and still drive their own diffusion backend. Survey stands alone; its GeoTIFFs can feed
+atlas. Every Python service except quarry depends on cortex. UIs are thin clients: the service decides and the UI only
+shows.
+
+**API and UI pairs.** darkroom ↔ safelight · curator ↔ cull · lens ↔ lightbox · survey ↔ sightline · mint ↔ assay.
+Studio has a page for lens, curator, quarry, forge, proof, atlas and darkroom, and links out to sightline.
+
+## Need it? Use it
+
+| Need | Use | Don't |
+|---|---|---|
+| Generate an image (a plate, a background, art, a sample) | **darkroom** `POST /generate/stream` (SSE), `GET /image/{id}`. Its record id, model and seed are your provenance. Example client: mint's `DarkroomClient`. | Call ComfyUI directly or generate without checks. |
+| Check an image for nudity, or text/an image against a policy | `argus_cortex.moderation` (`NudeNetClient`, `SingGuardClient`, `policies`) | Write your own nudity definition or policy text. |
+| Share the GPU with other services | `argus_cortex.gpu` (`coordinator_from_env()`, `lease()`) | Assume the GPU is free. |
+| Call a local or hosted model | `argus_cortex.backends` (`LocalBackend`, `RemoteBackend`, `with_retries`) | Hand-roll an HTTP client per model. |
+| Version a wire payload, commit its schema | `argus_cortex.wire` (`make_versioned_base`, `render_schema`) | Ship an unversioned contract. |
+| Guard a FastAPI server's writes, or run read-only | `argus_cortex.server` (`WriteGuard`, `env_flag`) | Use `BaseHTTPMiddleware`, which buffers streams. |
+| Read or write XMP sidecars | `argus_cortex.xmp` | Overwrite another stage's properties. |
+| Record lineage, embeddings or blobs | `argus_cortex.store` (`open_lineage_store` / `open_vector_store` / `open_blob_store`) | Add a database to a single stage. |
+| Record where a face, voice or image came from, or whether it may be shown publicly | `argus_cortex.provenance` (`Provenance`, `.cleared`, `generator`); non-Python clients use `provenance-schema.json` | Define your own provenance kinds or consent fields. |
+| Check a real person's consent for a use of their face or voice | `argus_cortex.consent` (`ConsentRecord`, `consent_valid` → `ConsentVerdict`, `consent_matches`); non-Python clients use `consent-schema.json`. Records are written by **mask** | Invent refusal reasons, or serve a record (it names a person). |
+| The training target (style, category) | `argus_cortex.taxonomy`; non-Python clients use `taxonomy-schema.json` | Copy the literals. |
+| Acquire source photos with licence and provenance | **quarry** | Scrape inside another stage. |
+| Find public-domain photos by caption, filters or meaning, then land a slice | **quarry** `GET /archives/{name}/search` (`semantic=`, `similar_to=` on PD12M), `POST /archives/{name}/fetch` (opt-in, `QUARRY_ALLOW_FETCH=1`) | Download PD12M or Megalith wholesale to search it. |
+| Score, dedupe or select images; faces; content rating | **curator** | Re-score in a later stage. |
+| Caption or keyword images | **lens** | Write ad-hoc captions. |
+| Training configs, or evaluating a LoRA | **forge**, **proof** | |
+| Terrain, georeferencing, map tiles | **atlas** (stylised), **survey** (survey-grade) | |
+| Point clouds: ground classification, DTM/DSM, volumes, datum transformations (geoid heights, GDA94→GDA2020) | **survey** (CLI, or `POST /jobs/{id}/{step}` over SSE); its GeoTIFFs feed `argus-atlas controls --dem` | Let PROJ pick a transformation, or reproject heights without a geoid grid. |
+| A face that speaks | **mask** `POST /speak?face=<id>` (text), `POST /push?face=<id>` (a WAV or PCM you already have) or the `/session/<id>/source` socket; screens open `/?face=<id>` | Drive a face's animation yourself, or render it per stage. |
+| On-chain provenance, IPFS; game-asset cards from reviewed templates | **mint** (`argus-mint serve`, or the CLI); a consumer supplies template variables, display text and 32-byte leaf hashes | Mint tokens a game reads stats from, or send free text to a model. |
+| Run the whole stack locally | **studio** `compose.yaml` | |
+| A new Python package, or CI | **argus-pkg-template**, **argus-ci** | Copy another repo's tooling by hand. |
+
+## Shared rules
+
+- Shared code lives in cortex: import it, don't copy it. A cortex change ripples into every stage on its next bump.
+- Provenance first. Anything the suite serves or trains on carries its source and licence; unlicensed input is refused.
+- Optional heavy dependencies are lazy imports behind extras. A missing service config fails open to a no-op, never a crash.
+- Talk across repos over HTTP or a versioned wire schema, never by reading another repo's files.
+
+## Local checkouts
+
+The maintainer's siblings live under `~/`, so the paths are `../argus-<name>`, with two exceptions:
+- cortex is `../argus-core`;
+- studio is `../argus-vision-demo`.
+
+Directories named `argus-<repo>-<topic>` are worktrees of `<repo>`, not separate repos.
+
+## The import block (every repo's CLAUDE.md)
+
+```markdown
+## 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/dev/SUITE.md
+```