fix: complete Velocity-OS feature migration wiring

README.md

@@ -1,83 +1,149 @@
 # Velocity-OS
 
-> **The AI-Augmented Real Estate Operating System** — a production-grade, air-gapped, containerized appliance for luxury property sales teams.
+Velocity-OS is the simplified production shell for Project Velocity: an AI-assisted operating system for real estate sales, client intelligence, property media, campaign work, and admin control.
 
-Built on the Jobs/Ive mandate: *design is how it works, not just how it looks.*
+The goal is not to copy the old Project_Velocity UI screen-for-screen. The goal is to preserve the useful capabilities, reduce the surface area, and make the system usable through three clear work modes.
 
----
+## Architecture At A Glance
 
-## Architecture at a Glance
-
-```
+```text
 Velocity-OS/
-├── webos/          React 19 + Framer Motion + Zustand — 3-Pillar UX
-├── core/           FastAPI + PostgreSQL + Oracle NL Engine
-├── agents/         NemoClaw sandboxes (OpenShell policy)
-├── media-engine/   Dream Weaver gateway (ComfyUI async)
-├── perception/     MediaPipe WASM + QD scoring
-└── infrastructure/ K3s + ECR + MIG GPU + s5cmd model hydration
+|-- webos/          React 19, React Router, Framer Motion, Zustand, TanStack Query
+|-- core/           FastAPI, PostgreSQL access, CRM APIs, Oracle natural DB agent
+|-- media-engine/   Dream Weaver gateway for image generation / virtual staging
+|-- agents/         Agent/runtime integration surface
+|-- infrastructure/ Deployment, model hydration, gateway, and runtime operations
 ```
 
-## The 3-Pillar Model
+## The Three Pillars
 
-| Pillar | Route | Purpose |
-|---|---|---|
-| ⚡ **Command** | `/command` | Morning briefing — KPIs, Oracle NL, AI priority cards |
-| 🎯 **Pipeline** | `/pipeline` | Deal intelligence — Kanban, Client 360, Showroom |
-| 🎨 **Studio** | `/studio` | Asset hub — Properties, Dream Weaver, Campaigns |
-| ⚙ Control Room | `/control-room` | Admin-only — system, schema, users, GPU |
+| Pillar | Route | What It Replaces From Project_Velocity |
+| --- | --- | --- |
+| Command | `/command` | Dashboard, Oracle prompt surface, priority signals |
+| Pipeline | `/pipeline` and `/pipeline/:personId` | CRM, leads, Client 360, conversations, tasks, showroom flow |
+| Studio | `/studio` and `/studio/:propertyId` | Inventory, property pages, media gallery, Dream Weaver / Reimagine, campaigns |
+| Control Room | `/control-room/:panel?` | Admin settings, Oracle/schema controls, comms settings, users, model hydration |
 
-## GPU Architecture
+## Runtime Truths
 
-Target: **NVIDIA RTX 6000 Blackwell (96GB VRAM)**
+- The public app is served from `https://velocity.desineuron.in/`.
+- Frontend API calls go through the same origin unless `VITE_API_URL` is set.
+- Dream Weaver uses multipart image upload through `/dream-weaver`, then polls `/dream-weaver/status/{job_id}`, then downloads from `/dream-weaver/result/{job_id}`.
+- The deployed GPU reality is the Desineuron AWS GPU worker, currently oriented around `4 x NVIDIA L4` for inference/runtime work. Do not assume the placeholder RTX 6000/MIG text from older mock screens is operational truth.
+- Large model and media runtime assets belong on GPU NVMe, not Linux root disk.
 
-MIG partitioned into two concurrent slices:
-- **Slice 0 (48GB)** — SGLang: Qwen3.6 35B LLM inference
-- **Slice 1 (48GB)** — ComfyUI: Wan 2.2 + Qwen-Image staging
+## Oracle Canvas And JSON Schemas
 
-Zero-contention. No operator toggle required.
+Velocity-OS imports the Project_Velocity Oracle JSON codebook assets required for canvas/component planning:
 
-## Deployment (Air-Gapped Workstation)
+- `core/oracle/oracle/oracle_runtime_codebook_merged.json`
+- `core/oracle/oracle/oracle_template_seed_db.json`
 
-```bash
-# 1. Hydrate AI models from S3 (one-time, ~105GB)
-cd infrastructure/model-hydration
-./hydrate_models.sh
+The loader lives at:
 
-# 2. Apply K3s manifests
-kubectl apply -f infrastructure/k3s/namespaces/
-kubectl apply -f infrastructure/k3s/volumes/
-kubectl apply -f infrastructure/k3s/secrets/secrets-template.yaml  # fill real values first
-kubectl apply -f infrastructure/k3s/deployments/gpu-mig-config.yaml
-kubectl apply -f infrastructure/k3s/deployments/deployments.yaml
-kubectl apply -f infrastructure/k3s/services/services.yaml
-kubectl apply -f infrastructure/k3s/ingress/ingress.yaml
+- `core/oracle/oracle/codebook_service.py`
 
-# 3. Run DB init job
-kubectl wait --for=condition=complete job/db-init -n velocity-os --timeout=120s
+The loader now resolves the native Velocity-OS paths first, with legacy `backend/oracle` paths only as compatibility inputs. A quick sanity check should report the large runtime codebook:
 
-# 4. Access at https://velocity.local
+```powershell
+python -c "from core.oracle.oracle.codebook_service import codebook_service; print(codebook_service.stats())"
 ```
 
-## CI/CD Pipeline
+Expected current result:
 
-Internet-connected CI (GitLab) builds and cosign-signs images → pushes to AWS ECR.
-Ingress Box (LAN node) polls ECR every 5 min → verifies signature → SCP to air-gapped workstation → `k3s ctr images import` → `kubectl rollout restart`.
+```text
+example_count: 2395
+template_count: 1320
+source_summary includes runtime_merged:2395
+```
 
-**Unsigned images are physically rejected at the Ingress Box.**
+Oracle natural query flow:
 
-## Design System
+1. The user asks a question in Command.
+2. `webos/src/pillars/command/OracleBar.tsx` posts `{ prompt, context }` to `/api/oracle/query`.
+3. `core/api/api/routes_oracle.py` calls the Oracle natural DB agent.
+4. The result returns SQL-backed rows, columns, warnings, and source tables.
+5. `OracleResultCard` renders the result as a metric, list, or table based on the returned data shape.
 
-- **Base**: `hsl(225, 25%, 8%)` deep navy
-- **Accent**: `#7C3AED` Velocity Violet (AI/actions)
-- **Intent**: `#F59E0B` Amber (QD / alerts)
-- **Glass**: `backdrop-filter: blur(20px)` · `rgba(255,255,255,0.05)` panels
-- **Motion**: `300ms cubic-bezier(0.4, 0, 0.2, 1)` standard · spring for reveals
+## Studio And Reimagine
 
-## Immutability Constraint
+Studio uses:
 
-`Project_Velocity` (source) is **read-only**. All files in this repository are copies + refactors. No source files were modified or deleted.
+- `webos/src/shared/hooks/useStudio.ts` for inventory/property normalization.
+- `webos/src/pillars/studio/StudioPillar.tsx` for property and campaign lists.
+- `webos/src/pillars/studio/PropertyEntity.tsx` for the property detail page.
+- `webos/src/pillars/studio/ReimaginePanel.tsx` for Dream Weaver.
 
----
+Reimagine currently supports:
+
+- source room image upload
+- room type selection
+- freeform styling prompt
+- async Dream Weaver job submission
+- polling without blocking the page
+- generated image preview
+- generated image download/open actions
+
+## Control Room
+
+Control Room is admin-only and route-driven:
+
+- `/control-room/system`
+- `/control-room/oracle-admin`
+- `/control-room/comms-config`
+- `/control-room/users`
+- `/control-room/models`
+- `/control-room/meta`
+
+The selected panel is derived from the URL. This avoids stale local state when users navigate directly or return from another page.
+
+## Local Development
+
+Frontend:
+
+```powershell
+cd webos
+npm install
+npm run dev
+```
+
+Production build check:
+
+```powershell
+cd webos
+npm run type-check
+npm run build
+```
+
+Backend:
+
+```powershell
+cd core
+python -m uvicorn api.main:app --host 127.0.0.1 --port 8001 --reload
+```
+
+Important environment variables:
+
+- `VITE_API_URL` overrides the frontend API origin.
+- `VITE_DREAM_WEAVER_URL` overrides Dream Weaver gateway origin.
+- `VITE_DREAM_WEAVER_API_KEY` adds the optional Dream Weaver gateway key.
+- Backend database settings are provided by the running deployment environment.
+
+## Verification Checklist
+
+Run before handoff:
+
+- `npm run type-check` from `webos`
+- `npm run build` from `webos`
+- Oracle codebook stats check from repo root
+- Login to `https://velocity.desineuron.in/`
+- Open Command and submit an Oracle question
+- Open Pipeline, switch Board/List, open a client, return to Pipeline without refresh
+- Open Studio, switch Properties/Campaigns, open a property, use Reimagine upload + prompt
+- Open Control Room and verify dark theme across all panels
+
+## Known Engineering Notes
+
+- The production build still warns that the Three.js vendor chunk is large. This is not a functional failure, but Studio 3D/media should remain lazy-loaded and can be split further later.
+- The app intentionally keeps Project_Velocity as a source/reference repository. Velocity-OS should import only the required code/data assets, not blindly mirror the old structure.
 
-*Velocity-OS v2.0 · Desineuron · © 2026*