docs: update README with full architecture and deploy instructions

README.md

@@ -1,17 +1,83 @@
 # Manar (منار) — AI Paid Media Ops Platform
 
-Manar means beacon/lighthouse in Arabic.
+Live: https://manar.asktam.net
-Monitor → Diagnose → Recommend → Execute → Report
+
+## Stack
+- **Frontend:** Next.js 14 + Tailwind + TypeScript
+- **Backend:** Python FastAPI (`manar-mcp` container)
+- **Databases:** PostgreSQL (core + tenants) + ClickHouse (metrics/analytics)
+- **VPS:** 76.13.157.7
+
+## Architecture
+
+### Multi-tenant
+- `manar_core` DB: users, brands, memberships
+- `manar_tenants` DB: per-brand schemas (`brand_alluriv`, `brand_asktam`, etc.)
+- Each brand schema contains: recommendations, audit_log, ai_memory, brand_context, ad_accounts, ad_credentials
+
+### AI Engine
+- **Recommendations engine:** Claude claude-sonnet-4 with execution state memory — prevents conflicting recs
+- **Execution state:** persistent per-campaign strategy memory stored in `brand_context`
+- **Anomaly detection:** 6 metric types (CPC, CTR, ROAS, impressions, budget_burn, zero_conversions)
+- **Corrective engine:** anomaly → Claude analysis → corrective recs → auto-execute (L2/L3 pilot)
+- **Budget guard:** no budget increases when campaign ROAS < 70% of target
+- **Conflict prevention:** 3 layers — prompt injection, post-generation filter, periodic purge
+
+### Transparency
+Every recommendation shows its trigger, action type, executability, and source engine.
 
 ## Containers
-- manar-frontend: Next.js at manar.asktam.net
-- manar-core-db: Postgres 16 (brands, users, memberships)
-- manar-tenants-db: Postgres 16 (per-brand schemas)
-- manar-mcp: FastMCP Google Ads connector
 
-## Brands (Phase 1)
+| Container | Role | Port |
-- Al Salama Medical: Google Ads 5467427558
+|---|---|---|
-- Ask Tam
+| `manar-mcp` | FastAPI REST + MCP server | 8092 (API), 8090 (MCP), 8091 (health) |
+| `manar-frontend` | Next.js UI | 3000 |
+| `manar-core-db` | Users/brands registry | 5432 |
+| `manar-tenants-db` | Per-brand operational data | 5432 |
 
-## Trust Ladder
+## Deploy
-L0 Observer | L1 Suggest | L2 Auto+veto | L3 Autopilot
+
+### MCP Backend
+```bash
+docker build -t manar-mcp:latest ./mcp/
+docker stop manar-mcp && docker rm manar-mcp
+docker run -d --name manar-mcp --network coolify --restart unless-stopped \
+  -e CLICKHOUSE_HOST=clickhouse -e CLICKHOUSE_PORT=8123 \
+  -e CLICKHOUSE_USER=tam -e "CLICKHOUSE_PASSWORD=Tam@ClickHouse2026!" \
+  -e CLICKHOUSE_DB=manar -e MCP_PORT=8090 -e API_PORT=8092 -e HEALTH_PORT=8091 \
+  -e "CORE_DB_URL=postgresql://manar:mn_c0re_2026_s3cr3t@manar-core-db:5432/manar_core" \
+  -e "TENANTS_DB_URL=postgresql://manar:mn_t3n4nts_2026_s3cr3t@manar-tenants-db:5432/manar_tenants" \
+  -e APP_URL=https://manar.asktam.net \
+  -e GOOGLE_ADS_CLIENT_ID=... \
+  -e GOOGLE_ADS_CLIENT_SECRET=... \
+  -e GOOGLE_ADS_DEVELOPER_TOKEN=... \
+  --health-cmd "curl -sf http://localhost:8091/health" --health-interval 15s \
+  manar-mcp:latest
+```
+
+### Frontend
+```bash
+docker build -t manar-frontend:latest ./frontend/
+docker compose -f ./frontend/docker-compose.yml up -d --force-recreate
+```
+
+### New Brand Onboarding
+```bash
+curl -X POST https://manar.asktam.net/api/alluriv/api/admin/brands/{slug}/bootstrap
+```
+
+## Admin Login
+- URL: https://manar.asktam.net/login
+- Email: loveriver7@gmail.com
+- Password: Manar2026!
+
+## Key Files
+- `mcp/api.py` — all REST endpoints (~86KB)
+- `mcp/recommendations_engine.py` — Claude prompt + budget guard + conflict filter
+- `mcp/execution_state.py` — per-campaign strategy memory
+- `mcp/execution_engine.py` — 20 Google Ads API actions
+- `mcp/anomaly_engine.py` — ClickHouse anomaly detection
+- `mcp/corrective_engine.py` — anomaly → corrective recommendations
+- `mcp/scheduler.py` — daily 2am automation loop
+- `frontend/src/app/dashboard/[brand_slug]/` — dashboard pages
+- `frontend/src/components/RecommendationCard.tsx` — rec card with transparency