diff --git a/docs/BACKEND_LEGACY_SUPABASE_SCRIPTS.md b/docs/BACKEND_LEGACY_SUPABASE_SCRIPTS.md
new file mode 100644
index 0000000..a40c8c4
--- /dev/null
+++ b/docs/BACKEND_LEGACY_SUPABASE_SCRIPTS.md
@@ -0,0 +1,23 @@
+# Backend root scripts and legacy `SupabaseService`
+
+Cosmos-first runtime lives under `backend/src/`. Root-level `backend/*.ts` maintenance and verification scripts that still import `supabaseService` from `src/services/SupabaseService.js` fall into these buckets:
+
+## Use `getLegacySupabaseClient()` for raw Postgres only
+
+Scripts that only need the Supabase JS client for `.from(...)` should import `getLegacySupabaseClient` from `src/services/legacySupabaseClient.ts` (see `verify_profiles.ts`, `create_aggressive_profile.ts`, `apply_standard_risk_profiles.ts`, etc.).
+
+## Still require full `supabaseService`
+
+| Script | Reason |
+|--------|--------|
+| `reconcileMissingOrderCoverage.ts`, `reconcileExitBackfillOnce.ts`, `reconcileSubTagRepair.ts` | `getActiveUsers` / `getActiveProfiles` |
+| `reconcileNoGoQtyMismatchOnce.ts` | Reconciliation helpers (`getReconciliationBackfillAuditRows`, `getFilledLifecycleOrdersForProfile`, `insertReconciliationBackfillAuditRows`, `upsertReconciliationBackfillOrders`, …) plus active user/profile listing |
+| `manualOverrideCloseTrades.ts` | Same reconciliation audit/order helpers as above |
+| `verify_traceability.ts`, `verify_fetch.ts`, `verify_sl_tp_persistence.ts` | `getLatestFilledEntry` / `getLatestOrder` |
+| `verify_realtime.ts` | `subscribeToProfiles` (realtime channel setup) |
+| `verifyTenantIsolation.ts` | Monkey-patches `loadLatestBotStateSnapshot` on the singleton |
+| `debugProfiles.ts`, `diagnose_profiles.ts`, `audit_profile_structure.ts` | `getActiveProfiles` / `getActiveUsers` (read-only listing) |
+| `e2e_full_scenario.ts`, `verify_e2e_fix.ts`, `final_e2e_param_verification.ts`, `verify_profiles_e2e.ts` | `getActiveProfiles` for E2E harness |
+| `testOrderStatusSyncRegressions.ts`, `testLifecycleRegressions.ts`, `testStrictCapitalGuard.ts`, `testTradeExecutorLifecycle.ts`, `testManualTraderCapitalGuard.ts`, `testFailureInjection.ts`, `testCoreModuleCoverage.ts`, `testReconciliationExitBackfillEvidenceGuard.ts`, `testSupabaseOrderPersistenceRegressions.ts`, `testSupabaseTradeHistorySourceFallback.ts`, `testReconciliationParityHeartbeat.ts` | Monkey-patch or call service methods under test |
+
+Auth-specific legacy usage remains in `src/services/platformAuthService.ts` (`verifyAccessToken`, admin checks), not in these scripts.