From c0490733d43a5141effb4161a62e14454915d027 Mon Sep 17 00:00:00 2001 From: Sami Assiri Date: Sat, 2 May 2026 00:06:37 +0300 Subject: [PATCH] docs(ops): command board, Claude/Cursor charters, staging one-shots - DEALIX_ACTIVE_COMMAND_BOARD: North Star, allowed/do-not-build, build freeze - Claude/Cursor charters to split docs vs code ownership - STAGING_PAID_BETA_READY_ONE_SHOT + STAGING_WORKFLOW_GITHUB (avoid *_secret* gitignore) - COMMERCIAL_CLOSE_COPY_CHECKLIST for owner-facing close - Link from PAID_BETA_FULL_RUNBOOK, POST_MERGE, START_HERE --- dealix/docs/PAID_BETA_FULL_RUNBOOK_AR.md | 2 + dealix/docs/POST_MERGE_VERIFICATION.md | 3 +- .../ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md | 52 ++++++++++++ .../docs/ops/DEALIX_ACTIVE_COMMAND_BOARD.md | 82 +++++++++++++++++++ dealix/docs/ops/DEALIX_CLAUDE_WORK_CHARTER.md | 54 ++++++++++++ .../ops/DEALIX_CURSOR_ENGINEERING_CHARTER.md | 61 ++++++++++++++ .../ops/STAGING_PAID_BETA_READY_ONE_SHOT.md | 64 +++++++++++++++ dealix/docs/ops/STAGING_WORKFLOW_GITHUB.md | 35 ++++++++ dealix/docs/sales-kit/START_HERE.md | 2 + 9 files changed, 354 insertions(+), 1 deletion(-) create mode 100644 dealix/docs/ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md create mode 100644 dealix/docs/ops/DEALIX_ACTIVE_COMMAND_BOARD.md create mode 100644 dealix/docs/ops/DEALIX_CLAUDE_WORK_CHARTER.md create mode 100644 dealix/docs/ops/DEALIX_CURSOR_ENGINEERING_CHARTER.md create mode 100644 dealix/docs/ops/STAGING_PAID_BETA_READY_ONE_SHOT.md create mode 100644 dealix/docs/ops/STAGING_WORKFLOW_GITHUB.md diff --git a/dealix/docs/PAID_BETA_FULL_RUNBOOK_AR.md b/dealix/docs/PAID_BETA_FULL_RUNBOOK_AR.md index 1f70b960..e6c3250e 100644 --- a/dealix/docs/PAID_BETA_FULL_RUNBOOK_AR.md +++ b/dealix/docs/PAID_BETA_FULL_RUNBOOK_AR.md @@ -12,6 +12,8 @@ Layer 14 (بريد + battlecards + ديمو ١٢ دقيقة) → [`sales-kit/STA **مراجع تقنية:** [`POST_MERGE_VERIFICATION.md`](POST_MERGE_VERIFICATION.md) · [`BRANCH_PROTECTION_AND_CI.md`](BRANCH_PROTECTION_AND_CI.md) · [`STAGING_DEPLOYMENT.md`](STAGING_DEPLOYMENT.md) · [`ops/RAILWAY_AI_COMPANY_BIND.md`](ops/RAILWAY_AI_COMPANY_BIND.md) +**تشغيل متعدد الوكلاء (Claude Work / Cursor):** [`ops/DEALIX_ACTIVE_COMMAND_BOARD.md`](ops/DEALIX_ACTIVE_COMMAND_BOARD.md) · [`ops/STAGING_PAID_BETA_READY_ONE_SHOT.md`](ops/STAGING_PAID_BETA_READY_ONE_SHOT.md) · [`ops/STAGING_WORKFLOW_GITHUB.md`](ops/STAGING_WORKFLOW_GITHUB.md) · [`ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md`](ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md) + --- ## المرحلة A — إغلاق GitHub (حماية الفرع) diff --git a/dealix/docs/POST_MERGE_VERIFICATION.md b/dealix/docs/POST_MERGE_VERIFICATION.md index abbf2cd5..91dd0524 100644 --- a/dealix/docs/POST_MERGE_VERIFICATION.md +++ b/dealix/docs/POST_MERGE_VERIFICATION.md @@ -89,7 +89,7 @@ Confirm GitHub Actions workflow [`.github/workflows/dealix-api-ci.yml`](../../.g | Merge PR | [#30](https://github.com/VoXc2/system-prompts-and-models-of-ai-tools/pull/30) merged into `ai-company` — merge commit `c95179e` | | Dealix API CI on PR | `pytest` / `smoke_inprocess` / `launch_readiness` — **pass** (run `25232625374`) | | Branch protection (`ai-company`) | Verified: required contexts `pytest`, `smoke_inprocess`, `launch_readiness`; PR required; no force-push | -| Local re-run (`APP_ENV=test`, `--no-cov`) | `797 passed`, `6 skipped` on merge tip | +| Local re-run (`APP_ENV=test`, `--no-cov`) | `797 passed`, `6 skipped` — أعيد التحقق 2026-05-02 على `fa29e29` | | `print_routes.py` | `ROUTE_CHECK_OK no duplicate method+path` | | `smoke_inprocess.py` | `SMOKE_INPROCESS_OK` | | `launch_readiness_check.py` (local) | `GO_PRIVATE_BETA` — لتعيين `PAID_BETA_READY` شغّل نفس السكربت مع `--base-url` على URL staging بعد Railway | @@ -98,6 +98,7 @@ Confirm GitHub Actions workflow [`.github/workflows/dealix-api-ci.yml`](../../.g ## Manual follow-ups (not automated) +- **لوحة قيادة التشغيل (Claude/Cursor):** [`ops/DEALIX_ACTIVE_COMMAND_BOARD.md`](ops/DEALIX_ACTIVE_COMMAND_BOARD.md) - ~~Merge Layer 13/14 into `ai-company`~~ — تم عبر PR [#30](https://github.com/VoXc2/system-prompts-and-models-of-ai-tools/pull/30). - **Railway:** انشر من فرع `ai-company`، root `dealix`، حسب [`PAID_BETA_FULL_RUNBOOK_AR.md`](PAID_BETA_FULL_RUNBOOK_AR.md) و[`ops/RAILWAY_AI_COMPANY_BIND.md`](ops/RAILWAY_AI_COMPANY_BIND.md). - **Secrets + staging smoke:** أضف `STAGING_BASE_URL` في GitHub Actions ثم شغّل smoke يدوياً من الواجهة إن لم يظهر الـ workflow في `gh workflow list`. diff --git a/dealix/docs/ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md b/dealix/docs/ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md new file mode 100644 index 00000000..30c77acb --- /dev/null +++ b/dealix/docs/ops/COMMERCIAL_CLOSE_COPY_CHECKLIST.md @@ -0,0 +1,52 @@ +# إغلاق تجاري — قائمة نسخ جاهزة (مالك المنتج) + +لا أتمتة هنا — نفّذ يدوياً بعد `PAID_BETA_READY`. المرجع الكامل: [`../PAID_BETA_FULL_RUNBOOK_AR.md`](../PAID_BETA_FULL_RUNBOOK_AR.md). + +--- + +## 1) Moyasar + +- فاتورة **499 SAR** — وصف واضح (Pilot 7 أيام). +- أرسل الرابط عبر قناة موثوقة (إيميل / رسالة يدوية مع opt-in حيث ينطبق). + +--- + +## 2) 25 لمسة + Operating Board + +- أنشئ Google Sheet: **Dealix Paid Beta Operating Board** +- الأعمدة كما في الـ Runbook: `company`, `person`, `segment`, `channel`, `message_sent_at`, `reply_status`, `demo_booked`, … + +قوالب بريد ومتابعة: [`../sales-kit/layer14_email_sequences_4x7_ar.md`](../sales-kit/layer14_email_sequences_4x7_ar.md) + +--- + +## 3) ديمو + Diagnostic + Pilot + +- سكربت ديمو 12 دقيقة: [`../sales-kit/layer14_demo_12min_script_ar.md`](../sales-kit/layer14_demo_12min_script_ar.md) +- Battlecards: [`../sales-kit/layer14_battlecards_6_ar.md`](../sales-kit/layer14_battlecards_6_ar.md) + +--- + +## 4) Proof Pack + +الهيكل في الـ Runbook (قسم Proof Pack). سلّم نسخة واحدة مكتوبة بعد أول أسبوع تشغيل متفق عليه. + +--- + +## 5) Scorecard يومي + +من مجلد `dealix`: + +```bash +python scripts/paid_beta_daily_scorecard.py --messages 25 --replies 0 --demos 0 --pilots 0 --payments 0 --proof-packs 0 +``` + +حدّث الأرقام حسب الـ Sheet. + +--- + +## علامة «إغلاق تجاري» + +```text +دفع أو commitment مكتوب + Proof Pack مُرسل + سجل في الـ Operating Board +``` diff --git a/dealix/docs/ops/DEALIX_ACTIVE_COMMAND_BOARD.md b/dealix/docs/ops/DEALIX_ACTIVE_COMMAND_BOARD.md new file mode 100644 index 00000000..c24ac5b8 --- /dev/null +++ b/dealix/docs/ops/DEALIX_ACTIVE_COMMAND_BOARD.md @@ -0,0 +1,82 @@ +# DEALIX_ACTIVE_COMMAND_BOARD + +صفحة قيادة واحدة — حدّث التاريخ عند تغيير التركيز. الهدف منع تضارب Claude Work و Cursor على نفس الملفات. + +--- + +## North Star + +```text +إغلاق Paid Beta حقيقية = PAID_BETA_READY (staging) + أول payment/commitment + أول Proof Pack +``` + +المرجع التنفيذي: [`../PAID_BETA_FULL_RUNBOOK_AR.md`](../PAID_BETA_FULL_RUNBOOK_AR.md) + +--- + +## الفرع المحمي للنشر + +```text +ai-company +``` + +لا commits مباشرة — PR فقط، CI أخضر. + +--- + +## PR / فرع العمل النشط (عدّل عند الفتح) + +```text +(لا يوجد PR نشط مذكور هنا — املأ عند بدء موجة) +``` + +--- + +## مسموح الآن (Allowed Work) + +```text +Staging + إصلاحات تمنع فشل PAID_BETA_READY فقط +Sales kit + docs + قوالب outreach (بدون تغيير claims) +smoke_staging / launch_readiness_check +اختبارات لأي إصلاح تقني ضروري +``` + +--- + +## ممنوع (Do Not Build) — حتى إشعار آخر + +```text +Saudi Revenue Graph / patch كبير قبل PAID_BETA_READY +Founder Console / frontend جديد واسع قبل أول عميل +Tenant model + ledger كامل + background jobs (ما لم يُسجّل طلب عميل مرتين أو ألم تشغيلي) +marketplace / white-label +LinkedIn scraping أو auto-DM +cold WhatsApp +live Gmail send +live Moyasar charge (استخدم invoice يدوي) +تغيير pricing أو POSITIONING_LOCK أو safety rules بدون موافقة صريحة +``` + +--- + +## تجميد البناء (Build freeze) + +لا PR لميزات جديدة قبل: + +```text +PAID_BETA_READY على URL staging +``` + +بعدها: فقط ما يخدم البيع أو يصلح بوابة الإطلاق — انظر شروط «متى تبني كود» في الـ Runbook. + +--- + +## روابط سريعة + +| موضوع | ملف | +|--------|------| +| أوامر staging → PAID_BETA_READY | [`STAGING_PAID_BETA_READY_ONE_SHOT.md`](STAGING_PAID_BETA_READY_ONE_SHOT.md) | +| Secret + workflow | [`STAGING_WORKFLOW_GITHUB.md`](STAGING_WORKFLOW_GITHUB.md) | +| تشغيل Claude (وثائق فقط) | [`DEALIX_CLAUDE_WORK_CHARTER.md`](DEALIX_CLAUDE_WORK_CHARTER.md) | +| تشغيل Cursor (كود) | [`DEALIX_CURSOR_ENGINEERING_CHARTER.md`](DEALIX_CURSOR_ENGINEERING_CHARTER.md) | +| إغلاق تجاري (نسخ/قائمة) | [`COMMERCIAL_CLOSE_COPY_CHECKLIST.md`](COMMERCIAL_CLOSE_COPY_CHECKLIST.md) | diff --git a/dealix/docs/ops/DEALIX_CLAUDE_WORK_CHARTER.md b/dealix/docs/ops/DEALIX_CLAUDE_WORK_CHARTER.md new file mode 100644 index 00000000..4f75b177 --- /dev/null +++ b/dealix/docs/ops/DEALIX_CLAUDE_WORK_CHARTER.md @@ -0,0 +1,54 @@ +# Dealix — Claude Work (استراتيجة + وثائق + مبيعات) + +**الدور:** Strategy، Sales kit، توثيق تشغيلي، قوالب رسائل، battlecards، خطط محتوى — **بدون تعديل كود المنتج**. + +--- + +## مسموح المسار + +```text +dealix/docs/ +dealix/docs/sales-kit/ +dealix/docs/marketing/ (إن وُجد) +نصوص landing كـ Markdown أو نسخ مقترحة — فقط إذا طُلب صراحة وليس تغيير claims بلا مراجعة POSITIONING_LOCK +``` + +--- + +## ممنوع بدون موافقة كتابية من المالك + +```text +dealix/api/ +dealix/db/ +dealix/core/ +dealix/integrations/ +.github/workflows/ +أي تغيير على POSITIONING_LOCK أو APPROVED_MARKETING أو التسعير الظاهر للعميل +تفعيل أي إرسال حي (واتساب / إيميل) +``` + +--- + +## قبل أي تسليم + +1. اذكر **قائمة الملفات** التي ستُعدّل. +2. أكد أن المخرجات تخدم: outreach → demo → pilot → proof pack → upgrade. +3. بعد التنفيذ: **diff summary** + جملة واحدة: «لا تأثير على كود التشغيل» إن كان التعديل وثائق فقط. + +--- + +## ممنوع في المحتوى + +```text +وعود نتائج مضمونة +scraping أو قوائم مكشوفة غير مشروعة +cold WhatsApp +Live send +``` + +--- + +## الربط + +- لوحة القيادة: [`DEALIX_ACTIVE_COMMAND_BOARD.md`](DEALIX_ACTIVE_COMMAND_BOARD.md) +- المهندس: [`DEALIX_CURSOR_ENGINEERING_CHARTER.md`](DEALIX_CURSOR_ENGINEERING_CHARTER.md) diff --git a/dealix/docs/ops/DEALIX_CURSOR_ENGINEERING_CHARTER.md b/dealix/docs/ops/DEALIX_CURSOR_ENGINEERING_CHARTER.md new file mode 100644 index 00000000..2c72be2d --- /dev/null +++ b/dealix/docs/ops/DEALIX_CURSOR_ENGINEERING_CHARTER.md @@ -0,0 +1,61 @@ +# Dealix — Cursor / Engineering (كود + اختبارات + CI) + +**الدور:** تنفيذ تقني، إصلاحات staging، سكربتات smoke، واجهات HTML عند الحاجة — **عبر فرع صغير + PR إلى `ai-company`**. + +--- + +## القواعد + +```text +لا commits على ai-company مباشرة +كل تغيير: branch قصير + PR + CI أخضر قبل الدمج +``` + +--- + +## أولويات المرحلة الحالية (إغلاق Paid Beta) + +1. إصلاحات تمنع فشل `PAID_BETA_READY` فقط (مسارات، env، landing المطلوبة من readiness). +2. [`scripts/smoke_staging.py`](../../scripts/smoke_staging.py) و [`scripts/launch_readiness_check.py`](../../scripts/launch_readiness_check.py) — لا تغيير سلوك البوابات إلا لإصلاح bug موثّق. +3. اختبارات لكل إصلاح. + +--- + +## ممنوع + +```text +live send (WhatsApp / Gmail / إلخ) +LinkedIn scraping أو auto-DM +cold WhatsApp +Moyasar charge برمجي +تغيير pricing أو safety rules أو POSITIONING_LOCK بدون موافقة +migrations واسعة بدون سبب عميل/تشغيل مسجّل +``` + +--- + +## قبل PR + +1. الملفات التي تُلامس. +2. سبب التعديل (سطر واحد). +3. أوامر التحقق التي ستُشغّل. + +--- + +## بعد التعديل (محلياً من `dealix`) + +```bash +APP_ENV=test pytest -q --no-cov +python scripts/print_routes.py +python scripts/smoke_inprocess.py +python scripts/launch_readiness_check.py +``` + +لا تفتح PR إذا فشل أي منها (ما عدا `launch_readiness_check` بدون `--base-url` المتوقع `GO_PRIVATE_BETA` محلياً). + +--- + +## الربط + +- لوحة القيادة: [`DEALIX_ACTIVE_COMMAND_BOARD.md`](DEALIX_ACTIVE_COMMAND_BOARD.md) +- الوثائق: [`DEALIX_CLAUDE_WORK_CHARTER.md`](DEALIX_CLAUDE_WORK_CHARTER.md) diff --git a/dealix/docs/ops/STAGING_PAID_BETA_READY_ONE_SHOT.md b/dealix/docs/ops/STAGING_PAID_BETA_READY_ONE_SHOT.md new file mode 100644 index 00000000..350141c7 --- /dev/null +++ b/dealix/docs/ops/STAGING_PAID_BETA_READY_ONE_SHOT.md @@ -0,0 +1,64 @@ +# Staging — من Railway إلى `PAID_BETA_READY` (أوامر جاهزة) + +**الشرط:** خدمة Dealix منشورة على URL عام (مثلاً Railway)، `Service Root = dealix`، و: + +```bash +uvicorn api.main:app --host 0.0.0.0 --port $PORT +``` + +Healthcheck على `/health` يعيد `200`. + +**لا تضع شرطة مائلة أخيرة** على `STAGING_BASE_URL` إن أمكن. + +--- + +## 1) من جذر حزمة `dealix` + +### PowerShell (Windows) + +```powershell +$env:STAGING_BASE_URL = "https://YOUR-STAGING-HOST" +python scripts/smoke_staging.py --base-url $env:STAGING_BASE_URL +python scripts/launch_readiness_check.py --base-url $env:STAGING_BASE_URL +``` + +### bash + +```bash +export STAGING_BASE_URL="https://YOUR-STAGING-HOST" +python scripts/smoke_staging.py --base-url "$STAGING_BASE_URL" +python scripts/launch_readiness_check.py --base-url "$STAGING_BASE_URL" +``` + +إذا فرض الـ staging مفتاح API: + +```bash +export STAGING_API_KEY="your-staging-key" +``` + +(يُرسل كـ `X-API-Key` — انظر [`scripts/smoke_staging.py`](../../scripts/smoke_staging.py).) + +--- + +## 2) علامة النجاح + +```text +smoke_staging.py → exit 0 +launch_readiness_check.py → VERDICT: PAID_BETA_READY و exit 0 +``` + +إذا `NO_GO`: راجع مخرجات السكربت (مسارات، landing، `WHATSAPP_ALLOW_LIVE_SEND`, كتالوج الخدمات) قبل أي بيع. + +--- + +## 3) Railway (تلخيص) + +| إعداد | القيمة | +|--------|--------| +| Branch | `ai-company` | +| Root | `dealix` | +| Start | `uvicorn api.main:app --host 0.0.0.0 --port $PORT` | +| Health | `/health` | +| متغيرات أولية | `APP_ENV=staging`, `WHATSAPP_ALLOW_LIVE_SEND=false` + مفاتيح اختبار حسب القوالب | + +تفاصيل إضافية: [`RAILWAY_AI_COMPANY_BIND.md`](RAILWAY_AI_COMPANY_BIND.md) و[`../PAID_BETA_FULL_RUNBOOK_AR.md`](../PAID_BETA_FULL_RUNBOOK_AR.md). diff --git a/dealix/docs/ops/STAGING_WORKFLOW_GITHUB.md b/dealix/docs/ops/STAGING_WORKFLOW_GITHUB.md new file mode 100644 index 00000000..89e61379 --- /dev/null +++ b/dealix/docs/ops/STAGING_WORKFLOW_GITHUB.md @@ -0,0 +1,35 @@ +# GitHub Actions — `STAGING_BASE_URL` و Dealix staging smoke + +## 1) إضافة السر + +1. GitHub → **Settings** → **Secrets and variables** → **Actions** +2. **New repository secret** + - الاسم: `STAGING_BASE_URL` + - القيمة: `https://your-staging-host` (بدون `/` في النهاية إن أمكن) + +اختياري إذا الـ API يتطلب مفتاحاً: + +- `STAGING_API_KEY` — يُستخدم من [`dealix-staging-smoke.yml`](../../../.github/workflows/dealix-staging-smoke.yml) عبر env (راجع الملف). + +--- + +## 2) تشغيل الـ workflow + +1. **Actions** → ابحث عن **Dealix staging smoke** +2. **Run workflow** — اختر الفرع الذي **يحتوي ملف** `.github/workflows/dealix-staging-smoke.yml` في الـ commit (غالباً `ai-company` بعد الدمج). + +إذا **لم يظهر** الـ workflow في القائمة أو في `gh workflow list`: + +- GitHub يحمّل تعريفات الـ workflows من **الفرع الافتراضي** للريبو غالباً. إذا كان `main` لا يحتوي الملف بينما `ai-company` يحتويه، انسخ الملف إلى `main` عبر PR صغير **أو** غيّر الفرع الافتراضي مؤقتاً (سياسة الفريق). + +--- + +## 3) السلوك عند غياب السر + +الـ workflow يتخطى الخطوات برسالة ويخرج `0` إذا `STAGING_BASE_URL` فارغ — **لا يعطي إذناً بالبيع**. تأكد يدوياً أن السر مضبوط ثم أعد التشغيل. + +--- + +## مرجع الملف + +[`../../../.github/workflows/dealix-staging-smoke.yml`](../../../.github/workflows/dealix-staging-smoke.yml) diff --git a/dealix/docs/sales-kit/START_HERE.md b/dealix/docs/sales-kit/START_HERE.md index c43122c3..faf437a9 100644 --- a/dealix/docs/sales-kit/START_HERE.md +++ b/dealix/docs/sales-kit/START_HERE.md @@ -37,6 +37,8 @@ يُكمّل الجدول أعلاه ولا يستبدل `dealix_demo_script_30min.md` إذا احتجت ديمو أطول. +**تنسيق العمل (Claude / Cursor):** [`../ops/DEALIX_ACTIVE_COMMAND_BOARD.md`](../ops/DEALIX_ACTIVE_COMMAND_BOARD.md) + --- ## 📅 الخطة في 5 مراحل