feat: Build the Dream Weaver interior restyling workflow to preserve room geometry while changing aesthetics (#5)

#3 Self-approved and unit tests passed with flying colors. Co-authored-by: Sagnik <sagnik7896@gmail.com> Reviewed-on: #5
2026-03-10 01:36:27 +05:30
parent cb6c752c8e
commit 55bb5e5a90
53 changed files with 11956 additions and 2222 deletions
--- a/Context/Bibels/Project
+++ b/Context/Bibels/Project
--- a/Context/Bibels/gitea_contribution_guide.md
+++ b/Context/Bibels/gitea_contribution_guide.md
@@ -0,0 +1,457 @@
+# Project Velocity — Gitea Feature Contribution Guide
+
+**Version:** 1.1  
+**Last Updated:** 2026-03-07  
+**Upstream Repository (Sagnik's):** `https://git.desineuron.in/sagnik/Project_Velocity`  
+**Your Fork:** `https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity`
+
+> This document is the **canonical guide** for every team member contributing to Project Velocity.  
+> The team uses a **Fork-based workflow**: each contributor has their own fork of Sagnik's repository. All features are developed in your fork and merged into the upstream via Pull Requests.  
+> It covers the full lifecycle: Issue → Branch → Commit → Push → Pull Request — both via the **CLI** and via **Antigravity Source Control UI**.
+
+### How the Fork Model Works
+
+```text
+[upstream] sagnik/Project_Velocity   ← the source of truth
+       ↑ Pull Requests
+[your fork] <you>/Project_Velocity   ← where you develop
+       ↑ git push
+[local] /your/machine/Project_Velocity
+```
+
+- `upstream` = Sagnik's repo — you **pull** from here to stay in sync.
+- `origin` = Your fork — you **push** your branches here.
+- PRs go **from your fork → upstream**.
+
+---
+
+## Table of Contents
+
+1. [Naming Conventions](#naming-conventions)
+2. [One-Time Setup — Fork & Remotes](#one-time-setup--fork--remotes)
+3. [Step 0 — Pre-flight: Populate `.gitignore` & `.gitkeep`](#step-0--pre-flight)
+4. [Step 1 — Create a Gitea Issue](#step-1--create-a-gitea-issue)
+5. [Step 2 — Sync with Upstream Before Branching](#step-2--sync-with-upstream-before-branching)
+6. [Step 3 — Create a Feature Branch](#step-3--create-a-feature-branch)
+7. [Step 4 — Make Your Changes & Commit](#step-4--make-your-changes--commit)
+8. [Step 5 — Push the Branch to Your Fork](#step-5--push-the-branch-to-your-fork)
+9. [Step 6 — Create a Pull Request (Fork → Upstream)](#step-6--create-a-pull-request-fork--upstream)
+10. [Quick Reference — CLI Cheat Sheet](#quick-reference--cli-cheat-sheet)
+
+---
+
+## Naming Conventions
+
+Consistent naming keeps the repository clean and makes history easy to read.
+
+| Type | Format | Example |
+|------|--------|---------|
+| **Issue Title** | `feat : <Short description>` | `feat : Build the native SwiftUI app shell` |
+| **Branch Name** | `feat/#<issue-number>` | `feat/#12` |
+| **Commit Message** | `feat(scope): <what changed>` or `fix(scope): <what was fixed>` | `feat(ios): add Dashboard, Oracle and Sentinel tab views` |
+
+> Use `fix`, `chore`, `docs`, `refactor`, or `test` instead of `feat` where appropriate.
+
+---
+
+## One-Time Setup — Fork & Remotes
+
+Do this **once** when you first clone your fork onto a new machine. You only need to do this once per machine.
+
+### 1. Clone your fork
+
+```bash
+git clone https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git
+cd Project_Velocity
+```
+
+### 2. Add the upstream remote (Sagnik's repo)
+
+```bash
+git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git
+```
+
+### 3. Verify your remotes
+
+```bash
+git remote -v
+```
+
+You should see **two** remotes:
+
+```text
+origin    https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git (fetch)
+origin    https://git.desineuron.in/<YOUR_USERNAME>/Project_Velocity.git (push)
+upstream  https://git.desineuron.in/sagnik/Project_Velocity.git (fetch)
+upstream  https://git.desineuron.in/sagnik/Project_Velocity.git (push)
+```
+
+> ⚠️ If you only see `origin`, you haven't added `upstream` yet. Run step 2 above.
+
+### Via Antigravity Source Control UI
+
+Antigravity does not have a direct UI button to add a new remote. Do this once via the terminal:
+1. Open a terminal inside Antigravity (`Ctrl + `` ` `` ` `).
+2. Run: `git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git`
+3. The upstream remote will now appear in the **Graph** section of Source Control.
+
+---
+
+## Step 0 — Pre-flight
+
+Before pushing anything, ensure these files are properly configured at the **root of the repository**.
+
+### `.gitignore`
+A root `.gitignore` already exists at the repository root. It covers:
+- **macOS** system files (`DS_Store`, etc.)
+- **Node / Vite / React** (`app/node_modules/`, `app/dist/`)
+- **Xcode / Swift** (derived data, `.xcuserdata`, build artifacts)
+- **Python / ComfyUI** (`__pycache__`, `.venv`, model weights)
+- **Infrastructure** (Terraform state, secrets)
+
+**You should never commit:**
+- API keys or secrets (`.env` files are ignored)
+- `node_modules/` directory
+- Xcode `DerivedData/` or `.xcuserdata/`
+- Python virtual environments (`.venv/`, `venv/`)
+
+### `.gitkeep`
+A `.gitkeep` file is used to **track an otherwise empty directory** in Git (Git does not track empty folders).
+
+**When to add one:** If you create a new directory that should be committed but has no files yet, add an empty `.gitkeep` file inside it:
+```bash
+touch path/to/your/new-empty-folder/.gitkeep
+```
+
+---
+
+## Step 1 — Create a Gitea Issue
+
+Every feature or bug fix must start with a **Gitea Issue**. Issues must be created in **Sagnik's upstream repository** — not your fork. The upstream is the source of truth for the project, and `Closes #<N>` in your PR description will only auto-close the issue if it lives in the same repo your PR targets.
+
+### Via Browser (Gitea Web UI)
+
+1. Go to **Sagnik's upstream repo**: `https://git.desineuron.in/sagnik/Project_Velocity`.
+2. Click on the **Issues** tab.
+3. Click the green **New Issue** button.
+4. Fill in the title using the format:
+   ```
+   feat : <Short description of your feature>
+   ```
+   **Example:**
+   ```
+   feat : Build the native SwiftUI app shell mirroring the WebOS interface
+   ```
+5. Add a description explaining:
+   - **What** you are building.
+   - **Why** it is needed.
+   - **Acceptance criteria** (what "done" looks like).
+6. Assign the issue to yourself.
+7. Click **Submit**. Note down the **Issue Number** (e.g., `#12`) — you will need it for the branch name.
+
+### Via CLI (using `curl` or Gitea API)
+
+```bash
+# Replace placeholders before running
+GITEA_URL="https://git.desineuron.in"
+GITEA_TOKEN="<YOUR_PERSONAL_ACCESS_TOKEN>"    # Generate at: Profile → Settings → Applications
+REPO_OWNER="sagnik"                           # Issues go in the UPSTREAM repo
+REPO_NAME="Project_Velocity"
+ISSUE_TITLE="feat : <Short description of your feature>"
+ISSUE_BODY="<Detailed description of what you are building and why>"
+
+curl -s -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d "{
+    \"title\": \"$ISSUE_TITLE\",
+    \"body\": \"$ISSUE_BODY\",
+    \"assignees\": [\"$REPO_OWNER\"]
+  }"
+```
+> The response JSON will contain the `number` field — **this is your issue number**.
+
+---
+
+## Step 2 — Sync with Upstream Before Branching
+
+Before creating a feature branch, **always** pull the latest changes from **`upstream`** (Sagnik's repo) — not from your fork (`origin`). This ensures your work starts from the most up-to-date version of the project.
+
+### Via CLI
+
+```bash
+# Navigate to your project root
+cd "/path/to/Project_Velocity"
+
+# Switch to main
+git checkout main
+
+# Fetch all branches from upstream
+git fetch upstream
+
+# Merge upstream/main into your local main
+git merge upstream/main
+
+# (Optional) Push the synced main to your own fork to keep it up to date
+git push origin main
+```
+
+> **Why `upstream` and not `origin`?**  
+> `origin` is your personal fork — it only knows about changes you've pushed.  
+> `upstream` is Sagnik's repository — the actual source of truth for the project.
+
+### Via Antigravity Source Control UI
+
+Antigravity's sync button pulls from `origin` by default. To sync from upstream, use the terminal:
+
+1. Open a terminal in Antigravity (`Ctrl + `` ` `` ` `).
+2. Run:
+   ```bash
+   git fetch upstream && git merge upstream/main
+   ```
+3. Then click the **↺ (Refresh)** icon in the Source Control panel to refresh the view.
+4. Confirm the **Graph** section shows your local `main` is aligned with `upstream/main`.
+
+---
+
+## Step 3 — Create a Feature Branch
+
+Branch name format: **`feat/#<ISSUE_NUMBER>`**
+
+**IMPORTANT:** Replace `<ISSUE_NUMBER>` with the actual number from Step 1.
+
+### Via CLI
+
+```bash
+# Make sure you are on main first
+git checkout main
+
+# Create and switch to the new branch
+git checkout -b feat/#<ISSUE_NUMBER>
+
+# Example:
+# git checkout -b feat/#12
+```
+
+### Via Antigravity Source Control UI
+
+1. In the **Source Control** panel, look at the bottom **Graph** section.
+2. Click on the **branch name** shown next to the current `HEAD` commit (e.g., `main`).
+3. A branch picker will appear at the top of the screen.
+4. Type the new branch name exactly: `feat/#<ISSUE_NUMBER>`
+5. Select **"Create new branch: feat/#<ISSUE_NUMBER>"** from the dropdown.
+6. Confirm. Your working branch is now set to the new feature branch.
+
+---
+
+## Step 4 — Make Your Changes & Commit
+
+### Stage Your Files
+
+#### Via CLI
+
+```bash
+# Stage specific files
+git add path/to/changed/file.swift
+
+# Stage all changed/new files at once (use with care)
+git add .
+
+# Review what is staged before committing
+git status
+```
+
+#### Via Antigravity Source Control UI
+
+1. In the **Source Control** panel, you will see two sections:
+   - **Staged Changes** — files ready to be committed.
+   - **Changes** — files that are modified but not yet staged.
+2. To **stage a file**: Hover over it in the **Changes** section and click the **`+`** (plus) icon that appears on the right.
+3. To **unstage a file**: Hover over it in **Staged Changes** and click the **`-`** (minus) icon.
+4. To **stage all changes at once**: Click the **`+`** (plus) icon next to the **Changes** section header.
+
+### Write Your Commit Message
+
+Use the **Conventional Commits** format:
+```
+<type>(scope): <short summary>
+```
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | A new feature |
+| `fix` | A bug fix |
+| `docs` | Documentation changes only |
+| `refactor` | Code restructured, no behavior change |
+| `chore` | Config, build scripts, dependencies |
+| `test` | Adding or fixing tests |
+
+**Example commit messages:**
+```
+feat(ios): add Dashboard, Oracle, Sentinel, and Inventory tab views
+
+feat(ios): implement AppStore with lead, visitor, and metrics models
+
+fix(ios): correct ARSunOverlayView coordinate calculations
+
+docs(agent): add velocity_ios_bible.md technical reference
+```
+
+### Commit
+
+#### Via CLI
+
+```bash
+git commit -m "<type>(scope): <short summary of your change>"
+
+# Example:
+# git commit -m "feat(ios): add Dashboard, Oracle, Sentinel tab views mirroring WebOS"
+```
+
+#### Via Antigravity Source Control UI
+
+1. Ensure your files are in the **Staged Changes** section.
+2. Click the **Message** text field at the top of the Source Control panel (placeholder: `Message (⌘Enter to com...)`).
+3. Type your commit message following the Conventional Commits format above.
+4. *(Optional)* Click **Generate ✦** to let Antigravity AI suggest a commit message based on your staged diffs — review it before accepting.
+5. Click the blue **✓ Commit** button (or press `⌘ + Enter`) to commit.
+
+---
+
+## Step 5 — Push the Branch to Gitea
+
+### Via CLI
+
+```bash
+# Push your feature branch to the remote (origin)
+git push origin feat/#<ISSUE_NUMBER>
+
+# Example:
+# git push origin feat/#12
+```
+
+If this is the **first push** of a new branch, Git may ask you to set the upstream:
+```bash
+git push --set-upstream origin feat/#<ISSUE_NUMBER>
+```
+
+### Via Antigravity Source Control UI
+
+1. After committing, look at the **Changes** header in the Source Control panel.
+2. Click the **`...` (More Actions)** menu (top-right of the Changes section header).
+3. Select **Push** from the dropdown.
+4. Alternatively, click the **↑ (Publish/Push)** cloud icon if visible next to the branch name in the status bar or Graph section.
+5. Antigravity will push your local feature branch to `origin/feat/#<ISSUE_NUMBER>` on Gitea.
+
+---
+
+## Step 6 — Create a Pull Request (Fork → Upstream)
+
+Since you are working on a fork, your PR goes **from your fork's feature branch → Sagnik's upstream `main`**. This is a cross-repository PR.
+
+### Via Browser (Gitea Web UI)
+
+1. Go to **Sagnik's upstream repo**: `https://git.desineuron.in/sagnik/Project_Velocity`.
+2. Click the **Pull Requests** tab → **New Pull Request**.
+3. Click **"compare across forks"** (Gitea shows this option when creating a cross-fork PR).
+4. Set up the PR direction:
+   - **Base repository:** `sagnik/Project_Velocity` — **Base branch:** `main`
+   - **Head repository:** `<YOUR_USERNAME>/Project_Velocity` — **Compare branch:** `feat/#<ISSUE_NUMBER>`
+5. Fill in the PR form:
+   - **Title:** `feat(scope): <Short description>`
+   - **Description:**
+   ```
+   ## Summary
+   <What does this PR do?>
+
+   ## Changes
+   - <List the main changes>
+
+   ## Related Issue
+   Closes #<ISSUE_NUMBER>
+   ```
+6. Assign **Sagnik** as reviewer.
+7. Click **Create Pull Request**.
+
+> 💡 **Alternatively**, after you push your branch to your fork (`origin`), Gitea may show a yellow banner inside Sagnik's upstream repo prompting you to create a cross-fork PR automatically. Click that if it appears.
+
+### Via CLI (using Gitea API)
+
+For a cross-fork PR, the `head` must include your fork username as a prefix.
+
+```bash
+GITEA_URL="https://git.desineuron.in"
+GITEA_TOKEN="<YOUR_PERSONAL_ACCESS_TOKEN>"
+UPSTREAM_OWNER="sagnik"          # Sagnik's username
+UPSTREAM_REPO="Project_Velocity"
+YOUR_USERNAME="<YOUR_USERNAME>"   # Your Gitea username
+FEATURE_BRANCH="feat/#<ISSUE_NUMBER>"
+PR_TITLE="feat(scope): <Short description>"
+PR_BODY="## Summary\n<What does this PR do?>\n\n## Changes\n- <List main changes>\n\n## Related Issue\nCloses #<ISSUE_NUMBER>"
+
+curl -s -X POST "$GITEA_URL/api/v1/repos/$UPSTREAM_OWNER/$UPSTREAM_REPO/pulls" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d "{
+    \"title\": \"$PR_TITLE\",
+    \"body\": \"$PR_BODY\",
+    \"head\": \"$YOUR_USERNAME:$FEATURE_BRANCH\",
+    \"base\": \"main\"
+  }"
+```
+
+> Note the `head` format: `"<YOUR_USERNAME>:feat/#<ISSUE_NUMBER>"` — this tells Gitea the branch lives in your fork, not the upstream.
+
+---
+
+## Quick Reference — CLI Cheat Sheet
+
+Copy and fill in the placeholders (`<...>`) before running.
+
+```bash
+# ── ONE-TIME SETUP (do this once per machine) ─────────────────
+cd "/path/to/Project_Velocity"
+git remote add upstream https://git.desineuron.in/sagnik/Project_Velocity.git
+git remote -v   # verify: you should see both origin and upstream
+
+# ── 1. Create the Gitea Issue ──────────────────────────────────
+# Go to Gitea web UI or use the curl command in Step 1
+# Title format: feat : <Short description>
+# Note the issue number: <ISSUE_NUMBER>
+
+# ── 2. Sync from upstream main ────────────────────────────────
+git checkout main
+git fetch upstream
+git merge upstream/main
+git push origin main              # keep your fork in sync too
+
+# ── 3. Create & switch to feature branch ─────────────────────
+git checkout -b feat/#<ISSUE_NUMBER>
+
+# ── 4. Stage & Commit ─────────────────────────────────────────
+git add .
+git status                        # double-check what is staged
+git commit -m "<type>(scope): <short summary>"
+
+# ── 5. Push branch to YOUR FORK (origin) ──────────────────────
+git push origin feat/#<ISSUE_NUMBER>
+
+# ── 6. Create Pull Request (fork → upstream) ──────────────────
+# Go to: https://git.desineuron.in/sagnik/Project_Velocity
+# Pull Requests → New Pull Request → Compare across forks
+# head: <YOUR_USERNAME>/Project_Velocity : feat/#<ISSUE_NUMBER>
+# base: sagnik/Project_Velocity          : main
+```
+
+---
+
+## Tips & Best Practices
+
+- **One issue = one branch = one PR.** Keep your changes focused.
+- **Always sync from `upstream`, not `origin`.** Your fork doesn't automatically know about changes Sagnik pushes. Run `git fetch upstream && git merge upstream/main` regularly.
+- **Commit often, push when ready.** Small commits make code review easier.
+- **Never commit directly to `main`.** Always work on a feature branch.
+- **Push to `origin`, PR to `upstream`.** Push goes to your fork. The PR targets Sagnik's repo.
+- **Reference issues in PRs.** Using `Closes #<ISSUE_NUMBER>` auto-closes the issue on merge.
+- **Personal Access Token:** Generate it once at `https://git.desineuron.in` → Profile → Settings → Applications → Generate Token. Store it securely (e.g., in your password manager or macOS Keychain).
+- **Keep your fork's `main` clean.** Never push feature work directly to `origin/main` — only merge `upstream/main` into it to stay current.
--- a/Context/Bibels/velocity_component_reference.md
+++ b/Context/Bibels/velocity_component_reference.md
@@ -0,0 +1,517 @@
+# Project Velocity — Component Reference
+
+> **Stack:** React + TypeScript · Framer Motion · Tailwind CSS · Recharts · Three.js / React Three Fiber · Zustand (`useStore`)
+
+---
+
+## User Flow Overview
+
+```
+App Start
+  └─ Not authenticated → LoginScreen
+       ├─ FaceID tap → 2.5s scan animation → login()
+       └─ "Use password instead" → password form → login()
+            └─ Authenticated → MainLayout
+                 ├─ Sidebar (always visible, collapsible)
+                 └─ Active Module (one of 5 pages)
+```
+
+---
+
+## 0 · Login Page
+**File:** [src/components/layout/LoginScreen.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/layout/LoginScreen.tsx)
+
+The entry gate to the OS. Simulates a biometric-first enterprise auth flow.
+
+| Component / Element | Function | Reason |
+|---|---|---|
+| **Background ambient orbs** | Two animated `motion.div` blobs with `blur-3xl` | Creates depth and premium feel on an otherwise empty screen |
+| **Login Card** | `motion.div` spring-animated card, `rounded-3xl`, glassmorphism surface | Focuses the user's eye; spring entry animation feels native/iOS-like |
+| **Logo icon** (`Scan`) | Glowing blue square icon with `boxShadow` pulse | Brand mark; reinforces the "scanning / intelligence" theme |
+| **FaceID Button** | Circular `motion.button`; on click triggers `isScanning` state → conic-gradient spinner + pulsing ring for 2.5s, then calls [login()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#247-248) | Primary auth path — simulates biometric scan UX |
+| **"Use password instead"** | Text button that sets `showPassword = true` | Fallback for when FaceID isn't available |
+| **Password Form** | `AnimatePresence` swap; `Lock` icon input + Submit button + "Back to FaceID" | Secondary auth path; accepts `"admin"` or empty string |
+| **Error message** | `motion.p` slide-in red text | Inline validation feedback |
+| **Footer** | `"Secured by On-Premise Python Backend"` | Communicates data sovereignty — important for enterprise real estate clients |
+
+**State:** `isScanning`, `showPassword`, `password`, [error](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#535-536)
+
+---
+
+## 1 · Dashboard
+**File:** [src/components/modules/Dashboard.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx)
+
+The command center. Shows live KPIs, sentiment, system health, AI chat, and lead velocity at a glance.
+
+### Layout
+4-column CSS grid. Top row: 4 KPI cards. Middle row: Sentiment (2-col) + System Health (2-col). Bottom row: AI Chat (2-col, 2-row) + Lead Velocity (2-col, 2-row).
+
+### Design Tokens
+`GLASS` object — shared `background`, `border`, `backdropFilter`, `boxShadow` applied to every widget for visual consistency.
+
+---
+
+### Base Components
+
+| Component | Function | Reason |
+|---|---|---|
+| **[Widget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Sentinel.tsx#42-74)** | Base `motion.div` wrapper: `rounded-2xl`, `overflow-hidden`, GLASS styles, entry animation (`opacity 0→1, y 18→0`), optional `glow` prop for stronger box-shadow | Single source of truth for all panel styling — change once, updates everywhere |
+| **[LiveBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#143-156)** | Green pulsing dot + "Live" text | Communicates real-time data feed to the user |
+| **[UpBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#157-166)** | Green `ArrowUpRight` + percentage text | Shows positive trend at a glance |
+
+---
+
+### KPI Cards (top row)
+
+| Component | Metric | Glow Color | Function |
+|---|---|---|---|
+| **[ActiveVisitorsWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#167-182)** | `metrics.activeVisitors` | Blue `rgba(59,130,246,0.22)` | Shows how many people are physically in the showroom right now |
+| **[TodayLeadsWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#183-198)** | `metrics.todayLeads` + converted count | Cyan `rgba(34,211,238,0.18)` | Tracks daily lead capture volume |
+| **[ConversionRateWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#199-214)** | `metrics.conversionRate %` vs industry avg | Indigo `rgba(99,102,241,0.20)` | Key sales efficiency metric |
+| **[TopPerformerWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#215-255)** | Hardcoded "Rania Al-Farsi" + deal stats | Amber `rgba(251,191,36,0.22)` | Gamification / motivation — highlights the top salesperson |
+
+All four use **[StatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#95-142)** internally:
+
+| [StatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#95-142) sub-element | Function |
+|---|---|
+| Large radial glow blob (bottom-right) | Ambient lighting effect matching reference image style |
+| Secondary softer bloom (bottom-left) | Adds depth to the lighting |
+| Icon (top-left) | Visual identifier for the metric type |
+| Badge (top-right) | Live / trend indicator |
+| Label (uppercase, muted) | Metric name |
+| Value (large `text-4xl`) | The number — primary information |
+| Sub-text | Context (e.g. "In Experience Center") |
+
+---
+
+### Middle Row
+
+#### [SentimentGauge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/InspectorPanel.tsx#5-53)
+Shows the real-time emotional temperature of the showroom.
+
+| Element | Function |
+|---|---|
+| Large blue glow bloom (bottom) | Lighting effect |
+| Secondary indigo bloom (left) | Depth |
+| Progress bar | Animated `motion.div` width from 0→value%; gradient blue fill with `boxShadow` glow |
+| Label ("Showroom Vibe") | Context |
+| Dynamic label ("Excellent" / "Good" / "Needs Attention") | Color-coded quick read |
+
+#### [SystemHealth](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#312-402)
+Shows CPU, GPU, Memory, Temperature of the on-premise backend server.
+
+| Element | Function |
+|---|---|
+| Multi-color glow bloom (blue left, cyan right, purple center) | Lighting effect |
+| 4× SVG circular arc gauges | Each animates `strokeDashoffset` from full→partial; `drop-shadow` filter for glow |
+| "Optimal" badge | Quick system status |
+
+---
+
+### Bottom Row
+
+#### [AIChatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#491-619) ("AI Onboard")
+An embedded AI assistant for deal strategy.
+
+| Element | Function |
+|---|---|
+| Avatar + "Online" badge | Humanizes the AI; shows it's active |
+| Message list | Scrollable chat history; assistant messages left-aligned, user messages right-aligned with blue bubble |
+| Auto-scroll (`useRef` + `scrollIntoView`) | Keeps latest message visible |
+| Typing indicator (3 animated dots) | Simulates AI thinking |
+| Input + Send button | User query entry |
+| Sparkle icon button | Triggers AI response simulation |
+| Mock response engine | Cycles through pre-written strategic responses |
+
+**State:** `messages[]`, `input`, `isTyping`, `isFocused`
+
+#### [LeadVelocityChart](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#403-483)
+Area chart showing generated vs. closed leads over time.
+
+| Element | Function |
+|---|---|
+| Large blue + cyan glow blooms | Lighting effect |
+| `AreaChart` (Recharts) | Visualizes lead pipeline velocity over the day |
+| Two `Area` series (Generated / Closed) | Blue = generated leads, Cyan = closed deals |
+| SVG gradient fills | Fade from color to transparent for depth |
+| Custom `Tooltip` | Glassmorphism styled tooltip on hover |
+| Legend dots | Color-coded series labels |
+
+---
+
+## 2 · The Oracle
+**File:** [src/app/oracle/page.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx)
+
+AI-powered CRM canvas. A natural language interface that renders different data views based on user prompts.
+
+### Layout
+Full-height split: **top AI insight banner** + **main canvas** (left: data view, right: AI chat bar).
+
+### User Flow
+```
+User types prompt → queryOracle() → returns { view, data, insight }
+  → Canvas switches to matching view (pipeline / team / timeline / map / calendar)
+  → AI insight banner updates
+  → Conversation history appended
+```
+
+---
+
+| Component | Function | Reason |
+|---|---|---|
+| **AI Insight Banner** | Full-width blue-tinted bar showing the AI's top insight for the current view | Surfaces the most important takeaway without the user having to read the full data |
+| **View Selector Pill** | Dropdown showing current view name (e.g. "Pipeline") | Lets user manually switch canvas views without typing |
+| **[GlassFrame](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#65-72)** | Wrapper `div` with `GLASS_PANEL` styles | Consistent glassmorphism container for all canvas panels |
+
+---
+
+### Canvas Views
+
+#### Kanban Pipeline (`pipeline`)
+| Element | Function |
+|---|---|
+| 4 columns (New Leads / Qualified / Proposal Sent / Negotiation) | Represents deal stages |
+| [PipelineCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#73-102) | Each deal: avatar, name, company, deal value badge; hover → blue glow border |
+| Column count badge | Shows number of deals per stage |
+
+#### Team Performance (`team_performance`)
+| Element | Function |
+|---|---|
+| `LineChart` (Recharts) | Shows individual rep performance over time |
+| Rep rows with avatar + stats | Name, deals closed, revenue, win rate |
+| Rank badges | Visual hierarchy of performance |
+
+#### Account Timeline (`account_timeline`)
+| Element | Function |
+|---|---|
+| Timeline entries | Chronological activity log per account |
+| Activity type icons | Call / Email / Meeting / Note |
+| Contact cards | Avatar + name + company + last activity |
+
+#### Geographic Lead Map (`lead_map`)
+| Element | Function |
+|---|---|
+| Map placeholder with pin markers | Geographic distribution of leads |
+| Lead count by region | Quantifies opportunity density |
+
+#### Calendar & Tasks (`calendar_tasks`)
+| Element | Function |
+|---|---|
+| Task list with due dates | Upcoming follow-ups and viewings |
+| Priority badges | High / Medium / Low |
+| Calendar grid | Visual scheduling view |
+
+---
+
+### AI Chat Bar (right panel)
+| Element | Function |
+|---|---|
+| Conversation history | Shows user prompts + AI responses |
+| Prompt mode selector | Dropdown to pick a pre-set view type |
+| Text input | Free-form natural language query |
+| Voice button ([Mic](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#525-543)) | Voice input trigger |
+| Send button | Submits query |
+| Sample prompt chips | One-click example queries to guide the user |
+
+---
+
+## 3 · The Sentinel
+**File:** [src/components/modules/Sentinel.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Sentinel.tsx)
+
+Real-time visitor intelligence. Tracks people physically in the showroom using AI facial analysis.
+
+### Layout
+Top row: 4 KPI stat cards. Middle: Zone Analytics (left) + AI Strategic Insights (right). Bottom: Sentiment Distribution (left) + Journey River (center) + Alert Panel (right).
+
+---
+
+### KPI Cards (top row)
+
+| Component | Metric | Accent | Function |
+|---|---|---|---|
+| **Active Visitors** | Live count | Green | How many people are in the building right now |
+| **Avg Sentiment** | % score | Blue | Overall emotional mood of all tracked visitors |
+| **Detection Accuracy** | % confidence | Purple | AI model confidence — trust indicator |
+| **Tracked Today** | Unique faces | Amber | Total unique individuals seen today |
+
+All use a shared `StatCard` pattern with icon, label, large value, and sub-text.
+
+---
+
+### Zone Analytics
+| Element | Function |
+|---|---|
+| Zone rows (A–D) | Main Showroom, Penthouse Gallery, Amenity Deck VR, Reception |
+| Visitor count per zone | How many people are in each area |
+| Sentiment % per zone | Color-coded: green (high) → amber (medium) → red (low) |
+| Zone letter badge | Quick visual identifier |
+
+**Reason:** Helps sales staff know where to focus attention — e.g. if Penthouse Gallery has 3 visitors at 85% sentiment, send a senior agent there.
+
+---
+
+### AI Strategic Insights
+| Element | Function |
+|---|---|
+| 4 insight cards (2×2 grid) | One per tracked company/lead |
+| Company name + deal stage badge | Context |
+| AI-generated insight text | Behavioral analysis (e.g. "Key decision maker showed high engagement during VR tour") |
+| Sentiment label (Positive / Neutral / Negative) | Color-coded quick read |
+| "LIVE ANALYSIS" badge | Communicates real-time processing |
+
+**Reason:** Converts raw behavioral data into actionable sales intelligence — the core value prop of the Sentinel.
+
+---
+
+### Sentiment Distribution
+| Element | Function |
+|---|---|
+| 5 emotion rows (Excited / Interested / Neutral / Confused / Disinterested) | Breakdown of visitor emotional states |
+| Emoji icons | Quick visual recognition |
+| Animated progress bars | Width proportional to count |
+| Count numbers | Exact figures |
+
+---
+
+### Journey River
+**File:** `src/components/sentinel/JourneyRiver/`
+
+The most complex visualization — an animated SVG path connecting tracked leads through their deal stages.
+
+| Sub-component | Function |
+|---|---|
+| **[JourneyRiver](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/index.tsx#162-284) (index)** | Container: lead list (left) + SVG canvas (center) + detail panel (right) |
+| **Lead list** | Scrollable list of tracked companies with sentiment score badges; click to select |
+| **[RiverPath](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/RiverPath.tsx#25-240)** | Draws a smooth bezier curve from lead entry point to current deal stage; animated `pathLength` on mount; glow shadow duplicate path |
+| **Sentiment Axis bar** | Horizontal gradient bar (red→amber→green) showing the sentiment spectrum |
+| **Detail Panel** | Right-side panel showing selected lead's last interaction (call/meeting), sentiment score gauge, and summary text |
+
+**Reason:** Makes the abstract concept of "deal pipeline" spatial and emotional — you can literally see the path a lead has taken.
+
+---
+
+### Alert Panel
+| State | Elements | Function |
+|---|---|---|
+| **Active** (amber) | `AlertTriangle` icon + "Sentiment Alert" title + message + timestamp | Notifies staff of a visitor showing negative signals |
+| **Clear** (green) | `ScanFace` icon + "All Clear" + "No alerts at this time" | Confirms no action needed |
+
+`AnimatePresence` with `mode="wait"` handles the transition. Fixed `minHeight` prevents layout shift between states.
+
+---
+
+## 4 · Inventory
+**File:** [src/components/modules/Inventory.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx)
+
+Full property management system for the building's units. Browse, filter, view in 3D, and inspect floor plans.
+
+### Layout
+Top: 4 stat counters. Below: search + filter bar. Main: 2-column unit card grid (left) + Google Maps embed (right).
+
+---
+
+### Stat Counters (top row)
+
+| Counter | Color | Function |
+|---|---|---|
+| **Total Units** | Blue | Total portfolio size |
+| **Available** | Green | Units ready to sell |
+| **Reserved** | Amber | Units with active interest |
+| **Sold** | Purple | Completed transactions |
+
+Each has an animated progress bar showing the percentage of total.
+
+---
+
+### Filter Bar
+| Element | Function |
+|---|---|
+| Search input | Text filter on unit number, type, view |
+| Filter pills (All Units / Available / Reserved / Sold / On Hold) | Status filter |
+| Grid/List toggle buttons | Switch between card grid and compact list view |
+
+---
+
+### [UnitCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#431-560)
+The primary browsing unit. Clicking opens [PropertyDetailModal](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#216-430).
+
+| Element | Function |
+|---|---|
+| Status glow (top-right corner) | Ambient color: green=available, amber=reserved, purple=sold |
+| "Unit Folder" label | Mimics a file system metaphor |
+| Unit number + floor | Primary identifier |
+| [StatusBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#57-74) | Color-coded pill: Available / Reserved / Sold / On Hold |
+| **Image → 3D preview on hover** | Static photo at rest; on `mouseEnter` swaps to a live Three.js [Canvas](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#505-513) with `autoRotate` | Wow factor — makes browsing feel like a product showcase |
+| Type / Area / View tags | Key specs at a glance |
+| Price | Primary decision metric |
+| **3D Viewer button** | Opens [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732) in `3d` mode |
+| **Blueprint button** | Opens [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732) in `blueprint` mode |
+
+---
+
+### [PropertyDetailModal](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#216-430)
+Full-screen overlay with complete unit information.
+
+| Section | Elements | Function |
+|---|---|---|
+| Header bar | Mac-style close buttons + unit number + status badge | Navigation + context |
+| Hero image | Full-width photo with gradient overlay + price overlay | Visual impact |
+| Description | Unit type + floor + prose description | Narrative sell |
+| Key stats grid | Bedrooms / Bathrooms / Area / Floor | Quick spec comparison |
+| Additional info | View / Parking / Type | Secondary specs |
+| Features & Amenities | Cyan pill tags | Selling points |
+| Quick-launch buttons | "3D Viewer" + "Blueprint Studio" | Direct access to visualization tools |
+| Pricing card | Price + price/m² + area + floor + parking | Financial details |
+| Payment Plan | Numbered steps (Booking / Construction / Handover %) | Financing structure |
+| Availability card | Status + last updated date | Current state |
+
+---
+
+### [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732)
+Full-screen modal for immersive unit exploration.
+
+| Mode | Component | Function |
+|---|---|---|
+| **3D Viewer** | [Viewer3D](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#111-154) → Three.js [Canvas](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#505-513) + [GlbModel](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#85-110) + `OrbitControls` | Interactive 3D walkthrough of the unit; mouse to rotate/pan/zoom |
+| **Blueprint Studio** | [BlueprintViewer](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#561-682) | Zoomable/pannable floor plan image; scroll to zoom, drag to pan, +/−/⌂ controls |
+
+[GlbModel](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#85-110) auto-normalizes the GLB scale to fit the viewport regardless of original model dimensions.
+
+---
+
+### [RightMapPane](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#733-751)
+| Element | Function |
+|---|---|
+| Google Maps `iframe` | Shows the geographic location of the development (Dubai Marina) |
+| Location label overlay | "Google Maps - Inventory Region" |
+| Unit price grid (bottom) | Shows first 4 units with prices as a quick reference |
+
+---
+
+### [UnitRow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#753-824) (List View)
+Compact table-style row for the list view toggle. Shows thumbnail + unit number + status badge + type/area tags + view + price in a single horizontal row.
+
+---
+
+## 5 · Settings
+**File:** [src/components/modules/Settings.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx)
+
+System configuration hub. 4 rows × 2 columns of glassmorphism cards.
+
+### Shared Primitives
+
+| Component | Function |
+|---|---|
+| **[GlassCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#36-57)** | `motion.div` with `GLASS` styles + staggered entry animation — base for all setting sections |
+| **[SectionHeader](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#58-71)** | Icon badge + title with bottom border — consistent section labeling |
+| **[SettingsRow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#72-98)** | Label + optional description (left) + control (right) with bottom separator — standard settings list item |
+| **[Toggle](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#99-116)** | Animated spring-based on/off switch; blue when on, grey when off |
+| **[DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183)** | Custom dropdown with `AnimatePresence` animated menu; click-outside-to-close overlay |
+| **[GhostButton](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#184-202)** | Subtle bordered button; `danger` prop for red variant |
+| **[DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220)** | Text input with focus border highlight |
+
+---
+
+### Setting Sections
+
+#### System Status ([SystemStatusCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#221-295))
+| Element | Function |
+|---|---|
+| Backend connection pill | Green/red indicator + "Connected" / "Connection lost" |
+| Version + Last Sync grid | Shows app version and last data sync time |
+| **Sync Now** button | Triggers [updateStatus({ serverStatus: 'syncing' })](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#325-328) |
+| **Restart** button | System restart action |
+
+#### iOS App / Device ([IOSConnectionCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#296-401))
+| Element | Function |
+|---|---|
+| Device status pill | Shows paired iPhone name or "No Device Paired" |
+| Pairing Code display | `VLC-7F3A-9B2D` with copy button |
+| Local IP display | `192.168.1.42:8765` with copy button |
+| **Pair Device** button | 2s simulated pairing animation → "Paired" state |
+| **Unpair** button (danger) | Appears after pairing |
+| Push Notifications toggle | Enable/disable alerts to paired iPhone |
+
+**State:** `paired`, `pairing`, `copied`
+
+#### Profile ([ProfileSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#402-440))
+| Row | Control |
+|---|---|
+| Full Name | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) |
+| Email | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) (type=email) |
+| Phone | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) (type=tel) |
+
+Avatar shows user initials from `useStore().user.name`.
+
+#### Notifications ([NotificationSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#441-465))
+5 toggle rows:
+- New Lead Alerts
+- Sentiment Alerts
+- Viewing Reminders
+- System Updates
+- Daily Email Digest
+
+#### Security ([SecuritySettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#466-504))
+| Row | Control |
+|---|---|
+| Two-Factor Authentication | Toggle |
+| Biometric Login (FaceID) | Toggle |
+| Change Password | Ghost button |
+| API Keys | Ghost button |
+| Session Timeout | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (15min / 30min / 1hr / Never) |
+
+#### Display ([DisplaySettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#505-547))
+| Row | Control |
+|---|---|
+| Reduced Motion | Toggle |
+| Compact Mode | Toggle |
+| Language | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (English / العربية) |
+| Timezone | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (Dubai / Riyadh / London) |
+
+#### Data & Privacy ([DataSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#548-581))
+| Row | Control |
+|---|---|
+| Auto-Backup | Toggle (always on) |
+| Data Retention | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (30d / 90d / 6mo / 1yr) |
+| Export Data | Ghost button |
+| Clear Cache | Ghost button (danger/red) |
+
+#### About ([AboutSection](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#582-612))
+- "V" logo mark with glow
+- Version 2.1.0 · Build 2024.02.18
+- Links: Terms of Service · Privacy Policy · Documentation
+
+---
+
+## Global Architecture
+
+### [App.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/App.tsx) — Shell
+| Element | Function |
+|---|---|
+| Auth gate | `isAuthenticated ? <MainLayout> : <LoginScreen>` |
+| [MainLayout](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/App.tsx#40-141) | `min-h-screen flex` with pure black background; renders `<Sidebar>` + `<motion.main>` |
+| Top Bar | Module title + "Project Velocity · v1.1" subtitle + user avatar dropdown |
+| User dropdown | Avatar button → Settings navigation + Logout |
+| `motion.main` | Animated width transition when sidebar expands/collapses |
+
+### [Sidebar.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/layout/Sidebar.tsx) — Navigation
+| Element | Function |
+|---|---|
+| Brand mark | "V" monogram when collapsed; "Velocity" + "v1.1" when expanded |
+| Nav items | Dashboard / Oracle / Sentinel / Inventory / Settings with icons |
+| Active indicator | Highlighted item for current module |
+| Collapse toggle | Chevron button at bottom; animates width 64px ↔ 220px |
+| Status dot | Green pulsing dot at bottom — system online indicator |
+
+### [useStore.ts](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts) — Global State (Zustand)
+| State slice | Contents |
+|---|---|
+| `user` | `{ id, name, role }` or `null` |
+| `isAuthenticated` | Boolean |
+| `activeModule` | `'dashboard' \| 'oracle' \| 'sentinel' \| 'inventory' \| 'settings'` |
+| `sidebarExpanded` | Boolean |
+| `metrics` | `{ activeVisitors, todayLeads, conversionRate, closedDeals, systemHealth, sentimentScore }` |
+| `velocityData` | Time-series array for Lead Velocity chart |
+| `status` | `{ isConnected, serverStatus, version, lastSync }` |
+| `visitors` | Array of tracked [Visitor](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/types/index.ts#44-53) objects |
+| Actions | [login()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#247-248), [logout()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#248-249), [setActiveModule()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#253-254), [toggleSidebar()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#254-255), [updateStatus()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#325-328) |
--- a/Context/Bibels/velocity_ios_bible.md
+++ b/Context/Bibels/velocity_ios_bible.md
@@ -0,0 +1,214 @@
+# Velocity iOS App - Technical Bible
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-03-07  
+**Application Version:** 1.1.0
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Application Overview](#application-overview)
+3. [Technology Stack](#technology-stack)
+4. [Architecture](#architecture)
+5. [Project Structure](#project-structure)
+6. [Core Modules](#core-modules)
+7. [State Management](#state-management)
+8. [Design System](#design-system)
+9. [Development Guidelines](#development-guidelines)
+10. [API Integration Points](#api-integration-points)
+
+---
+
+## Executive Summary
+
+**Velocity iOS** is the native mobile counterpart of the Velocity premium real estate sales enablement platform. Built natively for Apple devices using SwiftUI, it brings the luxury property showcase and experience center ecosystems directly into the hands of sales teams on the showroom floor. The application features seamless integrations with AI-powered lead management (Oracle), biometric visitor tracking (Sentinel), and real-time inventory management.
+
+**Purpose:** Provide sales teams with portable, native, intelligent insights and immersive property presentations with uncompromising performance and battery efficiency.
+
+**Target Users:** Sales Directors, Real Estate Agents, Property Managers on the floor.
+
+---
+
+## Application Overview
+
+### Key Features
+
+1. **Dashboard** - Real-time metrics (Visitors, Revenue, AI Jobs, Listings), sentiment analysis gauge, system health monitoring, and a quick live AI Chat Widget.
+2. **The Oracle** - AI-powered lead management interface to handle WhatsApp, web, and walk-in leads.
+3. **The Sentinel** - Biometric visitor tracking interface, visualizing Live visitor IDs, emotion, confidence, dwell time, and zones.
+4. **Inventory** - Real-time unit availability tracking, including augmented reality overlays (`ARSunOverlayView`).
+5. **Settings** - App configurations and connectivity testing.
+
+### User Flow
+
+```
+Launch (VelocityApp) -> ContentView (Entry Hub) -> Feature Tabs/Navigation -> Native Views (Dashboard, Oracle, Sentinel, etc.)
+```
+
+---
+
+## Technology Stack
+
+### Core Frameworks
+- **Swift** - Primary programming language.
+- **SwiftUI** - Declarative UI framework for building the entire interface.
+- **Combine / Observation** (`@Observable`) - Reactive programming for robust state management.
+
+### Networking & Data
+- **Alamofire** (via `ComfyClient.swift`) - Elegant HTTP networking for handling requests (e.g. Dream Weaver AI image generation).
+
+### UI & Animations
+- **SwiftUI Animation** - Native transitions (`.easeInOut`, `.spring()`, `.numericText()`).
+- **Glassmorphism natively** - via custom modifiers and blurs (`GlassCard`, `GlassBlurView`).
+
+---
+
+## Architecture
+
+### Application Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                       VelocityApp.swift                     │
+│               (App Entry & WindowGroup Setup)               │
+└─────────────────────────────────┬───────────────────────────┘
+                                  │
+┌─────────────────────────────────┴───────────────────────────┐
+│                        ContentView.swift                    │
+│                 (Main App Structure / Tab View)             │
+└──────┬────────────────────┬──────────────────────┬──────────┘
+       │                    │                      │
+┌──────┴──────┐      ┌──────┴──────┐        ┌──────┴──────┐
+│  Dashboard  │      │   Oracle    │        │  Sentinel   │
+│   Module    │      │   Module    │        │   Module    │
+└─────────────┘      └─────────────┘        └─────────────┘
+```
+
+### State Architecture
+A centralized `AppStore` leverages the `@Observable` macro to power the state of the app across different modules asynchronously.
+
+```text
+┌────────────────────────────────────────────────┐
+│               AppStore.swift (@Observable)     │
+├────────────────────────────────────────────────┤
+│  Metrics (DashboardMetrics)                    │
+│  Visitors (Sentinel array)                     │
+│  Alerts (isAlertActive, alertMessage)          │
+│  Leads & Messages (Oracle data)                │
+└──────────────────────┬─────────────────────────┘
+                       │
+             ┌─────────┴──────────┐
+             │ UI Subscriptions   │
+             │ (Environment/State)│
+             └────────────────────┘
+```
+
+---
+
+## Project Structure
+
+### Directory Layout
+
+```text
+iOS/
+├── App/                     # App Lifecycle
+│   ├── ContentView.swift    # Main App Tab/Navigation Hub
+│   └── VelocityApp.swift    # @main Entry Point
+├── Core/                    # Shared infrastructure
+│   ├── Math/
+│   │   └── SunMath.swift    # Calculation utilities for AR/Environment
+│   ├── Networking/
+│   │   └── ComfyClient.swift# Alamofire client (AI integrations)
+│   ├── State/
+│   │   └── AppStore.swift   # Single source of truth state manager
+│   └── UI/
+│   │   ├── GlassBlurView.swift # Native blur implementations
+│   │   └── VelocityTheme.swift # Design system tokens
+└── Features/                # Feature-specific modules
+    ├── Dashboard/
+    │   └── DashboardView.swift # Analytics, KPIs, Sentiment Gauge
+    ├── Inventory/
+    │   ├── ARSunOverlayView.swift # AR overlay for property sun paths
+    │   └── InventoryView.swift
+    ├── Oracle/
+    │   └── OracleView.swift # Lead progression and AI chat interface
+    ├── Sentinel/
+    │   └── SentinelView.swift # Visitor facial & emotion analysis
+    └── Settings/
+        └── SettingsView.swift # App configuration
+```
+
+---
+
+## Core Modules
+
+### 1. Dashboard (`DashboardView.swift`)
+**Purpose:** Executive overview matching the WebOS counterpart with native fluidity.
+**Components:**
+- **LiveKPICard**: Displays `Visitors`, `Revenue`, `AI Jobs`, and `Listings` with pulse animations.
+- **Sentiment Gauge**: A dynamic, animated thermometer evaluating the overall showroom vibe.
+- **System Health Panel**: Monitors underlying CPU/GPU/Memory configurations.
+- **AI Chat Widget**: Embedded, fast-access AI query terminal with typing indicators and conversational memory.
+
+### 2. Apps & AI Integration (`ComfyClient.swift` & Oracles)
+The iOS app natively implements calls to standard HTTP backends and advanced AI generation services using an `Alamofire` `Session` directly connecting to high-GPU instances for rapid image synthesis (`DreamWeaverRequest`).
+
+---
+
+## State Management
+
+### Zustand to AppStore Mapping
+The iOS app natively replicates the WebOS `Zustand` state mechanism heavily through `AppStore.swift`.
+
+- **Live Ticker:** Contains a background publisher running every 5 seconds that jitter-updates visitors, sentiment, and raises mock backend alerts.
+- **Models:**
+  - `Visitor`: Contains `id`, `faceId`, `sentiment`, `confidence`, `zone`.
+  - `Lead`: Categorizes lead paths (Walk-in, Website, WhatsApp), Qualification (Whale, Potential), Budget.
+  - `ChatMessage` & `DashboardMetrics`: Shared data schemas for AI interactions and KPIs.
+
+---
+
+## Design System
+
+**Location:** `Core/UI/VelocityTheme.swift`
+
+### Color Palette
+Precisely mirrors the web dashboard's high-contrast, premium dark mode:
+- **Backgrounds**: True black `(0, 0, 0)` with elevated surfaces (`#131418`, `#22262e`).
+- **Foregrounds**: Off-white for max readability, subtle grays for muted elements.
+- **Accent**: `VelocityTheme.accent` `(0.231, 0.510, 0.965)` (Blue)
+- **Semantic Status**: Matches SwiftUI `Color` blocks (`success`, `warning`, `danger$).
+
+### Native Glassmorphism
+Using native `VisualEffectView` or styled semi-transparent blocks wrapped in `.modifier(GlassCard())`.
+```swift
+// Implementation
+.background(
+    RoundedRectangle(cornerRadius: 16)
+        .fill(Color(red: 0.031, green: 0.039, blue: 0.071).opacity(0.82))
+        .overlay(RoundedRectangle(cornerRadius: 16).stroke(VelocityTheme.borderAccent, lineWidth: 1))
+        .shadow(color: .black.opacity(0.55), radius: 16, y: 4)
+)
+```
+
+---
+
+## Development Guidelines
+
+**UI Paradigms:**
+- Leverage `ZStack` and `GeometryReader` for scale-dependent UI components like gauges and progress bars.
+- Add subtle animations using `.animation(.easeInOut(duration: 0.4), value: ...)` to make data updates feel organic.
+- Restrict logic calculations out of the `View` body, moving them to extensions, external math engines (`SunMath.swift`), or the `AppStore`.
+
+---
+
+## API Integration Points
+
+**ComfyClient / Dream Weaver:**
+- Core generation client utilizing `.post` to `http://192.168.x.x:8000/dream-weaver`.
+- Automates formatting to Base64 formats for sending payloads to AI models and decoding the respective `output_base64` image back to a `UIImage`.
+
+*(Note: Data sources like leads and visitors are currently heavily maintained via the native `AppStore` state but conform to general structures mapping to `/api/leads` and `/api/visitors` on the production backends).*
+
--- a/Context/Bibels/velocity_technical_bible.md
+++ b/Context/Bibels/velocity_technical_bible.md
@@ -0,0 +1,862 @@
+# Velocity Web App - Technical Bible
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-02-18  
+**Application Version:** 2.1.0
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Application Overview](#application-overview)
+3. [Technology Stack](#technology-stack)
+4. [Architecture](#architecture)
+5. [Project Structure](#project-structure)
+6. [Core Modules](#core-modules)
+7. [State Management](#state-management)
+8. [Design System](#design-system)
+9. [Component Library](#component-library)
+10. [Development Guidelines](#development-guidelines)
+11. [Build & Deployment](#build--deployment)
+12. [API Integration Points](#api-integration-points)
+
+---
+
+## Executive Summary
+
+**Velocity** is a premium real estate sales enablement platform built for luxury property showcases and experience centers. The application integrates AI-powered lead management (Oracle), biometric visitor tracking (Sentinel), real-time inventory management, and comprehensive analytics dashboards to create an end-to-end sales enablement ecosystem.
+
+**Purpose:** Empower sales teams with intelligent insights, automated lead qualification, sentiment analysis, and immersive property presentations.
+
+**Target Users:** Sales Directors, Real Estate Agents, Property Managers
+
+---
+
+## Application Overview
+
+### Key Features
+
+1. **Dashboard** - Real-time metrics, lead velocity charts, sentiment analysis, system health monitoring
+2. **The Oracle** - AI-powered lead management with automated qualification and intelligent chat
+3. **The Sentinel** - Biometric visitor tracking with facial recognition and sentiment analysis
+4. **Inventory** - Unit availability tracking with advanced filters and status management
+5. **Settings** - System configuration and user preferences
+
+### User Flow
+
+```
+Login Screen (FaceID Auth) → Dashboard → Module Navigation (Sidebar) → Feature Interactions
+```
+
+---
+
+## Technology Stack
+
+### Frontend Framework
+- **React** `19.2.0` - UI library with latest concurrent features
+- **TypeScript** `5.9.3` - Static typing and enhanced DX
+- **Vite** `7.2.4` - Fast build tool with HMR
+
+### State Management
+- **Zustand** `5.0.11` - Lightweight state management with persistence
+- **Zustand Persist Middleware** - LocalStorage persistence for auth/navigation state
+
+### UI Framework
+- **Tailwind CSS** `3.4.19` - Utility-first styling
+- **shadcn/ui** - 40+ pre-built, accessible components
+- **Radix UI** - Headless component primitives for accessibility
+- **Framer Motion** `12.34.1` - Advanced animations and transitions
+
+### Data Visualization
+- **Recharts** `2.15.4` - Composable charting library
+
+### Form Management
+- **React Hook Form** `7.70.0` - Performant form handling
+- **Zod** `4.3.5` - Schema validation
+
+### Icons & Assets
+- **Lucide React** `0.562.0` - Modern icon library
+
+### Utilities
+- **date-fns** `4.1.0` - Date manipulation
+- **clsx** / **tailwind-merge** - Conditional className handling
+- **class-variance-authority** - Component variant management
+
+---
+
+## Architecture
+
+### Application Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    App.tsx (Root)                       │
+│              ┌──────────────────────────┐               │
+│              │  Authentication Guard    │               │
+│              └──────────┬───────────────┘               │
+│                         │                                │
+│         ┌───────────────┴────────────────┐              │
+│         │                                 │              │
+│   LoginScreen                        MainLayout         │
+│                                           │              │
+│                          ┌────────────────┼────────────┐│
+│                          │                │            ││
+│                      Sidebar         Module Router     ││
+│                                           │            ││
+│                          ┌────────────────┴──────┐    ││
+│                          │                        │    ││
+│                     Dashboard        Oracle/Sentinel/ ││
+│                                      Inventory/etc     ││
+└─────────────────────────────────────────────────────────┘
+```
+
+### State Architecture
+
+```
+┌────────────────────────────────────────────────┐
+│         Zustand Store (useStore.ts)            │
+├────────────────────────────────────────────────┤
+│  AuthState       │ Navigation   │ Oracle       │
+│  SentinelState   │ Dashboard    │ Inventory    │
+│  SystemState     │              │              │
+└────────────────────────────────────────────────┘
+        │
+        ├── LocalStorage Persistence (auth, activeModule)
+        └── Component Subscriptions (selective)
+```
+
+### Component Hierarchy
+
+```
+src/
+├── components/
+│   ├── layout/          # Layout components
+│   │   ├── LoginScreen  # Authentication UI
+│   │   └── Sidebar      # Navigation sidebar
+│   ├── modules/         # Feature modules
+│   │   ├── Dashboard    # Analytics dashboard
+│   │   ├── Oracle       # Lead management
+│   │   ├── Sentinel     # Visitor tracking
+│   │   ├── Inventory    # Unit management
+│   │   └── Settings     # Configuration
+│   └── ui/              # shadcn/ui components (40+)
+├── store/               # Zustand state
+├── types/               # TypeScript definitions
+├── lib/                 # Utilities
+└── hooks/               # Custom React hooks
+```
+
+---
+
+## Project Structure
+
+### Directory Layout
+
+```
+app/
+├── dist/                    # Production build output
+├── src/
+│   ├── components/
+│   │   ├── layout/
+│   │   │   ├── LoginScreen.tsx (8KB)  # FaceID auth screen
+│   │   │   └── Sidebar.tsx (5KB)      # App navigation
+│   │   ├── modules/
+│   │   │   ├── Dashboard.tsx (15KB)   # Analytics dashboard
+│   │   │   ├── Oracle.tsx (18KB)      # AI chat + lead mgmt
+│   │   │   ├── Sentinel.tsx (19KB)    # Biometric tracking
+│   │   │   ├── Inventory.tsx (18KB)   # Unit management
+│   │   │   └── Settings.tsx (16KB)    # App config
+│   │   └── ui/                        # 40+ shadcn components
+│   ├── hooks/
+│   │   └── use-mobile.ts              # Responsive breakpoint hook
+│   ├── lib/
+│   │   └── utils.ts                   # cn() helper
+│   ├── store/
+│   │   └── useStore.ts (10KB)         # Zustand state
+│   ├── types/
+│   │   └── index.ts (2KB)             # Type definitions
+│   ├── App.tsx (4KB)                  # Root component
+│   ├── App.css                        # Component styles
+│   ├── index.css (5KB)                # Global styles + utilities
+│   └── main.tsx                       # Entry point
+├── index.html                         # HTML template
+├── package.json                       # Dependencies
+├── tailwind.config.js (5KB)          # Theme config
+├── tsconfig.json                      # TS config
+├── vite.config.ts                     # Vite config
+└── components.json                    # shadcn config
+```
+
+### Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `vite.config.ts` | Build tool configuration, React plugin setup |
+| `tailwind.config.js` | Theme customization, custom animations, velocity colors |
+| `tsconfig.json` | TypeScript compiler options |
+| `tsconfig.app.json` | App-specific TS config |
+| `tsconfig.node.json` | Node environment TS config |
+| `components.json` | shadcn/ui component installation config |
+| `postcss.config.js` | PostCSS plugins (Tailwind) |
+| `eslint.config.js` | Linting rules |
+
+---
+
+## Core Modules
+
+### 1. Dashboard
+
+**Purpose:** Real-time analytics and system monitoring
+
+**Components:**
+- **ActiveVisitorsWidget** - Live visitor count with pulse animation
+- **TodayLeadsWidget** - Daily lead generation metrics
+- **ConversionRateWidget** - Lead-to-sale conversion tracking
+- **SentimentGauge** - Showroom sentiment thermometer (0-100%)
+- **LeadVelocityChart** - Time-series lead generation graph
+- **SystemHealth** - CPU/GPU/Memory/Temperature gauges
+- **RecentActivity** - Activity feed with emoji icons
+
+**Data Sources:**
+- `useStore().metrics` - Dashboard metrics
+- `useStore().velocityData` - Chart data
+
+**Key Features:**
+- Bento grid layout (4-column responsive grid)
+- Framer Motion staggered animations
+- Recharts area charts with gradients
+- Real-time pulse indicators
+
+---
+
+### 2. Oracle (AI Lead Management)
+
+**Purpose:** Intelligent lead qualification and automated conversations
+
+**Components:**
+- Lead sidebar with qualification badges (Whale/Potential/Tire Kicker)
+- AI chat interface with thinking states
+- Lead status pipeline (New → Engaged → Qualified → Hot → Closed)
+- Unread message indicators
+- Source badges (WhatsApp/Website/Walk-in)
+
+**Data Sources:**
+- `useStore().leads` - Lead database
+- `useStore().messages` - Chat history per lead
+- `useStore().activeLeadId` - Current conversation
+
+**Key Features:**
+- AI message generation with simulated thinking state
+- Lead auto-qualification scoring
+- Budget and interest tracking
+- Last active timestamps
+- Glassmorphic chat bubbles
+
+---
+
+### 3. Sentinel (Biometric Tracking)
+
+**Purpose:** Facial recognition and sentiment analysis
+
+**Components:**
+- Live visitor grid with face IDs
+- Sentiment visualization (Excited/Interested/Neutral/Confused/Disinterested)
+- Zone-based tracking
+- Dwell time monitoring
+- Confidence scores
+- Alert system for negative sentiment
+
+**Data Sources:**
+- `useStore().visitors` - Active visitor tracking
+- `useStore().isAlertActive` - Alert state
+- `useStore().alertMessage` - Alert content
+
+**Key Features:**
+- Real-time FaceID cards with sentiment pills
+- Zone heatmaps (future enhancement)
+- Automated alert triggers (<50% sentiment)
+- Visitor remove capability
+- Confidence percentage indicators
+
+---
+
+### 4. Inventory
+
+**Purpose:** Real-time unit availability tracking
+
+**Components:**
+- Unit cards with status badges
+- Floor plan visualization (future)
+- Filter bar (All/Available/Reserved/Sold/Hold)
+- Unit details (area, price, view, floor)
+- Status management dropdown
+
+**Data Sources:**
+- `useStore().units` - Unit database
+- `useStore().filterStatus` - Active filter
+- `useStore().selectedUnitId` - Selected unit
+
+**Unit Types:**
+- Studio
+- 1BR, 2BR, 3BR
+- Penthouse
+
+**Status States:**
+```typescript
+'available' | 'reserved' | 'sold' | 'hold'
+```
+
+---
+
+### 5. Settings
+
+**Purpose:** System configuration and user preferences
+
+**Sections:**
+- Theme settings
+- Notification preferences
+- System diagnostics
+- User profile management
+- Data sync options
+
+---
+
+## State Management
+
+### Zustand Store Architecture
+
+**Location:** `src/store/useStore.ts`
+
+### Store Slices
+
+#### AuthState
+```typescript
+{
+  isAuthenticated: boolean
+  user: User | null
+  login: (user: User) => void
+  logout: () => void
+}
+```
+
+#### NavigationState
+```typescript
+{
+  activeModule: ModuleId
+  sidebarExpanded: boolean
+  setActiveModule: (module: ModuleId) => void
+  toggleSidebar: () => void
+  setSidebarExpanded: (expanded: boolean) => void
+}
+```
+
+#### OracleState
+```typescript
+{
+  leads: Lead[]
+  activeLeadId: string | null
+  messages: Record<string, ChatMessage[]>
+  isOracleThinking: boolean
+  setActiveLead: (leadId: string | null) => void
+  addMessage: (leadId: string, message: ChatMessage) => void
+  setOracleThinking: (thinking: boolean) => void
+  markLeadAsRead: (leadId: string) => void
+}
+```
+
+#### SentinelState
+```typescript
+{
+  visitors: Visitor[]
+  isAlertActive: boolean
+  alertMessage: string
+  addVisitor: (visitor: Visitor) => void
+  removeVisitor: (visitorId: string) => void
+  triggerAlert: (message: string) => void
+  clearAlert: () => void
+}
+```
+
+#### DashboardState
+```typescript
+{
+  metrics: DashboardMetrics
+  velocityData: LeadVelocityData[]
+  updateMetrics: (metrics: Partial<DashboardMetrics>) => void
+  addVelocityDataPoint: (data: LeadVelocityData) => void
+}
+```
+
+#### InventoryState
+```typescript
+{
+  units: Unit[]
+  selectedUnitId: string | null
+  filterStatus: Unit['status'] | 'all'
+  setSelectedUnit: (unitId: string | null) => void
+  setFilterStatus: (status: Unit['status'] | 'all') => void
+}
+```
+
+#### SystemState
+```typescript
+{
+  status: SystemStatus
+  updateStatus: (status: Partial<SystemStatus>) => void
+}
+```
+
+### Persistence
+
+**Storage Key:** `velocity-webos-storage`
+
+**Persisted State:**
+- `isAuthenticated`
+- `user`
+- `activeModule`
+
+All other state is session-based.
+
+---
+
+## Design System
+
+### Color Palette
+
+#### Velocity Brand Colors
+```javascript
+velocity: {
+  black: '#0a0a0a',    // Primary background
+  dark: '#111111',     // Secondary background
+  panel: '#151515',    // Panel background
+  blue: '#3b82f6',     // Primary action
+  cyan: '#06b6d4',     // Secondary action
+  amber: '#f59e0b',    // Warning/attention
+  green: '#22c55e',    // Success/positive
+  red: '#ef4444',      // Error/negative
+}
+```
+
+#### Semantic Colors (HSL)
+- **Background:** `0 0% 4%` (near-black)
+- **Foreground:** `0 0% 98%` (near-white)
+- **Primary:** `210 100% 56%` (blue)
+- **Border:** `0 0% 18%` (subtle gray)
+- **Muted:** `0 0% 15%` (disabled states)
+
+### Typography
+
+**Font Stack:**
+```css
+-apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Inter', 'Segoe UI', sans-serif
+```
+
+**Letter Spacing:** `-0.01em` (tight, premium feel)
+
+**Font Sizes:**
+- Display: `text-4xl` (36px)
+- Heading: `text-xl` (20px)
+- Body: `text-sm` (14px)
+- Caption: `text-xs` (12px)
+
+### Spacing
+
+**Border Radius:**
+- `xs`: `calc(var(--radius) - 6px)`
+- `sm`: `calc(var(--radius) - 4px)`
+- `md`: `calc(var(--radius) - 2px)`
+- `lg`: `var(--radius)` (0.75rem / 12px)
+- `xl`: `calc(var(--radius) + 4px)`
+- `2xl`: `1rem` (16px)
+- `3xl`: `1.5rem` (24px)
+
+**Default Radius:** `0.75rem` (12px)
+
+### Glassmorphism
+
+#### Utility Classes
+```css
+.glass                /* Subtle glass effect */
+.glass-strong         /* Bold glass effect */
+.glass-panel          /* Panel with blur */
+.glass-card           /* Card with gradient + blur */
+```
+
+#### Implementation
+```css
+.glass-panel {
+  background: rgba(255, 255, 255, 0.03);
+  backdrop-filter: blur(24px);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 1rem;
+}
+```
+
+### Shadows
+
+**Glass Shadow:** `0 8px 32px rgba(0, 0, 0, 0.4)`
+
+**Glow Effects:**
+- Blue: `0 0 40px rgba(59, 130, 246, 0.3)`
+- Amber: `0 0 40px rgba(245, 158, 11, 0.3)`
+- Green: `0 0 20px rgba(34, 197, 94, 0.4)`
+
+### Animations
+
+#### Keyframes
+- `accordion-down/up` - Radix accordion
+- `shimmer` - Loading shimmer effect
+- `pulse-glow` - Pulsing glow animation
+- `slide-in/up` - Entry animations
+- `fade-in` - Opacity fade
+- `scale-in` - Scale + fade
+- `float` - Floating hover effect
+- `scan` - Scanning line effect
+- `faceid-pulse` - FaceID ring pulse
+
+#### Timing Functions
+- **Apple:** `cubic-bezier(0.4, 0.0, 0.2, 1)` - Standard easing
+- **Bounce:** `cubic-bezier(0.34, 1.56, 0.64, 1)` - Spring bounce
+
+### Status Indicators
+
+**Sentiment Pills:**
+```css
+.sentiment-excited    /* Green */
+.sentiment-confused   /* Amber */
+.sentiment-neutral    /* Gray */
+```
+
+**Status Pulse:**
+```css
+.status-pulse         /* Animated pulse dot */
+```
+
+---
+
+## Component Library
+
+### shadcn/ui Components (40+)
+
+**Navigation:**
+- Sidebar, Navigation Menu, Menubar, Breadcrumb, Pagination
+
+**Layout:**
+- Card, Separator, Scroll Area, Resizable, Aspect Ratio, Sheet
+
+**Forms:**
+- Input, Textarea, Select, Checkbox, Radio Group, Switch, Slider, Calendar, Date Picker, Input OTP
+
+**Feedback:**
+- Alert, Alert Dialog, Dialog, Drawer, Toast (Sonner), Tooltip, Hover Card, Popover, Progress, Skeleton, Spinner
+
+**Data Display:**
+- Table, Badge, Avatar, Chart, Carousel, Accordion, Collapsible, Tabs, Toggle Group
+
+**Actions:**
+- Button, Button Group, Dropdown Menu, Context Menu, Command (⌘K)
+
+**Utilities:**
+- Form (React Hook Form), Field, Label, Empty, Item, KBD
+
+---
+
+## Development Guidelines
+
+### Code Style
+
+**Component Structure:**
+```typescript
+// 1. Imports
+import { motion } from 'framer-motion';
+import { Icon } from 'lucide-react';
+import { useStore } from '@/store/useStore';
+
+// 2. Types/Interfaces
+interface WidgetProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+// 3. Component
+export function Widget({ children, className }: WidgetProps) {
+  const store = useStore();
+  
+  return (
+    <motion.div className={cn('glass-card', className)}>
+      {children}
+    </motion.div>
+  );
+}
+```
+
+**Naming Conventions:**
+- Components: `PascalCase` (e.g., `Dashboard.tsx`)
+- Hooks: `camelCase` with `use` prefix (e.g., `useMobile.ts`)
+- Types: `PascalCase` (e.g., `ModuleId`)
+- Utilities: `camelCase` (e.g., `cn()`)
+
+**Path Aliases:**
+- `@/*` → `src/*`
+
+### Animation Guidelines
+
+**Entry Animations:**
+```typescript
+initial={{ opacity: 0, y: 20 }}
+animate={{ opacity: 1, y: 0 }}
+transition={{ duration: 0.3, ease: [0.4, 0, 0.2, 1] }}
+```
+
+**Stagger Delays:** Increment by `0.1s` for sequential animations
+
+**Spring Animations:**
+```typescript
+transition={{ 
+  type: 'spring', 
+  stiffness: 300, 
+  damping: 30,
+  mass: 0.8 
+}}
+```
+
+### State Management Patterns
+
+**Selective Subscriptions:**
+```typescript
+const activeModule = useStore((state) => state.activeModule);
+```
+
+**Batch Updates:**
+```typescript
+set((state) => ({
+  ...state,
+  multiple: updates,
+}));
+```
+
+---
+
+## Build & Deployment
+
+### Scripts
+
+```bash
+npm run dev      # Start dev server (localhost:5173)
+npm run build    # TypeScript check + Vite build
+npm run lint     # ESLint check
+npm run preview  # Preview production build
+```
+
+### Build Output
+
+**Directory:** `dist/`
+
+**Assets:**
+- `index.html` - Entry point
+- `assets/index-[hash].js` - Bundled JavaScript
+- `assets/index-[hash].css` - Bundled CSS
+
+### Environment Variables
+
+Create `.env` file:
+```env
+VITE_API_URL=https://api.velocity.com
+VITE_FACEID_KEY=your_key_here
+VITE_ORACLE_AI_KEY=your_key_here
+```
+
+Access in code:
+```typescript
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+---
+
+## API Integration Points
+
+### Expected Backend Endpoints
+
+**Authentication:**
+```
+POST /api/auth/faceid
+POST /api/auth/logout
+GET  /api/auth/me
+```
+
+**Leads (Oracle):**
+```
+GET    /api/leads
+GET    /api/leads/:id
+POST   /api/leads
+PATCH  /api/leads/:id
+DELETE /api/leads/:id
+GET    /api/leads/:id/messages
+POST   /api/leads/:id/messages
+```
+
+**Visitors (Sentinel):**
+```
+GET    /api/visitors
+POST   /api/visitors          # Add new visitor
+DELETE /api/visitors/:id      # Remove visitor
+GET    /api/visitors/zones    # Zone analytics
+POST   /api/alerts            # Trigger alert
+```
+
+**Inventory:**
+```
+GET    /api/units
+GET    /api/units/:id
+PATCH  /api/units/:id/status
+GET    /api/units/availability
+```
+
+**Dashboard:**
+```
+GET /api/metrics              # Real-time metrics
+GET /api/velocity             # Lead velocity data
+GET /api/system-health        # System status
+GET /api/activity             # Recent activity feed
+```
+
+### WebSocket Events
+
+**Real-time Updates:**
+```
+ws://api.velocity.com/ws
+
+Events:
+- visitor:new
+- visitor:update
+- visitor:removed
+- lead:new
+- lead:updated
+- metrics:update
+- alert:triggered
+```
+
+---
+
+## Performance Optimization
+
+### Code Splitting
+
+Vite automatically code-splits by route. Each module is lazy-loaded:
+
+```typescript
+const Dashboard = lazy(() => import('./components/modules/Dashboard'));
+```
+
+### Image Optimization
+
+- Use WebP format
+- Lazy load images with `loading="lazy"`
+- Serve responsive images via `<picture>` tag
+
+### Bundle Size
+
+**Current Build:**
+- JavaScript: ~300KB (gzipped)
+- CSS: ~50KB (gzipped)
+
+**Optimization Strategies:**
+- Tree-shaking unused components
+- Dynamic imports for heavy modules
+- Remove unused Tailwind classes (purge)
+
+---
+
+## Security Considerations
+
+### Authentication
+
+- FaceID biometric authentication
+- JWT token storage in LocalStorage (consider httpOnly cookies for production)
+- Automatic logout on token expiration
+
+### Data Privacy
+
+- Visitor face data handled according to GDPR
+- No PII stored in browser localStorage
+- Encrypted WebSocket connections (WSS)
+
+### Input Validation
+
+- Zod schema validation on all forms
+- Server-side validation required
+- XSS protection via React's built-in escaping
+
+---
+
+## Testing Strategy
+
+### Unit Tests (Recommended)
+
+**Framework:** Vitest + React Testing Library
+
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom
+```
+
+**Test Coverage Targets:**
+- Zustand store actions: 100%
+- Component rendering: 80%
+- User interactions: 70%
+
+### E2E Tests (Recommended)
+
+**Framework:** Playwright
+
+```bash
+npm install -D @playwright/test
+```
+
+**Critical Flows:**
+- Login → Dashboard → Lead Interaction
+- Visitor Alert Trigger → Response
+- Unit Status Update
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** Build fails with TypeScript errors  
+**Fix:** Run `npm run build` to see full errors, check `tsconfig.json`
+
+**Issue:** Tailwind classes not applying  
+**Fix:** Check `tailwind.config.js` content paths, restart dev server
+
+**Issue:** Zustand state not persisting  
+**Fix:** Clear localStorage `velocity-webos-storage`, check persistence config
+
+**Issue:** Framer Motion animations janky  
+**Fix:** Reduce `stiffness`, increase `damping`, check for layout shifts
+
+---
+
+## Roadmap
+
+### Planned Features
+
+- **Voice Commands:** Alexa/Google Assistant integration
+- **AR Property Tours:** WebXR integration
+- **Multi-language Support:** i18n with Arabic/English
+- **Dark/Light Mode:** Theme switcher
+- **Mobile App:** React Native version
+- **Analytics Export:** PDF/Excel reports
+
+---
+
+## Contributors
+
+**Development Team:** Desineuron - Project Velocity  
+**Design System:** Custom Velocity UI  
+**Built With:** ❤️ and ☕
+
+---
+
+**End of Technical Bible**