document the analysis contracts and correct the job-queue claim

The README's architecture diagram and stack list promised Redis + RQ. There is
no such thing in this codebase: redis_url is a settings field nothing reads,
rq is not a dependency, and the only worker is an asyncio poller over a
Postgres job table. Describe what exists.

API_CONTRACTS and KNOWN_LIMITATIONS gain the rules a reader needs to interpret
a result: deterministic confidence-ranked matching, the precision/recall curve,
the three flood-hazard cell populations, the sub-cell selection fallback, the
whole-feature object count next to clipped area metrics, and the required
manifest CRS. The new limitations are stated as limits rather than buried:
raster analysis has no sub-cell precision, and the object count is not
fractional.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/KNOWN_LIMITATIONS.md

@@ -43,6 +43,16 @@ runtime source of truth.
   underlying named Area itself is wholly valid.
 - Cross-region and land/sea selections stay split by legal/source zone.
   Semantically incompatible metrics are not merged.
+- Raster analysis is cell-based. A selection smaller than one source cell is
+  answered over the cells it touches, so the analysed area is larger than the
+  drawn area; the response says so rather than returning zeros. Sub-cell
+  precision is not available from a raster source.
+- The object count in a vector selection counts whole features that touch the
+  selection, while area and length metrics clip to it. The response reports how
+  many features the edge cuts; it does not attempt a fractional object count.
+- Flood-hazard percentages are shares of the modelled area. Where the VMM model
+  does not cover the selection, that is reported as missing coverage and never
+  as an absence of risk.
 
 ## Historical analysis
 
@@ -68,12 +78,28 @@ runtime source of truth.
   `YOLO_SEG_MODEL_PATH`/`SAM_MODEL_PATH` to existing local weights and enables
   them explicitly. GeoIntel never downloads segmentation weights automatically;
   fixture segmentation remains explicit-only.
+- Detection QA reports both a strict footprint IoU and an envelope diagnostic.
+  For an axis-aligned box detector the strict figure has a ceiling below 1 on
+  rotated or non-rectangular buildings; the response states which geometry mode
+  applies rather than silently attributing that gap to detection quality.
+- Segmentation inference still predicts one tile per call. Batching is
+  implemented for detection only, because the SAM adapter is prompt-driven and
+  does not share the detector's batch semantics.
+- Tile-edge truncated boxes are dropped in favour of the overlapping
+  neighbour's complete view. On a manifest generated with `overlap=0` there is
+  no such neighbour, so an object on a seam is lost rather than duplicated.
+  Generate tiles with an overlap larger than the biggest expected object.
 
 ## Operations
 
-- Long AI/GIS work still uses the existing synchronous job abstraction rather
-  than a distributed durable queue. Interrupted synchronous work is marked
-  failed on restart and must be retried explicitly.
+- Detection and segmentation runs can be queued through
+  `POST /detection/run-async` and executed by the in-process analysis worker, so
+  tiled GPU inference no longer blocks an HTTP request. This is a job table in
+  PostgreSQL polled by the API process, not a distributed durable queue: there
+  is no cross-host distribution and no automatic retry. The synchronous
+  `POST /detection/run` remains available for small runs. Interrupted work is
+  marked failed on restart and must be retried explicitly.
+- Other long GIS work still uses the synchronous job abstraction.
 - GeoIntel remains a controlled single-operator product. The optional guest
   demo adds bounded presentation access only; multi-user authorization and
   tenant isolation remain outside the product scope.