docs: polish project landing readme

README.md

@@ -5,7 +5,17 @@ It combines a premium WebOS, an iPad field app, a FastAPI neural core, ComfyUI-b
 
 This repository is the active product codebase for the Velocity suite.
 
-## What Velocity Includes
+## At A Glance
+
+| Area | Current State |
+| --- | --- |
+| WebOS | Live UI shell with Dashboard, Oracle, Sentinel, Inventory, Catalyst, and Settings |
+| Backend | Unified FastAPI backend with PostgreSQL, auth, Sentinel, Catalyst, CCTV, scenes, videos, and vault |
+| iPad | Materially implemented app surface for inventory, camera flows, and Time & Light |
+| AI Media | Dream Weaver, Qwen, and Wan workflow assets present locally |
+| Infra | Linux control surface, AWS GPU workers, stable ingress, and S3-backed asset strategy |
+
+## Product Surfaces
 
 - `Velocity WebOS`
   - operator console for sales, inventory, perception, and marketing
@@ -70,7 +80,7 @@ flowchart LR
     ingress --> comfy
 ```
 
-## Current Stack
+## Stack
 
 ### Frontend
 
@@ -107,6 +117,34 @@ flowchart LR
 - S3-backed model and asset strategy
 - route-managed Comfy exposure
 
+## Quick Start
+
+### 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
+```
+
 ## Repository Areas
 
 | Path | Purpose |
@@ -118,7 +156,7 @@ flowchart LR
 | `infrastructure/` | ingress, ops, deployment, and recovery artifacts |
 | `.Agent Context/` | working docs, bibels, strategy, and truth artifacts |
 
-## Core Runtime Surfaces
+## Runtime Coverage
 
 ### WebOS modules
 
@@ -147,7 +185,7 @@ flowchart LR
 - Wan 2.2 workflow assets exist locally
 - queue/gateway model exists and is being hardened into a canonical async path
 
-## Product Positioning
+## 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:
@@ -159,9 +197,9 @@ It is designed as a private deployment system for builders, channel partners, an
 - high-end marketing asset generation
 - portfolio-aware expansion over time
 
-## Current Reality
+## Current Delivery Status
 
-What is materially present now:
+Implemented now:
 
 - strong WebOS UI shell
 - real iOS implementation surface
@@ -170,7 +208,7 @@ What is materially present now:
 - Dream Weaver / Qwen / Wan workflow assets
 - browser-webcam Sentinel path using MediaPipe
 
-What is still being closed:
+Still being closed:
 
 - canonical CRM routes for `leads`, `chat_logs`, and `kanban`
 - unified CRM database contract
@@ -178,34 +216,6 @@ What is still being closed:
 - 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:
@@ -218,7 +228,7 @@ Velocity is being shaped toward:
 
 The current repo also includes the ingress and ops artifacts used to run this model today.
 
-## Operator Docs
+## Internal Truth Sources
 
 Key internal docs live under `.Agent Context/` and `infrastructure/`.
 Important current references include:
@@ -229,7 +239,7 @@ Important current references include:
 
 ## Status
 
-This is an active product repository, not a cleaned public SDK.
+This is an active product repository, not a cleaned SDK.
 Expect a mix of:
 
 - production-bound code