diff --git a/app/plugins/Transmogrify/README.md b/app/plugins/Transmogrify/README.md
index 5a3163fbf..0c51ce724 100644
--- a/app/plugins/Transmogrify/README.md
+++ b/app/plugins/Transmogrify/README.md
@@ -126,3 +126,45 @@ Hints:
   - src/Command/TransmogrifyCommand.php
   - config/schema/tables.json
   - src/Lib/Traits/* (type mapping, caching, row transformations, hooks)
+
+## Org Identities → External Identities: Readiness and Migration Behavior
+
+This plugin migrates Organizational Identities to the new model introduced in COmanage Registry v5:
+
+- OrgIdentity was split into ExternalIdentity and ExternalIdentityRole.
+- ExternalIdentity directly relates to Person (a Person may have multiple External Identities, but each External Identity belongs to a single Person).
+- The CoOrgIdentityLink crosswalk was eliminated and Organizational Identity Pooling was dropped.
+- affiliation was replaced by affiliation_type_id.
+- o was renamed to organization.
+- ou was renamed to department.
+- External Identities no longer have Primary Names.
+- External Identities do not carry the login flag on Identifiers. As of v5.1.0, the Identifier Mapper Pipeline Plugin can be used to set this flag.
+
+Eligibility (reasoning) is based on “non‑historical” links in cm_co_org_identity_links (co_org_identity_link_id IS NULL):
+- A) No non‑historical link: excluded (x)
+- B) Has non‑historical link(s) but all co_person_id are NULL: excluded (x)
+- C) Has at least one non‑historical link with a non‑NULL co_person_id: included (✓)
+
+Included (✓) Org Identities are migrated as:
+- One ExternalIdentity linked directly to the Person (person_id from the link)
+- One ExternalIdentityRole for role‑like attributes with v5 field changes applied:
+    - affiliation → affiliation_type_id (type‑mapped)
+    - o → organization
+    - ou → department
+- External Identities do not have Primary Names; identifier “login” flags are not set by this migration (use the Identifier Mapper Pipeline if needed)
+
+### Recommended preflight: Org Identities Health command
+
+Run this before migrating to verify which Org Identities will be included vs excluded, using the same non‑historical link reasoning:
+
+```bash
+bin/cake transmogrify --orgidentities-health
+```
+
+
+You’ll see a fixed‑width table with Reason, Included/Excluded counts, and an Indicator (✓ included, x excluded). Reasons are:
+- A) No non‑historical link (excluded)
+- B) Has non‑historical link(s) but all co_person_id are NULL (excluded)
+- C) Has at least one non‑historical link with a non‑NULL co_person_id (included)
+
+Totals summarize overall readiness. Use this report to address data conditions (eg, missing person links) so that important Org Identities are eligible for migration.