docs: similarity precheck API

docs/api.md

@@ -10,6 +10,7 @@ Replace `{GATEWAY}` with `https://chain.joinbase.ai` (prod) or
 | Route | What it tells you |
 |-------|-------------------|
 | `POST /challenge/prism/v1/submissions` | Submit zip / JSON / training-only |
+| `POST /challenge/prism/v1/submissions/precheck` | Advisory copy-gate (3/coldkey/UTC day; no queue/pod) |
 | `GET /challenge/prism/v1/submissions/{id}` | Detail + bpb + review/similarity/agentic records |
 | `GET /challenge/prism/v1/submissions/{id}/events` | Stage timeline |
 | `POST /challenge/prism/v1/submissions/{id}/retry` | Requeue an infra-failed row |
@@ -47,6 +48,9 @@ Terminal states to know:
 Submit errors: `403 hotkey_not_in_metagraph`, `404 unknown_arch`,
 `409 submission_gated`, `503 metagraph_unavailable`.
 
+Precheck errors: same membership/contract codes, plus
+`429 precheck_quota_exceeded` when the 3/coldkey/UTC-day budget is spent.
+
 ## Auth note
 
 Miner routes identify you by hotkey (`X-Miner-Hotkey` or JSON `miner_hotkey`). Never

docs/scoring.md

@@ -17,6 +17,8 @@ submission is coherent and not cheating; their quality notes never move the scor
   training-only entries on a published arch are never "copies" by construction.
 - After the gate, an LLM similarity review + agentic anti-cheat still run:
   `Copied` / `Suspicious` / `cheat` verdicts → hard zero.
+- Probe the cheap gate first with `POST /v1/submissions/precheck` (3/coldkey/UTC
+  day) — see [Submit](submit.md#precheck-similarity-before-you-submit).
 
 ## Architecture competition (emission math)
 

docs/submit.md

@@ -88,6 +88,47 @@ from the registry (miner-sent architecture is rejected on these rows). Unknown
 - Cheat / rejected verdicts are **terminal** — no auto-retry. Manual retry for
   infra-class failures: `POST /v1/submissions/{id}/retry`.
 
+## Precheck similarity before you submit
+
+Dry-run the same pre-LLM copy gate **without** burning your 1-max slot or a GPU
+eval. Same payload as submit (ZIP or JSON):
+
+```bash
+curl -sS -X POST "$GATEWAY/challenge/prism/v1/submissions/precheck" \
+  -H 'content-type: application/zip' \
+  -H "X-Miner-Hotkey: $HOTKEY" \
+  --data-binary @submission.zip
+```
+
+Example response:
+
+```json
+{
+  "similar": false,
+  "verdict": "clean",
+  "message": "no earlier architecture copy detected by the pre-LLM gate; full submit still runs similarity + agentic",
+  "quota": {
+    "day": "2026-08-08",
+    "used": 1,
+    "limit": 3,
+    "remaining": 2,
+    "identity": "coldkey"
+  }
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `similar` | `true` → would hard-reject at intake copy gate |
+| `verdict` | `clean` / `copied` / `skipped` (training-only) |
+| `matched_against` | Corpus id only (never competitor source) |
+| `score` | Similarity in `[0,1]` when compared |
+| `quota` | Daily budget (`limit` = 3) |
+
+**Quota: 3 attempts per coldkey per UTC day** (hotkey fallback when Owner is
+unknown). Rotating hotkeys under the same coldkey does **not** reset the budget.
+A 4th call returns `429` / `precheck_quota_exceeded` with `remaining=0`.
+
 ## Gateways
 
 | Environment | Base URL |

docs/troubleshooting.md

@@ -9,6 +9,8 @@
 | `503 metagraph_unavailable` | Snapshot lag after a fresh registration — retry in a couple of minutes |
 | `missing_telemetry_hooks` | `training.py` must import `prism_telemetry`, call `report(...)`, and may call `finish_evaluation()` |
 | Status `rejected` | Pre-LLM copy gate: your `architecture.py` matches an *earlier* one. Write your own; start from the baseline |
+| `similar: true` on precheck | Would hit intake copy gate — revise before `POST /v1/submissions` |
+| `429 precheck_quota_exceeded` | 3 prechecks/coldkey/UTC day used; rotating hotkeys does not reset |
 | `auto_retry` events | Infra failure retrying (up to 3 retries) — wait for the final state |
 | `failed` after retries | Slot `blocked`; leaving the metagraph reopens it via the watcher |
 | No telemetry on the site | Your loop never called `report(...)` — hooks are mandatory |