Missed files

2026-04-12 19:25:43 +05:30
parent 4645ff737b
commit d77373900a
69 changed files with 4375 additions and 2469 deletions
--- a/Context/Bibels/Project
+++ b/Context/Bibels/Project
@@ -0,0 +1,875 @@
+# Project Velocity Master Bibel
+
+**Status:** Master source of truth  
+**Prepared:** 2026-04-12  
+**Scope:** Unified synthesis of Project Velocity markdown documentation across product, architecture, infrastructure, operations, iOS, web, AI workflows, and GTM context  
+**Exclusions:** Anything under `Sourik` was intentionally excluded from this synthesis  
+**Method:** This document normalizes and reconciles the current documentation corpus. It is not a raw concatenation. Where source docs disagree, this bibel favors the latest operational truth and the more concrete implementation artifact.
+
+---
+
+## Chapter Index
+
+1. Charter and Scope
+2. Source Corpus
+3. Product Thesis
+4. Commercial Model
+5. Customer and User Model
+6. Suite Architecture
+7. Core Product Surfaces
+8. Oracle
+9. Sentinel
+10. Dream Weaver and Catalyst
+11. Web Application
+12. iOS Application
+13. Backend and AI Runtime
+14. Data Model and Core Entities
+15. Infrastructure and Deployment Model
+16. Stable Ingress Layer
+17. Linux AWS Control Surface
+18. Operating Flows
+19. Security, Privacy, and Sovereignty
+20. Current Live Truth
+21. Build Priorities and Open Gaps
+22. Runbooks and Team Usage
+23. Source Lineage Map
+
+---
+
+## 1. Charter and Scope
+
+Project Velocity is not one app. It is a private, on-prem or client-controlled real-estate operating system composed of:
+
+- a premium web interface
+- a native iPad surface
+- an AI CRM and analytics layer
+- a biometric perception and scoring layer
+- a visual generation layer
+- a durable infrastructure and operator layer
+
+Velocity is designed around an anti-SaaS principle:
+
+- client data stays with the client
+- deployments can run on-prem or in client-controlled cloud
+- the product is sold as strategic capability, not seat-based software
+
+This master bibel exists to collapse scattered markdown artifacts into one normalized document the team can use as the primary reference.
+
+---
+
+## 2. Source Corpus
+
+This bibel synthesizes the key Project Velocity markdown sources, including:
+
+- core bibles:
+  - `velocity_technical_bible.md`
+  - `velocity_ios_bible.md`
+  - `Project Velocity - The Oracle.md`
+  - `The Sentinel Bibel.md`
+  - `Desineuron Ops Control Plane Bibel.md`
+- infrastructure:
+  - `TEAM_HANDOFF_2026-04-08.md`
+  - ingress and ops control plane READMEs
+- Comfy and Dream Weaver:
+  - `DREAMWEAVER_TECHNICAL_SPEC.md`
+  - `A100_DEPLOYMENT_VALIDATION.md`
+  - `comfy_engine/scripts/README.md`
+- operational truth docs:
+  - `nemoclaw_setup_truth.md`
+  - `velocity_status_report.md`
+  - `oracle_development_status.md`
+- strategic and customer docs:
+  - Kolkata builder intel
+  - Customer 0 strategy
+  - customer persona notes
+  - sprint and user story docs
+
+Excluded from synthesis:
+
+- any path containing `Sourik`
+- vendor or dependency markdown such as `node_modules`
+- non-authoritative third-party readmes unless they directly influenced repo behavior
+
+---
+
+## 3. Product Thesis
+
+Velocity is a real-estate sales acceleration platform for high-value property selling environments.
+
+Its core promise is:
+
+- compress sales cycles
+- increase intelligence during sales interactions
+- reduce lead leakage
+- preserve data sovereignty
+- give each property or portfolio a private, premium operating stack
+
+The product is built around a first-principles model:
+
+- property-specific intelligence matters
+- portfolio intelligence unlocks when multiple properties are active
+- AI should operate the workflow surface, not just answer questions
+- product delivery must be standardized enough to avoid bespoke installation chaos
+
+Velocity is therefore best understood as a modular operating system, not a single dashboard.
+
+---
+
+## 4. Commercial Model
+
+The business model reflected in the documentation is:
+
+- initial setup fee
+- monthly maintenance / bleeding-edge upgrade fee
+- inventory-linked or performance-linked downstream value capture
+
+The product is not sold primarily by seats. The most important commercial unit is the property, with portfolio behavior unlocking when multiple properties are onboarded.
+
+Working internal segmentation:
+
+- **Tier 3 / city-channel model**
+  - CP or channel-heavy deployment
+  - one city per install
+  - can cover many builders in that city
+  - user count can still be high
+- **Tier 2 / project-builder model**
+  - per-project deployment for a builder
+  - narrower operational scope
+  - property-specific generation and sales workflows
+- **Tier 1 / enterprise portfolio model**
+  - multi-property or multi-portfolio controls
+  - monitoring and interaction layers across properties
+  - governance and deeper integrations
+
+Commercially, the strongest internal framing is:
+
+- first property gets full setup
+- second property unlocks portfolio features
+- enterprise control grows with property count and operational complexity
+
+---
+
+## 5. Customer and User Model
+
+### Customer Types
+
+- developers / builders
+- brokerages and CPs
+- city-channel sales operators
+- enterprise portfolio operators
+
+### Internal User Types
+
+- junior broker
+- senior broker
+- sales director
+- marketing operator
+- data steward
+- compliance reviewer
+- platform admin
+- operator / infra admin
+
+### Team Reality
+
+The current docs imply two simultaneous realities:
+
+- product reality for future customers
+- internal Desineuron operating reality used to build, demo, and run the system
+
+This bibel captures both, but prefers the operational truth when implementation details matter.
+
+---
+
+## 6. Suite Architecture
+
+```mermaid
+flowchart TD
+    A[Velocity User Surface] --> B[Web App]
+    A --> C[iPad App]
+    B --> D[FastAPI Neural Core]
+    C --> D
+    D --> E[Oracle]
+    D --> F[Sentinel]
+    D --> G[Inventory]
+    D --> H[Dream Weaver / Catalyst]
+    E --> I[PostgreSQL]
+    F --> I
+    G --> I
+    D --> J[NemoClaw / Reasoning Layer]
+    H --> K[ComfyUI / GPU Workloads]
+    L[Linux Control Surface] --> M[AWS GPU Nodes]
+    L --> N[S3 Canonical Asset Store]
+    O[t4g Stable Ingress] --> B
+    O --> C
+    O --> L
+    O --> M
+```
+
+Velocity has four major planes:
+
+- **experience plane**
+  - web app
+  - iPad app
+- **intelligence plane**
+  - Oracle
+  - Sentinel
+  - NemoClaw
+  - Dream Weaver / Catalyst
+- **data plane**
+  - PostgreSQL
+  - asset storage
+  - S3 model store
+- **operations plane**
+  - Linux control surface
+  - stable ingress
+  - AWS GPU workers
+
+---
+
+## 7. Core Product Surfaces
+
+The currently documented product surfaces are:
+
+- **Dashboard**
+  - KPIs, health, activity, sentiment, velocity
+- **Oracle**
+  - AI CRM and analytical canvas
+- **Sentinel**
+  - biometric and attention-scoring engine
+- **Inventory**
+  - unit and property availability tracking
+- **Dream Weaver / Catalyst**
+  - visual generation and asset transformation
+- **Settings / operator surfaces**
+  - system configuration, connectivity, route control, infra control
+
+---
+
+## 8. Oracle
+
+Oracle is the AI operating surface of Velocity. It is not a simple chatbot.
+
+### What Oracle Is
+
+- a prompt-driven CRM intelligence surface
+- a persistent vertical canvas
+- a branchable and mergeable analytical workspace
+- a controlled data access gateway mediated by Nemoclaw and policy
+
+### Core Oracle Principles
+
+- natural-language intent becomes typed execution
+- durable page revisions replace ephemeral AI replies
+- collaboration uses forks and merge requests
+- provenance and auditability are mandatory
+- AI planning must remain policy-constrained
+
+### Oracle Architecture
+
+```mermaid
+flowchart LR
+    A[User Prompt] --> B[Prompt Execution]
+    B --> C[NemoClaw Planning]
+    C --> D[Policy Validation]
+    D --> E[Data Access Gateway]
+    E --> F[PostgreSQL / Tenant Data]
+    F --> G[Visualization Resolver]
+    G --> H[Canvas Component]
+    H --> I[Revisioned Oracle Canvas]
+    I --> J[Fork / Merge Workflow]
+```
+
+### Core Oracle Behaviors
+
+- prompt authoring with context
+- retrieval planning through semantic mapping
+- policy-validated data access
+- component synthesis or template selection
+- append/insert/replace on a vertically scrolling canvas
+- fork and merge semantics for shared work
+
+### Oracle Truth in Repo
+
+The repo has:
+
+- a styled Oracle shell
+- temporary mock-oriented UI behavior
+- placeholder backend Oracle route files
+
+The repo does not yet have:
+
+- the full production Oracle runtime mounted and wired end to end
+
+So Oracle is conceptually mature, but partially implemented.
+
+---
+
+## 9. Sentinel
+
+Sentinel is the biometric, session-intelligence, and attention-scoring engine.
+
+### Core Principles
+
+- local-first perception
+- no raw webcam stream to remote backend
+- PostgreSQL as source of truth
+- real-time broker-facing intelligence
+- infrastructure truth over nostalgic planning
+
+### Sentinel Inputs
+
+- browser-side facial blendshape data
+- scene timing
+- CRM context
+- asset opens
+- CCTV enrichment
+- auto-mode session evidence
+
+### Sentinel Outputs
+
+- QD score
+- lead tags
+- live notifications
+- session intelligence
+- vault-open intelligence
+- auto-mode lead linkage
+
+### Sentinel Modes
+
+- **Assigned Mode**
+  - tied to existing lead
+- **Auto Mode**
+  - no pre-bound lead
+  - CCTV and session evidence reconcile later
+
+### Sentinel Flow
+
+```mermaid
+flowchart TD
+    A[Browser Webcam + MediaPipe] --> B[Biometric Packets]
+    B --> C[/api/sentinel/ws/perception]
+    C --> D[Scene Lookup]
+    D --> E[NemoClaw Scoring]
+    E --> F[perception_sessions]
+    E --> G[omnichannel_logs]
+    E --> H[Live QD Broadcast]
+    I[CCTV OCR/Event] --> J[/api/cctv/event]
+    J --> K[Auto Mode Matcher]
+    K --> L[Lead Link or Lead Create]
+```
+
+### Active Truth
+
+The docs are explicit that:
+
+- NVIDIA-hosted completions are the active primary path
+- Ollama/OpenShell exist but are not the production-first scoring path
+
+That distinction should remain explicit in team communication.
+
+---
+
+## 10. Dream Weaver and Catalyst
+
+Dream Weaver is the structural-preservation visual restyling system. Catalyst is the broader generation and asset automation layer.
+
+### Dream Weaver Objective
+
+Restyle interiors while preserving:
+
+- geometry
+- window placement
+- vanishing points
+- architectural truth
+
+### Technical Strategy
+
+- RealVisXL V5.0 Lightning as core model family in the historical design docs
+- stacked ControlNet approach
+- depth + line preservation
+- SAM-based masking
+- workflow portability through ComfyUI API JSON
+
+### Operational Direction
+
+The later infra work also shows Qwen-based image edit/generation workflows entering the stack. So the project now contains two overlapping visual-generation realities:
+
+- Dream Weaver spec centered on SDXL / RealVisXL / ControlNet / SAM
+- operational AWS generation work centered on Qwen image models and ComfyUI / GPU orchestration
+
+These should be treated as parallel capabilities, not contradictions.
+
+### Dream Weaver Pipeline
+
+```mermaid
+flowchart LR
+    A[Reference / Room Image] --> B[Preprocess]
+    B --> C[M-LSD]
+    B --> D[Depth]
+    B --> E[SAM / Masking]
+    C --> F[Control Stack]
+    D --> F
+    E --> F
+    F --> G[Sampler / Restyler]
+    G --> H[Styled Output]
+    H --> I[API / iPad / Batch Workflow]
+```
+
+### Operational Purpose
+
+- interior restyling
+- marketing posters
+- cinematic video
+- mobile-triggered asset generation
+- broker-facing wow factor
+
+---
+
+## 11. Web Application
+
+The web app is a React + TypeScript + Vite application.
+
+### Frontend Stack
+
+- React 19
+- TypeScript
+- Vite
+- Zustand
+- Tailwind CSS
+- shadcn/ui
+- Radix UI
+- Framer Motion
+- Recharts
+- React Hook Form
+- Zod
+
+### Core Web Modules
+
+- Dashboard
+- Oracle
+- Sentinel
+- Inventory
+- Settings
+
+### State Model
+
+The docs describe Zustand-backed state slices for:
+
+- auth
+- navigation
+- Oracle
+- Sentinel
+- Dashboard
+- Inventory
+- system state
+
+### Current Truth
+
+The web app appears stronger as a polished shell than as a fully integrated production data surface. It carries much of the premium experience language and component structure the rest of the system is meant to converge toward.
+
+---
+
+## 12. iOS Application
+
+Velocity iOS is the native mobile counterpart for Apple devices, especially the showroom iPad surface.
+
+### iOS Stack
+
+- Swift
+- SwiftUI
+- Combine / Observation
+- Alamofire for networking
+- native animation and glassmorphism
+
+### iOS Modules
+
+- Dashboard
+- Oracle
+- Sentinel
+- Inventory
+- Settings
+
+### Strategic Role
+
+The iPad app is not just a companion. It is central to the product’s premium physical-sales-gallery positioning.
+
+Important documented capabilities:
+
+- portable sales intelligence
+- native presentation surface
+- AI generation triggering
+- AR sun-path overlay
+- inventory and lead interaction on the floor
+
+### Design Direction
+
+- native fluidity
+- battery efficiency
+- premium dark/glass aesthetic
+- parity with web where needed, but not web-in-a-wrapper
+
+---
+
+## 13. Backend and AI Runtime
+
+The backend is a FastAPI neural core with PostgreSQL, auth, websockets, and AI orchestration.
+
+### Key Responsibilities
+
+- API routing
+- auth and RBAC
+- CRM and lead operations
+- Sentinel perception processing
+- Oracle execution path
+- websockets and notifications
+- video and scene catalog access
+- NemoClaw integration
+
+### NemoClaw Role
+
+NemoClaw is the reasoning layer used across:
+
+- lead tagging
+- CCTV profiling
+- QD scoring
+- future Oracle planning and data access interpretation
+
+### Prompt Truth in Repo
+
+The repo contains explicit prompt artifacts for:
+
+- `cctv_profiler`
+- `lead_tagger`
+- `qd_calculator`
+
+These are concrete prompt contracts, not vague intentions. They should be treated as product logic.
+
+### Runtime Reality
+
+The system documentation repeatedly shows a hybrid runtime model:
+
+- hosted NVIDIA-compatible reasoning path as primary
+- private / local alternatives possible
+- runtime abstraction should outlive vendor choice
+
+---
+
+## 14. Data Model and Core Entities
+
+The major persistent entities reflected across the docs are:
+
+- users and roles
+- leads and lead intelligence
+- inventory and project data
+- perception sessions
+- CCTV events
+- vault assets and opens
+- omnichannel logs
+- page revisions and canvas components
+- model catalog and hydration state
+- machine sessions and cost records
+
+### Persistent Truth
+
+PostgreSQL is the primary source of truth for operational data.  
+S3 is becoming the canonical store for large model and asset artifacts.  
+AWS GPU NVMe is treated as fast ephemeral runtime cache, not authoritative storage.
+
+---
+
+## 15. Infrastructure and Deployment Model
+
+Project Velocity now has a clear split between:
+
+- **stable control surfaces**
+- **ephemeral compute workers**
+- **canonical storage**
+
+### Current Deployment Pattern
+
+- Linux box:
+  - long-lived control surface
+  - private origin services
+  - operator tooling
+- AWS t4g ingress:
+  - stable public edge
+  - route manager
+- AWS GPU instances:
+  - disposable compute nodes
+  - ComfyUI and model workloads
+- S3:
+  - canonical model / workflow / asset store
+
+### Architectural Principle
+
+This is not “one giant computer.”  
+It is:
+
+- one control plane
+- one ingress plane
+- one durable asset plane
+- many disposable compute workers
+
+That is the correct model.
+
+---
+
+## 16. Stable Ingress Layer
+
+The stable ingress layer is the permanent public front door.
+
+### Purpose
+
+- stable public IP
+- DNS target for public routes
+- TLS termination
+- hostname-based routing
+- forwarding to Linux or AWS backends
+
+### Current Public Surfaces
+
+The handoff documents establish these public hostnames as part of the route model:
+
+- `office.desineuron.in`
+- `git.desineuron.in`
+- `cloud.desineuron.in`
+- `projects.desineuron.in`
+- `talk.desineuron.in`
+- `vpn.desineuron.in`
+- `comfy.desineuron.in`
+- `ops.desineuron.in`
+
+### Key Design Principle
+
+Backends may change. Public identity should not.
+
+That is why:
+
+- GPU workers should not own the stable Elastic IP
+- the ingress box should stay alive and route based on managed config
+
+---
+
+## 17. Linux AWS Control Surface
+
+The Linux box is now the operational control surface for AWS.
+
+### Responsibilities
+
+- machine lifecycle management
+- preferred instance selection
+- spot/on-demand visibility
+- session and cost tracking
+- route management through ingress
+- model ingest and hydration orchestration
+- operator UI and CLI
+
+### Canonical Asset Strategy
+
+The documentation evolution shows a strong convergence:
+
+- Linux can store local copies
+- but S3 should be the canonical large-model source for ephemeral AWS hydration
+
+That is the right direction because S3 is:
+
+- durable
+- AWS-native
+- fast to hydrate with `s5cmd`
+- not dependent on home network conditions
+
+### Control Plane Flow
+
+```mermaid
+flowchart TD
+    A[Operator UI / CLI on Linux] --> B[Launch AWS Worker]
+    B --> C[Worker Bootstrap]
+    C --> D[Hydrate from S3]
+    D --> E[Verify Manifest]
+    E --> F[Start Workload]
+    F --> G[Map Route Through Ingress]
+    G --> H[Track Runtime / Cost / Logs]
+```
+
+---
+
+## 18. Operating Flows
+
+### Lead Intelligence Flow
+
+- lead enters through channel
+- Oracle / backend receives it
+- tagging and enrichment happen
+- lead lands in CRM operating surface
+
+### Sentinel Session Flow
+
+- broker runs session
+- MediaPipe emits perception packets
+- backend computes QD and updates lead/session state
+- notifications stream back in real time
+
+### Dream Weaver / Comfy Flow
+
+- operator or app triggers generation
+- GPU worker receives workflow
+- model hydrates if missing
+- ComfyUI or pipeline runs
+- output is returned or archived
+
+### Infra Control Flow
+
+- operator selects profile
+- Linux control surface launches worker
+- route gets mapped through ingress
+- workload is exposed without changing public identity
+
+---
+
+## 19. Security, Privacy, and Sovereignty
+
+Project Velocity’s strongest recurring architectural doctrine is data sovereignty.
+
+### Security Principles
+
+- client data belongs to client
+- on-prem or client-controlled cloud must be supported
+- zero-trust between services
+- least privilege for machine roles
+- no hidden production dependencies on developer laptops
+- auditability matters for both operations and business decisions
+
+### Privacy Positioning
+
+Velocity is explicitly positioned as anti-SaaS in the strategic docs.
+
+That means product delivery should support:
+
+- on-prem deployment
+- client-owned cloud
+- local or sovereign runtime options
+- explicit consent and audit around biometric flows
+
+This is not just a compliance detail. It is a core selling argument.
+
+---
+
+## 20. Current Live Truth
+
+Based on the most recent infrastructure handoff and operational truth docs, the current live picture is:
+
+- stable ingress is running on AWS `t4g.micro`
+- Linux box is the long-lived origin and control surface
+- ComfyUI is exposed through managed ingress routing
+- auto-heal exists for:
+  - home IP sync
+  - Comfy route sync
+- ops control plane is live on Linux
+- S3 is in place as the canonical control-plane bucket
+
+Important operational truths that should not be lost:
+
+- GPU nodes are ephemeral and should be treated that way
+- route management should be dynamic, not hardcoded
+- NVMe is for speed, not truth
+- Linux and S3 together are the operational backbone
+
+---
+
+## 21. Build Priorities and Open Gaps
+
+The documentation implies this priority order:
+
+1. stabilize control plane and ingress
+2. stabilize model hydration and GPU orchestration
+3. finish Oracle backend/runtime implementation
+4. continue iOS and web convergence
+5. standardize packaging for on-prem delivery
+
+### Open Gaps
+
+- Oracle production runtime is not fully wired yet
+- several frontend surfaces still rely on mock or transitional behavior
+- deployment packaging for customer installs is not yet standardized enough
+- multi-property / portfolio product packaging needs formalization in product artifacts
+- some business docs are strong on thesis but still need conversion into installable product contracts
+
+---
+
+## 22. Runbooks and Team Usage
+
+### What the team should point to for truth
+
+- **this master bibel** for unified product and architecture truth
+- **ingress handoff** for current infra routing truth
+- **ops control plane bibel** for operator workflows
+
+### When a new service is added
+
+The team should define:
+
+- what plane it belongs to
+- whether it is stable or ephemeral
+- where its truth is stored
+- how it is routed publicly
+- which system owns its startup, health, and recovery
+
+### Operational Rule
+
+If a workflow depends on a developer’s Windows laptop staying alive, it is not production-ready.
+
+---
+
+## 23. Source Lineage Map
+
+This master bibel draws primarily from these source families:
+
+### Product and architecture
+
+- `Project Velocity - The Oracle.md`
+- `The Sentinel Bibel.md`
+- `velocity_technical_bible.md`
+- `velocity_ios_bible.md`
+- `oracle_development_status.md`
+
+### Visual generation
+
+- `DREAMWEAVER_TECHNICAL_SPEC.md`
+- `A100_DEPLOYMENT_VALIDATION.md`
+- `comfy_engine/scripts/README.md`
+- `Project Velocity_ Dream Weaver.md`
+
+### Infra and operations
+
+- `TEAM_HANDOFF_2026-04-08.md`
+- `Desineuron Ops Control Plane Bibel.md`
+- `nemoclaw_setup_truth.md`
+- `infrastructure_deployment_manifest.md`
+- ingress and ops READMEs
+
+### Business and GTM context
+
+- `Velocity Kolkata Customer 0 Strategy - Get My Ghar.md`
+- `Kolkata Builder Intel and Meeting Map - April 2026.md`
+- `Customer Personas for Abu Dhabi and Dubai...md`
+- sprint user story docs
+
+### Prompt and AI behavior contracts
+
+- `backend/nemoclaw_prompts/*.md`
+
+---
+
+## Final Position
+
+Project Velocity is best understood as a sovereign, modular real-estate operating system with:
+
+- premium user surfaces
+- AI-driven CRM and perception intelligence
+- property-linked generation workflows
+- a private operational backbone
+- a route-stable ingress layer
+- a Linux-hosted control plane
+- S3-backed canonical model and asset strategy
+
+That is the coherent architecture the scattered docs were already converging toward.
--- a/Context/Bibels/Sourik
+++ b/Context/Bibels/Sourik
@@ -0,0 +1,355 @@
+# Sourik Code Intake and Compatibility Report
+
+**Prepared:** 2026-04-12  
+**Scope:** `Project_Velocity/Sourik` only, evaluated against the current non-`Sourik` Project Velocity codebase, built features, and live operating model  
+**Purpose:** Decide what from `Sourik` is worth merging, what is redundant, what is bloat, and where the conflicts will be
+
+---
+
+## Scoring Model
+
+| Score | Meaning |
+| --- | --- |
+| 1 | Banish. Do not merge into main. |
+| 2 | Archive only. Historical value, no production merge value. |
+| 3 | Very weak merge candidate. Requires heavy rewrite or extraction. |
+| 4 | Risky or partial. Import only if a specific owner adopts it. |
+| 5 | Mixed value. Keep for reference, not direct merge. |
+| 6 | Useful implementation ideas, but not merge-ready. |
+| 7 | Good candidate for selective integration. |
+| 8 | Strong subsystem candidate. |
+| 9 | High-value, near-merge-ready if wiring assumptions are corrected. |
+| 10 | Critical import candidate. No direct equivalent or materially better than current mainline. |
+
+---
+
+## Executive Summary
+
+The `Sourik` tree is not one clean feature branch. It is a mixed bundle of:
+
+- real backend/API work
+- a separate Go agent runtime
+- frontend additions for marketing and analytics
+- a partial iOS spike
+- strong test evidence in some areas
+- large amounts of residue:
+  - local env files
+  - coverage outputs
+  - compiled binaries
+  - sqlite prototypes
+  - pycache
+  - logs
+  - duplicate docs
+
+The correct merge posture is:
+
+- **do not merge the tree wholesale**
+- **extract selected subsystems**
+- **banish operational residue**
+- **treat the Go runtime as an alternate architecture, not as an automatic addition**
+
+Highest-value areas in `Sourik`:
+
+- Python API modules around leads, persona, analytics, websocket, kanban, and Sentinel consent/GDPR patterns
+- test coverage and test cases
+- some Catalyst service abstractions
+- some iOS camera/time-light experiment code
+
+Highest-risk areas:
+
+- duplicate backend entrypoint and alternate runtime model
+- alternate Nemoclaw + MCP + Go server stack
+- hardcoded stale infrastructure assumptions
+- local SQLite-first assumptions that conflict with current PostgreSQL truth
+- Comfy service hardcoded to stale IPs
+
+---
+
+## What Sourik Actually Contains
+
+### Implementation Shape
+
+`Sourik/velocity` contains:
+
+- Python FastAPI app:
+  - `main.py`
+  - `api/*.py`
+  - `services/*.py`
+  - `db/connection.py`
+- Go runtime:
+  - `main.go`
+  - `internal/nemoclaw/*`
+  - `internal/oracle/*`
+  - `internal/mcp/*`
+  - `internal/sentinel/*`
+  - `integrations/*.go`
+- frontend additions:
+  - `frontend/src/app/marketing/page.tsx`
+  - `frontend/src/lib/api.ts`
+  - dashboard/marketing components
+- iOS spike:
+  - `VelocityApp/*`
+- docs and summaries:
+  - `README.md`
+  - `SPRINT_SUMMARY_FOR_SAGNIK.md`
+  - `SPEC.md`
+  - `docs/*`
+- residue:
+  - `.env`
+  - `prototype.db`
+  - coverage outputs
+  - binaries
+  - logs
+  - pycache
+
+### Sourik Architecture According to Sourik
+
+The root `README.md` describes an “Agentic Operations Layer” with:
+
+- WhatsApp webhook
+- Go OpenClaw/NemoClaw layer
+- MCP server
+- ComfyUI / CRM / visual hub integrations
+
+That is a materially different center-of-gravity from the current mainline, where:
+
+- FastAPI backend is the operational center
+- Linux control surface and ingress are already live
+- Comfy routing and AWS orchestration are already established
+
+This matters. `Sourik` is not just “new features.” It contains an alternate operating model.
+
+---
+
+## Compatibility with Current Mainline
+
+### Current Mainline Truth
+
+The non-`Sourik` codebase already has:
+
+- a live FastAPI backend in `backend/main.py`
+- active routers for Sentinel, CCTV, videos, scenes, vault
+- a real Nemoclaw client abstraction in Python
+- an Oracle implementation path in `backend/oracle/*`
+- a premium React app in `app/src/*`
+- a live ingress plane in `infrastructure/desineuron_ingress/*`
+- a live Linux AWS control surface in `infrastructure/ops_control_plane/*`
+- a real iOS app tree in `iOS/velocity/velocity/*`
+
+So the comparison baseline is not theoretical. It is a partially working system with live infrastructure.
+
+### Main Compatibility Findings
+
+| Sourik Area | Mainline Equivalent | Compatibility |
+| --- | --- | --- |
+| `velocity/api/leads.py` | no equally complete current leads CRUD module in mainline backend | Good candidate |
+| `velocity/api/sentinel.py` | overlaps with `backend/routers/sentinel.py` but focuses on consent/GDPR/biometric storage | Selective candidate |
+| `velocity/api/catalyst.py` | overlaps with `backend/api/routes_catalyst.py` | Merge conflict likely |
+| `velocity/api/ws.py` | overlaps conceptually with current websocket/event logic | Selective candidate |
+| `velocity/api/analytics.py` | weak/no exact current equivalent | Good candidate |
+| `velocity/api/persona.py` | likely additive | Good candidate |
+| `velocity/api/kanban.py` | no clear current equivalent in mainline | Good candidate |
+| `velocity/services/comfyui_service.py` | conflicts with current ingress + Comfy routing + live GPU architecture | Poor direct candidate |
+| `velocity/main.py` | conflicts with `backend/main.py` | Do not merge directly |
+| `velocity/main.go` + `internal/*` | alternate runtime architecture | Do not merge directly |
+| `VelocityApp/*` | overlaps with current iOS app | Selective candidate only |
+
+---
+
+## Scored Intake Table
+
+| Sourik Path / Scope | Score | Merge Recommendation | Reason |
+| --- | ---: | --- | --- |
+| `Sourik/velocity/api/leads.py` | 8 | Selective merge candidate | Real CRUD, qualification, demographics endpoints. Mainline has product need here and no equally complete direct equivalent. Needs DB contract alignment. |
+| `Sourik/velocity/api/kanban.py` | 8 | Selective merge candidate | Kanban behavior is useful and currently underrepresented in mainline implementation. |
+| `Sourik/velocity/api/analytics.py` | 8 | Selective merge candidate | Adds reporting/analytics surface that appears useful for Marketing and Oracle support. |
+| `Sourik/velocity/api/persona.py` | 7 | Selective merge candidate | Likely additive business logic and API value. |
+| `Sourik/velocity/api/chat_logs.py` | 7 | Selective merge candidate | Useful if mapped into Oracle / CRM flows; needs contract alignment with current auth and DB. |
+| `Sourik/velocity/api/ws.py` | 7 | Selective merge candidate | Useful patterns and tests likely exist, but websocket ownership already exists in current backend. |
+| `Sourik/velocity/api/sentinel.py` | 7 | Extract specific features only | Valuable for biometric consent, GDPR, and export patterns. But it is SQLite-centered and overlaps with current Sentinel runtime. |
+| `Sourik/velocity/tests/api/*` | 9 | Strong import candidate | Test suites are high-value, especially for a fragile future merge. Adapt tests even if code is not merged verbatim. |
+| `Sourik/velocity/tests/internal/nemoclaw/*` | 7 | Import selectively | Good coverage and behavioral protection if Go/Nemo concepts are retained anywhere. |
+| `Sourik/velocity/services/ad_network_skills.py` | 7 | Selective merge candidate | Likely useful for Catalyst ad automation and may complement current Meta-focused path. |
+| `Sourik/velocity/services/social_posting.py` | 7 | Selective merge candidate | Useful capability if social publishing remains in scope. |
+| `Sourik/velocity/services/catalyst_content.py` | 7 | Selective merge candidate | Useful Catalyst logic, but must be aligned with current Comfy and asset pipeline. |
+| `Sourik/velocity/services/comfyui_service.py` | 4 | Reference only, do not merge directly | Hardcodes stale host/IP and assumes a different Comfy deployment pattern from the current live ingress-managed GPU model. |
+| `Sourik/velocity/frontend/src/app/marketing/page.tsx` | 7 | Selective UI import candidate | Useful product surface not currently dominant in mainline app. Needs design-system integration and router alignment. |
+| `Sourik/velocity/frontend/src/components/marketing/*` | 7 | Selective UI import candidate | Likely useful for Catalyst/marketing module. |
+| `Sourik/velocity/frontend/src/components/dashboard/*` | 6 | Compare component by component | Useful ideas, but mainline already has strong dashboard surfaces. Merge only where functionality is genuinely additive. |
+| `Sourik/velocity/frontend/src/lib/api.ts` | 5 | Reference only; do not merge as-is | Useful contract hints, but current mainline already has API client layers. This should inform consolidation, not become a second truth. |
+| `Sourik/VelocityApp/Features/CameraView.swift` | 7 | Selective import candidate | Good feature spike: camera capture + send-to-Comfy flow + time/light controls. Worth comparing to current iOS inventory/AR path. |
+| `Sourik/VelocityApp/Features/TimeControlSlider.swift` | 7 | Selective import candidate | Likely useful to augment Sun/lighting feature work. |
+| `Sourik/VelocityApp/Features/TimeLightEngine.swift` | 7 | Selective import candidate | Strong fit with current Velocity iOS sun-path direction. |
+| `Sourik/VelocityApp/Core/Router.swift` | 5 | Review only | Could help, but current iOS structure already has navigation patterns. |
+| `Sourik/velocity/main.py` | 3 | Do not merge directly | It creates a second FastAPI root with a different DB model, routing shape, and operational assumptions. Extract modules only. |
+| `Sourik/velocity/main.go` | 3 | Do not merge directly | Alternate runtime center. Valuable as concept or archived subsystem, but not compatible with current mainline architecture without a deliberate platform decision. |
+| `Sourik/velocity/internal/nemoclaw/*` | 4 | Review as architecture experiments only | Significant conceptual overlap with current Python Nemoclaw path. A direct merge would create two control centers. |
+| `Sourik/velocity/internal/mcp/*` | 5 | Review selectively | Interesting if you want future MCP work, but not aligned with current operational center yet. |
+| `Sourik/velocity/internal/oracle/*` | 4 | Reference only for now | Current mainline already has an Oracle implementation direction in Python. Direct merge would fork the architecture. |
+| `Sourik/velocity/internal/sentinel/sentinel_api.go` | 4 | Reference only | Sentinel is already active in Python backend. |
+| `Sourik/velocity/integrations/*.go` | 5 | Review case-by-case | Potentially useful adapters, but only if the Go runtime is retained. |
+| `Sourik/velocity/docs/COMFYUI_HANDOFF.md` | 6 | Keep as reference | Useful context for intended wire-up, but assumes VPN/headscale-era setup that no longer matches current ingress truth. |
+| `Sourik/SPRINT_SUMMARY_FOR_SAGNIK.md` | 7 | Keep as reference artifact | Useful for intent, coverage claims, and blocked wire list. Not production code. |
+| `Sourik/SPEC.md` | 5 | Archive as historical spec | Useful context, but contains stale node IPs, port assumptions, and stage-only instructions that no longer match live infrastructure. |
+| `Sourik/PRD.md` | 2 | Archive only | Too thin to be operationally meaningful. |
+| `Sourik/velocity/README.md` | 6 | Keep as architecture snapshot | Good summary of Sourik’s intended architecture. |
+| `Sourik/velocity/.env` | 1 | Banish | Local secrets/config residue. Must not merge. |
+| `Sourik/desineuron-l4-node.pem` | 1 | Banish | Private key material in source tree. Never merge. |
+| `Sourik/velocity/db/prototype.db` | 1 | Banish | Local prototype database, not source. |
+| `Sourik/velocity/prototype.db` | 1 | Banish | Same issue. |
+| `Sourik/velocity/.coverage` | 1 | Banish | Coverage artifact. |
+| `Sourik/velocity/coverage*` | 1 | Banish | Coverage outputs, not source. |
+| `Sourik/velocity/.agent/*coverage*`, `*test_output*` | 1 | Banish | CI/test residue. |
+| `Sourik/velocity/antigravity_server` | 1 | Banish | Compiled binary, not source. |
+| `Sourik/velocity/antigravity_test_build.exe` | 1 | Banish | Compiled Windows artifact, not source. |
+| `Sourik/velocity/__pycache__`, `.pytest_cache` | 1 | Banish | Generated caches. |
+| `Sourik/velocity/logs/VALIDATION_FINAL.log` | 2 | Archive only | Useful as evidence, not source. |
+| `Sourik/velocity/test_out.txt`, `guide_extracted.txt`, `guide_utf8.txt` | 2 | Archive only | Scratch outputs. |
+| `Sourik/velocity/stubs/*` | 3 | Archive or keep in a clearly marked scratch area | Potentially useful examples, but not merge targets. |
+| `Sourik/velocity/archive/*` | 2 | Archive only | Historical material. |
+
+---
+
+## Bloat and Residue in Sourik
+
+These are immediate no-merge items:
+
+- private keys
+- `.env`
+- `.coverage`
+- `coverage*`
+- `.pytest_cache`
+- `__pycache__`
+- compiled binaries
+- local sqlite databases
+- raw logs
+- scratch text files
+
+These do not need debate. They are not source code.
+
+---
+
+## Redundant vs Additive Features
+
+### Redundant or Architecturally Conflicting
+
+1. **FastAPI root app**
+   - `Sourik/velocity/main.py`
+   - conflicts with current `backend/main.py`
+   - creates a second root service with different routing and DB assumptions
+
+2. **Go agent runtime**
+   - `Sourik/velocity/main.go`
+   - `internal/nemoclaw/*`
+   - `internal/mcp/*`
+   - this is an alternate operational center, not a drop-in feature set
+
+3. **ComfyUI service**
+   - assumes stale IP-based deployment
+   - current system already has:
+     - stable ingress
+     - GPU worker tagging
+     - auto-healing route sync
+     - Linux AWS control plane
+
+### Additive and Potentially Valuable
+
+1. **Lead / Kanban / Persona / Analytics Python APIs**
+   - mainline can benefit directly from these
+
+2. **Sentinel consent and GDPR patterns**
+   - these are useful as selective feature imports into current Sentinel
+
+3. **Marketing frontend**
+   - a real additive surface for the Catalyst/marketing module
+
+4. **iOS camera and time/light features**
+   - fit directly with current iPad vision and sun/AR direction
+
+5. **Test suites**
+   - very high value regardless of whether code merges directly
+
+---
+
+## Compatibility with Built Features
+
+### Works with Current Mainline Direction
+
+- property and lead workflows
+- marketing/campaign intelligence
+- camera-driven iOS interactions
+- GDPR/consent handling
+- Kanban CRM motions
+
+### Conflicts with Current Mainline Truth
+
+- SQLite/prototype-first database assumptions
+- hardcoded or stale infrastructure endpoints
+- alternate Go-first NemoClaw/MCP control center
+- separate backend root service
+- stale VPN/headscale-era deployment assumptions
+
+---
+
+## Recommended Intake Strategy
+
+### Merge Now Candidates
+
+- `velocity/api/leads.py`
+- `velocity/api/kanban.py`
+- `velocity/api/analytics.py`
+- `velocity/api/persona.py`
+- tests supporting the above
+- selected marketing frontend components
+- selected iOS camera/time-light feature files
+
+### Extract, Rewrite, Then Merge
+
+- `velocity/api/sentinel.py`
+- `velocity/api/chat_logs.py`
+- `velocity/services/*`
+- `frontend/src/lib/api.ts`
+
+### Do Not Merge Directly
+
+- `velocity/main.py`
+- `velocity/main.go`
+- `velocity/internal/nemoclaw/*`
+- `velocity/internal/oracle/*`
+- `velocity/internal/mcp/*`
+- `velocity/services/comfyui_service.py`
+
+### Banish Immediately from Merge Candidate Set
+
+- `.env`
+- `.pem`
+- `.db`
+- `coverage*`
+- `.coverage`
+- `.pytest_cache`
+- `__pycache__`
+- binaries
+- logs
+- scratch outputs
+
+---
+
+## Final Recommendation
+
+Sourik’s code should be treated as:
+
+- **30% importable feature work**
+- **30% useful reference and test material**
+- **40% architectural conflict or residue**
+
+The best path is:
+
+1. strip all residue first
+2. import Python feature modules selectively
+3. import tests aggressively
+4. compare marketing frontend additions against current app
+5. compare iOS camera/time-light features against current iOS app
+6. keep the Go/Nemo/MCP stack out of the first merge unless you deliberately choose to adopt that architecture
+
+That will give you the value in Sourik’s work without poisoning the current mainline with a second operating model.
+