Merge pull request 'Make email and phone unique per business, not platform-wide' (#5) from fix/per-business-identity into main

Reviewed-on: #5

docs/PILOT_READINESS.md

@@ -131,9 +131,33 @@ prices read-only.
   mismatch.
 - The Products page always shows default prices.
 
+## People in more than one business
+
+Email and phone are unique **within a business**, not across the platform,
+so one person can work for two businesses. Each account has its own
+password and role.
+
+- Login looks the email up in every business. If the password matches one
+  account, it signs straight in; if it matches several, the login page asks
+  which business. Someone with a wrong password learns nothing about which
+  businesses an email belongs to, and a wrong guess never resets the
+  failed-login count of another business's account.
+- Signup and staff creation only check for duplicates inside the business,
+  so they no longer reveal whether an email or phone is registered
+  elsewhere.
+- Platform-operator access now needs the `platformAdmin` flag on the
+  account as well as the email in `PLATFORM_ADMIN_EMAILS`. Without the
+  flag, any owner could create a staff account with the operator's email
+  in their own business. The flag is only set by `npm run seed` and
+  `npm run migrate:identity`, never through the app.
+
+**Deploying this change:** run `npm run migrate:identity` straight after
+the deploy. It flags the existing operator accounts and swaps the old
+platform-wide unique indexes for per-business ones. Until it runs,
+operators cannot open the Platform console and a second business cannot
+reuse an email. It is safe to re-run.
+
 ## Still open
-- **Global email and phone uniqueness.** One person cannot work for two
-  businesses, and signup reveals whether an address is already registered.
 - **Isolation by convention.** Tenant filters are still written per route.
   The tests cover the sales, stock, transfer and access paths, not every
   route.