diff --git a/docs/external-miner/README.md b/docs/external-miner/README.md
index 2e73508c5..e0c713733 100644
--- a/docs/external-miner/README.md
+++ b/docs/external-miner/README.md
@@ -14,7 +14,7 @@ over HTTP to the live challenges:
 | Challenge | `challenge_id` | Scoring | Guide | Public miner repo |
 |-----------|----------------|---------|-------|-------------------|
 | Design | `design` | `challenge_scoring_version` **2** (daily share ≥2 wins + agentic) | [design.md](./design.md) | [BaseIntelligence/design-challenge](https://github.com/BaseIntelligence/design-challenge) |
-| Prism | `prism` | `challenge_scoring_version` **2** (bpb-only) | [prism.md](./prism.md) | [BaseIntelligence/prism](https://github.com/BaseIntelligence/prism) (miner docs forthcoming) |
+| Prism | `prism` | `challenge_scoring_version` **2** (bpb-only) | [prism.md](./prism.md) | [BaseIntelligence/prism](https://github.com/BaseIntelligence/prism) |
 
 Do **not** conflate version axes:
 
diff --git a/docs/external-miner/troubleshoot.md b/docs/external-miner/troubleshoot.md
index 4c14f768b..18ef40418 100644
--- a/docs/external-miner/troubleshoot.md
+++ b/docs/external-miner/troubleshoot.md
@@ -22,6 +22,9 @@
 | Symptom | Likely cause | What to check |
 |---------|--------------|---------------|
 | Rejected submit | Recipe contract | `GET /v1/recipe` + baseline; follow [`PRISM_RECIPE.md`](../PRISM_RECIPE.md) |
+| Source-tree rejected on raw ZIP | Need `zip_base64` JSON intake | Multi-file trees (helpers/`kernels/`/`tokenizer/`) must use JSON `zip_base64`, not raw `application/zip` |
+| Tokenizer / hub errors on pod | No network; wrong declaration | Use `ctx["tokenizer"]`; declare via `tokenizer/` or `build_tokenizer` in `architecture.py` (not `training.py`). GPT-2 is fallback only |
+| `CAP_EXCEEDED` / Score 0 | Model > 350M params | Terminal — resize `build_model`; not auto-retried |
 | Score 0 after review | `Copied` / `Suspicious` | Similarity gate; rewrite; do not paste baseline wholesale |
 | Stuck `Provisioning` | Lium market thinness | Ops-side; watch `GET /v1/jobs` / events |
 | Idempotent replay | Same `submission_id` | Expected — returns prior row |