fix: Applied fix for name, the oracle team sharing, sentinel client list visibility

docs/LOCAL_DEV_SNAPSHOT.md

@@ -0,0 +1,143 @@
+# Velocity Local Dev Snapshot
+
+This document defines the correct way to work against a local copy of the current Velocity backend state without polluting Git and without guessing whether a backend-only change will work in production.
+
+## Why This Exists
+
+Project Velocity now depends on live PostgreSQL-backed surfaces and runtime state that cannot be validated reliably from frontend-only local development.
+
+Examples:
+
+- operator identity and profile hydration
+- CRM-backed Sentinel client selection
+- Oracle Canvas data access and sharing
+- verified team-account lists for share flows
+
+The correct solution is a repeatable local snapshot workflow.
+
+## Design Rule
+
+Local runtime copies must never be committed.
+
+Everything produced by this workflow lives under gitignored paths:
+
+- `.local-dev/`
+- `runtime-snapshots/`
+- `local-dev-bundles/`
+
+## Bundle Shape
+
+The Linux-origin export bundle contains:
+
+- `backend.env.export`
+- `velocity.dump`
+- `restore.instructions.txt`
+
+This is intentionally minimal. It gives local developers what they need to stand up a local database-backed verification surface without pushing runtime state into the repository.
+
+## Export From Linux Box
+
+Run this on the Linux-origin host:
+
+```bash
+cd /opt/desineuron-velocity-site/repo
+bash scripts/export_velocity_local_bundle.sh
+```
+
+This creates a tarball in `/tmp` named like:
+
+```text
+/tmp/velocity-local-bundle-YYYYmmdd-HHMMSS.tar.gz
+```
+
+## Import On Windows Dev Machine
+
+1. Copy the tarball to the Windows machine.
+2. Extract it under:
+
+```text
+Project_Velocity/.local-dev/source-bundles/<bundle-name>/
+```
+
+3. Run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\import_velocity_local_bundle.ps1
+```
+
+This will:
+
+- copy the exported env snapshot into `.local-dev/backend/.env.local`
+- copy the PostgreSQL dump into `.local-dev/db/velocity.dump`
+- generate a local Docker Compose file for PostgreSQL
+- generate a restore script
+
+## Restore Local Database
+
+After import, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\.local-dev\db\restore_local_snapshot.ps1
+```
+
+This restores the dump into a local PostgreSQL container on:
+
+- host: `127.0.0.1`
+- port: `54329`
+- db: `velocity_local`
+- user: `velocity_local`
+- password: `velocity_local`
+
+## Local Backend Wiring
+
+The backend expects these env keys:
+
+- `VELOCITY_DB_HOST`
+- `VELOCITY_DB_PORT`
+- `VELOCITY_DB_NAME`
+- `VELOCITY_DB_USER`
+- `VELOCITY_DB_PASSWORD`
+- `DATABASE_URL`
+- `CORS_ORIGINS`
+- `VELOCITY_ASSET_DIR`
+- `JWT_SECRET_KEY`
+
+The exported env snapshot provides the production-shaped variable names. For local verification, point the DB values to the local PostgreSQL container rather than the production database.
+
+## Create A Zip For Sayan And Sourik
+
+Once `.local-dev/` is hydrated locally, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\package_velocity_local_bundle.ps1
+```
+
+This creates a gitignored zip under:
+
+```text
+Project_Velocity/local-dev-bundles/
+```
+
+That zip is the correct handoff artifact for teammate local verification.
+
+## What This Solves
+
+This workflow allows local verification of:
+
+- real account-backed login flows
+- profile name/avatar hydration
+- share-recipient lookup
+- Sentinel CRM client selection
+- Oracle-backed DB reads
+
+## What It Does Not Solve By Itself
+
+This does not automatically fix backend bugs.
+
+If Oracle still returns `500` locally after restoring the snapshot, that is now a real reproducible backend issue rather than a blind production-only guess.
+
+## Current Constraint
+
+The current machine cannot SSH into the Linux box because the host is configured for publickey auth and this workstation is not authorized yet.
+
+That means the export step must currently be triggered from a machine or shell that already has valid SSH/key access to the Linux-origin host.