diff --git a/factory/PROMPT.md b/factory/PROMPT.md
index 2de4dbd..77ff16f 100644
--- a/factory/PROMPT.md
+++ b/factory/PROMPT.md
@@ -20,8 +20,24 @@ Before acting, read the relevant best-practices file:
 - Disk issues → `cat ${FACTORY_ROOT}/factory/best-practices/disk.md`
 - CI issues → `cat ${FACTORY_ROOT}/factory/best-practices/ci.md`
 - Dev-agent issues → `cat ${FACTORY_ROOT}/factory/best-practices/dev-agent.md`
+- Review-agent issues → `cat ${FACTORY_ROOT}/factory/best-practices/review-agent.md`
 - Git issues → `cat ${FACTORY_ROOT}/factory/best-practices/git.md`
 
+## Credentials & API Access
+
+Environment variables are set. Source the helper library for convenience functions:
+```bash
+source ${FACTORY_ROOT}/lib/env.sh
+```
+
+This gives you:
+- `codeberg_api GET "/pulls?state=open"` — Codeberg API (uses $CODEBERG_TOKEN)
+- `wpdb -c "SELECT ..."` — Woodpecker Postgres (uses $WOODPECKER_DB_PASSWORD)
+- `woodpecker_api "/repos/2/pipelines"` — Woodpecker REST API (uses $WOODPECKER_TOKEN)
+- `$REVIEW_BOT_TOKEN` — for posting reviews as the review_bot account
+- `$HARB_REPO_ROOT` — path to the harb repo
+- `$FACTORY_ROOT` — path to the dark-factory repo
+
 ## Escalation
 
 If you can't fix it, escalate to Clawy (the main agent):
diff --git a/factory/best-practices/review-agent.md b/factory/best-practices/review-agent.md
new file mode 100644
index 0000000..c2a053e
--- /dev/null
+++ b/factory/best-practices/review-agent.md
@@ -0,0 +1,30 @@
+# Review Agent Best Practices
+
+## Architecture
+- `review-poll.sh` (cron */10) → finds open PRs with CI pass + no review → spawns `review-pr.sh`
+- `review-pr.sh` uses `claude -p` to review the diff, posts structured comment
+- Uses `review_bot` Codeberg account for formal reviews (separate from main account)
+- Skips WIP/draft PRs (`[WIP]` in title or draft flag)
+
+## Safe Fixes
+- Manually trigger review: `bash ${FACTORY_ROOT}/review/review-pr.sh <pr-number>`
+- Force re-review: `bash ${FACTORY_ROOT}/review/review-pr.sh <pr-number> --force`
+- Check review log: `tail -20 ${FACTORY_ROOT}/review/review.log`
+
+## Common Failures
+- **"SKIP: CI=failure"** — review bot won't review until CI passes. Fix CI first.
+- **"already reviewed"** — bot checks `<!-- reviewed: SHA -->` comment marker. Use `--force` to override.
+- **Review error comment** — uses `<!-- review-error: SHA -->` marker, does NOT count as reviewed. Bot should retry automatically.
+- **Self-narration collapse** — bot sometimes narrates instead of producing structured JSON. JSON output format in the prompt prevents this.
+- **Hallucinated findings** — bot may flag non-issues. This needs Clawy's judgment — escalate.
+
+## Monitoring
+- Unreviewed PRs with CI pass for >1h → factory-poll.sh auto-triggers review
+- Review errors should resolve on next poll cycle
+- If same PR fails review 3+ times → likely a prompt issue, escalate
+
+## Lessons Learned
+- Review bot must output JSON — prevents self-narration collapse
+- DISCUSS verdict should be treated same as REQUEST_CHANGES by dev-agent
+- Error comments must NOT include `<!-- reviewed: SHA -->` — would falsely mark as reviewed
+- Review bot uses Codeberg formal reviews API — branch protection requires different user than PR author