diff --git a/README.md b/README.md
index 7b0dc305..397de169 100644
--- a/README.md
+++ b/README.md
@@ -68,3 +68,45 @@ Angular CLI does not come with an end-to-end testing framework by default. You c
 ## Additional Resources
 
 For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+
+## AAF integration — `dev-aaf` deployment
+
+The `aaf-dev` branch targets the **`biocloud-dev-aaf`** Auth0 tenant
+(`dev-aaf` environment), isolated from `dev-bc`. Deploys are **manual** for now.
+
+Point the app at the tenant via runtime config — edit
+`src/assets/config/app-config.json`:
+
+```json
+"auth0": {
+  "domain": "biocloud-dev-aaf.au.auth0.com",
+  "clientId": "ZtroVyP0eDfVzpCBSnfYfXBCE6iCmo1R",
+  "backend": "https://dev-aaf.api.aai.test.biocommons.org.au"
+}
+```
+
+Run locally (set `backend` to `http://localhost:8000` if running the API locally):
+
+```bash
+npm ci && npm start        # http://localhost:4200
+```
+
+Deploy to the hosted dev-aaf portal:
+
+```bash
+aws sso login --profile aai
+export AWS_PROFILE=aai AWS_REGION=ap-southeast-2
+npm ci && npm run build
+aws s3 sync ./dist/aai-portal/browser/ s3://aai-dev-aaf-portal/ --delete
+DIST=$(aws cloudfront list-distributions \
+  --query "DistributionList.Items[?contains(Aliases.Items,'dev-aaf.portal.aai.test.biocommons.org.au')].Id | [0]" \
+  --output text)
+aws cloudfront create-invalidation --distribution-id "$DIST" --paths "/*"
+```
+
+AAF login: **no portal change needed.** AAF uses Identifier-First / Home-Realm
+Discovery configured in Auth0 (see `aai-infrastructure`) — the portal's standard
+`loginWithRedirect()` shows an email-only screen, and institutional emails (any
+AAF-federated domain) route to AAF automatically. There is deliberately **no
+"Login with AAF" button** and no `connection` parameter. Hosted at
+<https://dev-aaf.portal.aai.test.biocommons.org.au>.