docs: add professional project landing README

README.md

@@ -1,3 +1,242 @@
-# Project_Velocity
+# Project Velocity
 
-Next-gen operating environment: WebOS and iPad App
+Project Velocity is an on-prem real estate operating system for high-value property sales.
+It combines a premium WebOS, an iPad field app, a FastAPI neural core, ComfyUI-based media generation, and biometric/sentiment-assisted sales intelligence.
+
+This repository is the active product codebase for the Velocity suite.
+
+## What Velocity Includes
+
+- `Velocity WebOS`
+  - operator console for sales, inventory, perception, and marketing
+- `The Oracle`
+  - AI-assisted lead intelligence and analytical workspace
+- `The Sentinel`
+  - live perception, sentiment, and showroom engagement tracking
+- `Inventory / Time & Light`
+  - property inventory surfaces and light-analysis tooling
+- `The Catalyst`
+  - marketing campaign orchestration and asset generation
+- `iPad App`
+  - field-facing app for inventory, camera workflows, and time/light experience
+- `Neural Core`
+  - unified FastAPI backend with PostgreSQL, auth, Sentinel, Catalyst, CCTV, scenes, videos, and vault services
+
+## Product Screens
+
+### Dashboard
+
+![Velocity Dashboard](docs/images/readme/dashboard.png)
+
+### The Oracle
+
+![The Oracle](docs/images/readme/oracle.png)
+
+### The Sentinel
+
+![The Sentinel Overview](docs/images/readme/sentinel-overview.png)
+
+![The Sentinel Live Session](docs/images/readme/sentinel-live-session.png)
+
+### Inventory
+
+![Inventory](docs/images/readme/inventory.png)
+
+### The Catalyst
+
+![The Catalyst](docs/images/readme/catalyst.png)
+
+### Settings
+
+![Settings](docs/images/readme/settings.png)
+
+## Architecture
+
+```mermaid
+flowchart LR
+    ipad[iPad App] --> webapi[FastAPI Neural Core]
+    webos[Velocity WebOS] --> webapi
+    webapi --> pg[(PostgreSQL)]
+    webapi --> sentinel[Sentinel Engine]
+    webapi --> catalyst[Catalyst Routes]
+    webapi --> vault[Vault Links]
+    webapi --> cctv[CCTV / Scene / Video Routers]
+    catalyst --> comfy[ComfyUI / Dream Weaver / Wan / Qwen]
+    comfy --> s3[S3 Model + Asset Store]
+    comfy --> gpu[AWS GPU Workers]
+    webos --> ingress[t4g Ingress]
+    ipad --> ingress
+    ingress --> webapi
+    ingress --> comfy
+```
+
+## Current Stack
+
+### Frontend
+
+- `React 19`
+- `Vite`
+- `TypeScript`
+- `Tailwind`
+- `Framer Motion`
+- `Recharts`
+- `Zustand`
+
+### Backend
+
+- `FastAPI`
+- `PostgreSQL`
+- `WebSockets`
+- `JWT auth`
+- `asyncpg`
+
+### AI / Media
+
+- `ComfyUI`
+- `Dream Weaver`
+- `Qwen image workflows`
+- `Wan 2.2 workflow assets`
+- `Sentinel perception pipeline`
+- `Google MediaPipe browser-side face landmarking`
+
+### Infrastructure
+
+- Linux control surface
+- AWS GPU workers
+- stable `t4g.micro` ingress
+- S3-backed model and asset strategy
+- route-managed Comfy exposure
+
+## Repository Areas
+
+| Path | Purpose |
+| --- | --- |
+| `app/` | Velocity WebOS frontend |
+| `backend/` | FastAPI neural core |
+| `iOS/` | native iPad application |
+| `comfy_engine/` | Dream Weaver, Wan, Qwen workflow logic and assets |
+| `infrastructure/` | ingress, ops, deployment, and recovery artifacts |
+| `.Agent Context/` | working docs, bibels, strategy, and truth artifacts |
+
+## Core Runtime Surfaces
+
+### WebOS modules
+
+- Dashboard
+- The Oracle
+- The Sentinel
+- Inventory
+- The Catalyst
+- Settings
+
+### Backend capabilities already present
+
+- authentication and token issuance
+- Catalyst campaign routes
+- Sentinel websocket/session ingestion
+- CCTV routes
+- scenes and videos routes
+- vault routes
+- static asset serving
+- health checks
+
+### Media and generation paths
+
+- Dream Weaver workflow stack exists locally
+- Qwen poster workflow assets exist locally
+- Wan 2.2 workflow assets exist locally
+- queue/gateway model exists and is being hardened into a canonical async path
+
+## Product Positioning
+
+Velocity is not built as a SaaS-first CRM.
+It is designed as a private deployment system for builders, channel partners, and enterprise real-estate operators who want:
+
+- private data ownership
+- on-prem or client-controlled deployment
+- AI-assisted sales acceleration
+- perception-assisted showroom intelligence
+- high-end marketing asset generation
+- portfolio-aware expansion over time
+
+## Current Reality
+
+What is materially present now:
+
+- strong WebOS UI shell
+- real iOS implementation surface
+- live FastAPI backend
+- live ingress and AWS/Linux operational model
+- Dream Weaver / Qwen / Wan workflow assets
+- browser-webcam Sentinel path using MediaPipe
+
+What is still being closed:
+
+- canonical CRM routes for `leads`, `chat_logs`, and `kanban`
+- unified CRM database contract
+- prompt inventory and persona contract map
+- full end-to-end async orchestration across all media workflows
+- stronger frontend/backend contract discipline
+
+## Local Development
+
+### Web frontend
+
+```bash
+cd app
+npm install
+npm run dev
+```
+
+Default local URL:
+
+```text
+http://127.0.0.1:5173/
+```
+
+### Backend
+
+```bash
+python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+Health check:
+
+```text
+http://127.0.0.1:8000/health
+```
+
+## Deployment Model
+
+Velocity is being shaped toward:
+
+- `on-prem primary`
+- `client-owned cloud optional`
+- `Linux control surface as operator plane`
+- `AWS GPU workers as elastic compute`
+- `S3 as canonical model and large-asset store`
+
+The current repo also includes the ingress and ops artifacts used to run this model today.
+
+## Operator Docs
+
+Key internal docs live under `.Agent Context/` and `infrastructure/`.
+Important current references include:
+
+- `Project Velocity Master Bibel`
+- `Sprint 1 Fact Table`
+- `TEAM_HANDOFF_2026-04-08.md`
+
+## Status
+
+This is an active product repository, not a cleaned public SDK.
+Expect a mix of:
+
+- production-bound code
+- live infrastructure artifacts
+- design explorations
+- strategic docs
+- work-in-progress subsystem convergence
+
+The main direction is stable:
+Velocity is converging into a private, modular, on-prem real estate operating system with AI, perception, and media generation as first-class components.