diff --git a/.github/review-references.yaml b/.github/review-references.yaml
new file mode 100644
index 00000000..e8ff2d98
--- /dev/null
+++ b/.github/review-references.yaml
@@ -0,0 +1,29 @@
+# Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`).
+version: 1
+
+instructions: |
+ This repository is the Python client for the Apify API, a port of the JS client that the Python SDK
+ builds on. For every behaviour the pull request adds or changes, check three things: that it matches
+ what the API actually does, that it matches what the JS client does for the same operation (ignore
+ differences caused by different language idioms and style), and that every place the Python SDK uses
+ the changed code still works. Back every finding with the reference file and line (create public
+ github link fixed to a commit you have seen).
+
+references:
+ - repository: apify/apify-core
+ ref: develop
+ paths:
+ - src/api/**
+ - src/packages/**
+ instructions: |
+ The API the client calls. Compare the request the client builds with what the handler accepts
+ (paths, methods, query and body parameters, defaults, limits) and what the client expects back with
+ what the handler returns (field names and types, pagination, status codes, error types).
+ - repository: apify/apify-client-js
+ instructions: |
+ The reference implementation this client mirrors. Compare the changed Python methods with the
+ matching JS methods: parameters and defaults, the request it sends, how it parses the response,
+ what it returns, and how it handles errors.
+ - repository: apify/apify-sdk-python
+ instructions: |
+ The main consumer of this client. Highlight the changes that will require updates to the SDK.
diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml
index 233d945e..1ca80ef2 100644
--- a/.github/workflows/factory_review.yaml
+++ b/.github/workflows/factory_review.yaml
@@ -25,6 +25,8 @@ jobs:
# Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the
# repository's layout when this workflow was added; edit them like any other code.
with:
+ # The draft of the cross-repository references, under evaluation. Back to `main` once it lands.
+ ai-developer-ref: claude/review-references
policy: |
{
"denyGlobs": [
diff --git a/.rules.md b/.rules.md
index bba36456..31a2c49d 100644
--- a/.rules.md
+++ b/.rules.md
@@ -42,3 +42,7 @@ The OpenAPI spec can lag behind the API and omit fields, and a live response onl
- A single resource's fields are in `PUBLISHED_*_FIELDS` in `src/packages/-server/src//.server.ts`.
- A list endpoint has its own, usually smaller, `API_PUBLISHED_*_LIST_FIELDS` in `src/api/src/routes//_list.ts`, and often builds each item inline. Don't assume a list item has the same fields as the single resource.
+
+### Additional context
+
+The code in this repository is based on and integrated with code from other repositories. The most important references are defined in [review references](./.github/review-references.yaml)