@tera-system/core 0.1.0

package/core/tera-system/TOOLING_AND_MCP_POLICY.md

@@ -0,0 +1,285 @@
+<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
+
+# TOOLING_AND_MCP_POLICY.md
+
+# سياسة الأدوات و MCPs لمنظومة Tera
+
+---
+
+## 1. تعريفات أساسية
+
+### 1.1 الفرق بين Agent و Tool و MCP
+
+| المفهوم | التعريف | مثال |
+|---|---|---|
+| **Agent** | كيان يفكر ويحلل ويقرر ضمن تخصصه. يقرأ مدخلات، يطبق معرفة، وينتج مخرجات. يملك صلاحية اتخاذ قرار محدودة ضمن نطاقه. | `EngineeringAgent` ينفذ كود بناءً على مهمة. |
+| **Tool** | أمر أو برنامج ينفذ إجراء محددًا. لا يفكر ولا يقرر، فقط ينفذ. قد يكون CLI أو API أو وظيفة برمجية. | `git diff`، `npm test`، `playwright test` |
+| **MCP** (Model Context Protocol) | واجهة اتصال تسمح للـ Agent بالتفاعل مع أنظمة خارجية. يوفر سياقًا إضافيًا للـ Agent (قراءة) أو يسمح له بتنفيذ إجراءات (كتابة). | Playwright MCP لاختبار UI، GitHub MCP لقراءة المستودع |
+
+### 1.2 قاعدة الفصل
+
+```text
+Agent يفكر ويقرر.
+Tool ينفذ.
+MCP يربط الـ Agent بالنظام الخارجي.
+```
+
+> **لا تخلط بين Agent و Tool.**
+>
+> الـ Agent يقرر. الأداة تنفذ. MCP يربط.
+> الأداة لا تقرر. MCP لا يقرر. القرار يبقى عند Tera أو العميل المفوّض.
+
+---
+
+## 2. مبادئ استخدام الأدوات و MCPs
+
+### 2.1 المبادئ العامة
+
+1. **الأداة للتنفيذ، وليست للقرار.**
+2. **أي استخدام لـ MCP يجب أن يكون له Trigger واضح من Tera.**
+3. **لا استخدام عشوائي للأدوات.**
+4. **الصلاحية Read-Only هي الأصل للأدوات التي تتعامل مع بيانات حقيقية.**
+5. **أداة Write تحتاج موافقة صريحة من Tera أو المستخدم.**
+6. **لا استخدام لأسرار Production عبر أي أداة.**
+7. **نتائج الأدوات تُسجل في ملفات project-control المناسبة.**
+
+### 2.2 متى نستخدم MCP؟
+
+```text
+نستخدم MCP عندما:
+- الـ Agent يحتاج معلومات لا توجد في ملفات المشروع.
+- الـ Agent يحتاج التحقق من شيء خارجي (مثل API يعمل، UI يظهر صح).
+- الـ Agent يحتاج تفاعل مع نظام لا يمكن الوصول إليه بالقراءة فقط.
+
+لا نستخدم MCP عندما:
+- المعلومة موجودة في ملفات المشروع.
+- يمكن التحقق يدويًا بقراءة بسيطة.
+- الأداة قد تسبب تغيير غير مرغوب في نظام خارجي.
+```
+
+---
+
+## 3. MCPs المسموحة الآن (الحد الأدنى الضروري)
+
+> **✅ الوضع الفعلي الموثق (2026-07-31):** التكوين النشط في `.opencode/opencode.json` و `~/.config/opencode/opencode.jsonc` يتضمن MCPs التالية:
+> - `.opencode/opencode.json`: `playwright` + `semgrep` + `structurizr`
+> - `~/.config/opencode/opencode.jsonc`: `playwright` + `semgrep`
+>
+> **تصحيح نظامي (SCP-2026-07-31-001):** الأقسام 3.2 (API Testing MCP) و 3.3 (Git/GitHub MCP) و 3.4 (Database Read-Only MCP) كانت تسرد MCPs **غير مفعلة فعلياً** في أي تكوين — نُقلت إلى قائمة §4 المؤجلة أو توثيقها كأدوات CLI حسب الحاجة. لا يفقد النظام أي وظيفة من هذا التصحيح.
+
+### 3.1 Playwright / Browser Automation MCP
+
+| البند | القيمة |
+|---|---|
+| **الاسم** | Playwright / Browser Automation |
+| **الغرض** | اختبار الواجهات، Smoke Tests، E2E، مراجعة Phase 6، QA في Phase 7 |
+| **الصلاحية الافتراضية** | `BROWSER_READ` (قراءة + Screenshots + تنقل) |
+| **مسموح به لـ** | ✅ جميع العملاء — Coding Agents, Auditor, QA Agent, Design Reviewer, UI Designer |
+| **يقرأ** | ✅ روابط التطبيق، حالة UI، screenshots |
+| **يكتب** | ❌ لا يعدل كودًا |
+| **يعدّل بيانات** | ❌ ممنوع |
+| **ينشر** | ❌ ممنوع |
+| **التبعية** | يجب أن يكون التطبيق قيد التشغيل محليًا أو في بيئة اختبارية |
+
+**شروط الاستخدام:**
+- **يُستخدم فقط في بيئة Development/Staging** — ممنوع على Production.
+- **متاح مبدئياً** لجميع العملاء دون موافقة Tera (تشغيل التطبيق لأول مرة يحتاج تأكيد أنه Dev).
+- لا يرسل بيانات حساسة في الاختبارات.
+- أي screenshot يُستخدم كدليل بصري في Handback أو تقارير المراجعة.
+- **ممنوع**: تعديل الكود، تغيير بيانات، نشر.
+- **فُعّل عبر:** MCP Server (`@playwright/mcp`) + CLI (`@playwright/cli`) — راجع SCP-107.
+
+---
+
+### 3.2 Semgrep MCP
+
+| البند | القيمة |
+|---|---|
+| **الاسم** | Semgrep Static Analysis |
+| **الغرض** | فحص كود ثابت (أخطاء برمجية، ثغرات، أنماط خطرة) |
+| **الصلاحية الافتراضية** | `READ_ONLY` — يفحص ولا يعدّل |
+| **مسموح به لـ** | ✅ جميع العملاء — عبر MCP (`semgrep_scan_directory`) وعبر CLI (`semgrep --config=tera-system/semgrep-rules/`) |
+| **القواعد** | قواعد Tera المخصصة في `tera-system/semgrep-rules/` |
+
+**شروط الاستخدام:**
+- يستخدم مع قواعد Tera (`semgrep-rules/`) أو القواعد العامة عند الحاجة.
+- نتائج الفحص تُسجل في المهمة/التقرير — لا تعديل للكود.
+- **فُعّل عبر:** MCP Server (`semgrep mcp` في `opencode.jsonc` + `mcp-server-semgrep` في `.opencode/opencode.json`) + CLI.
+
+---
+
+### 3.3 أدوات CLI في البوابات (وليست MCPs)
+
+بعض الأدوات الحرجة تعمل **كأوامر CLI داخل Quality Gates** بدل MCPs — وهذا مقصود:
+- لا استهلاك توكنز دائم في السياق.
+- تُشغَّل في اللحظة المحددة بقاعدة واضحة.
+- النتيجة: `exit code` + تقرير محفوظ + عتبات في `QUALITY_GATE_THRESHOLDS.md`.
+
+| الأداة | الأمر | البوابة |
+|---|---|---|
+| **Semgrep (CLI)** | `semgrep --config=tera-system/semgrep-rules/ --metrics=off <files>` | SEMGREP_SANITY_CHECK — كل مهمة كود |
+| **Trivy** | `trivy fs --scanners vuln,secret,misconfig .` | Trivy Dependency & Secrets Check — قبل التسليم |
+| **Gitleaks** | `gitleaks git . --redact --no-banner` | Gitleaks Git History Secrets Check — قبل التسليم (SCP-2026-07-31-001) |
+
+**قاعدة:** لا تُحوَّل أدوات البوابات الحاسمة إلى MCP إلا إذا احتاج العميل الاستعلام التفاعلي من نتائجها لحظياً.
+
+---
+
+### 3.4 مكتبات الجودة في المشاريع (وليست MCPs)
+
+| الأداة | الشكل | الاستخدام |
+|---|---|---|
+| **axe-core** (`@axe-core/playwright`) | devDependency داخل اختبارات Playwright | فحص Accessibility للواجهات الجديدة (SCP-2026-07-31-001) |
+| **Testcontainers** (NuGet / npm) | مكتبة اختبارات | اختبارات تكاملية مع خدمات حقيقية (PostgreSQL/Redis/SQL Server) داخل Docker (SCP-2026-07-31-001) |
+| **Bruno** (`@usebruno/cli`) | CLI | توثيق واختبار APIs عبر Collections |
+
+---
+
+### 3.5 Structurizr (C4 Modeling) MCP
+
+| البند | القيمة |
+|---|---|
+| **الاسم** | Structurizr C4 Architecture Modeling |
+| **الغرض** | نمذجة البنية المعمارية (C4 Model) عبر Structurizr DSL — توليد Context, Container, Component diagrams |
+| **المصدر** | `colincoleman/structurizr-mcp` (GitHub) — مثبت محلياً في `structurizr-mcp/` |
+| **الصلاحية الافتراضية** | `READ_WRITE` — يقرأ ويكتب ملفات `.dsl` فقط |
+| **المستعمل** | `ApplicationBlueprintAgent` (مُهندس) — لأغراض blueprinting + solution preparation (phases 1–4, SCP-2026-07-28-118) |
+| **يقرأ** | ✅ ملفات Structurizr DSL (`.dsl`) — النماذج المعمارية النصية |
+| **يكتب** | ✅ ملفات `.dsl` جديدة — يعدّل النماذج القائمة بعد موافقة |
+| **يولّد** | ✅ Diagrams (PNG/SVG) من DSL — للتوثيق الداخلي |
+| **يعدّل كود تطبيق** | ❌ ممنوع تماماً |
+| **ينشر diagrams لخارج** | ❌ ممنوع — للتوثيق الداخلي فقط |
+
+**✅ الوضع الحالي:** تم تثبيت `colincoleman/structurizr-mcp` (Python, uv) من GitHub إلى `structurizr-mcp/` في جذر المشروع. MCP مسجل في `opencode.json`.
+
+**⚠️ يتطلب Docker قيد التشغيل** للتصدير والتحقق:
+- **تصدير diagrams** إلى SVG/PNG
+- **معاينة النماذج** عبر http://localhost:8081
+- **التحقق من DSL** عبر Structurizr CLI داخل Docker
+
+**تشغيل الحاوية (مرة واحدة) — من جذر المستودع:**
+```bash
+docker run -d --rm -p 8081:8080 -v "%CD%\architecture:/usr/local/structurizr" structurizr/structurizr local
+```
+> **ملاحظة:** المسار نسبي من جذر المستودع (يعمل على أي جهاز). بديل PowerShell: `-v "$PWD\architecture:/usr/local/structurizr"`
+> **ملاحظة:** المنفذ 8081 لأن 8080 مشغول بـ ERPNext. المعاينة عبر http://localhost:8081
+
+بدون Docker: الـ MCP يعمل لكنه يقدّم فقط قراءة/كتابة ملفات `.dsl` — لن يعمل validate ولا export diagrams.
+
+**شروط الاستخدام:**
+- **المصدر الأساسي هو DSL النصي** — ملف `.dsl` هو مصدر الحقيقة (version-controlled). الـ diagrams هي مخرجات مشتقة.
+- **Docker مطلوب للـ diagrams البصرية** — بدونه، الـ DSL النصي هو المخرج الوحيد.
+- **يُستخدم فقط لـ ApplicationBlueprintAgent** — في سياق blueprinting وليس لكتابة كود.
+- **صلاحية الكتابة:** فقط لملفات `.dsl` — لا يعدّل أي ملف كود تطبيق.
+- **التسجيل:** أي diagram يُولّد يسجل في `project-preparation/BLUEPRINT_DECISION_CANDIDATES.md`.
+- **عدم المشاركة الخارجية:** الـ diagrams للتوثيق الداخلي فقط.
+
+---
+
+## 4. MCPs المؤجلة (ليست الآن)
+
+| الأداة | السبب | وقت التفعيل المقترح |
+|---|---|---|
+| **API Testing MCP** | متاحة حالياً عبر curl/webfetch + Bruno CLI — لا حاجة لخادم MCP. | عند الحاجة لاستعلام تفاعلي متكرر من العملاء من نتائج API مباشرة. |
+| **Git / GitHub MCP** | Git CLI الحالية تغطي القراءة والكتابة (بموافقة). | عند اعتماد GitHub سير عمل PRs بكثافة. |
+| **Database Read-Only MCP** | الوصول الحالي عبر CLI/استعلامات مصرّح بها. | عند وجود مشروع يتطلب فحص قواعد بيانات متكرراً من عدة عملاء. |
+| **Figma MCP** | البروتوكول الحالي FIGMA_INTEGRATION.md + UIVisualDesignerAgent يكفي الآن. MCP Figma سيضيف تعقيدًا قبل الحاجة الفعلية. | عند وجود مشروع يعتمد على Figma بانتظام وتتعدد مهام التصميم. |
+| **Deployment / Cloud MCPs** | النشر ليس محورًا حاليًا. DevOpsDeploymentAgent الحالي يغطي التخطيط والتحضير. | عند وجود مشروع يتطلب نشر فعلي متكرر CI/CD. |
+| **Production DB Write Tools** | خطرة جدًا وتحتاج ضوابط أمنية متقدمة. | عند وجود مشروع يتطلب وصول كتابي إلى قاعدة بيانات Production مع خطة rollback موثقة. |
+| **Email / Calendar MCPs** | غير ضرورية حاليًا لمنظومة Tera. | عند الحاجة لجدولة مواعيد أو إرسال اتصالات آلية. |
+| **Drive / Document MCPs** | يمكن إدارة المستندات عبر الملفات المحلية حاليًا. | عند العمل مع عملاء يستخدمون Google Docs أو SharePoint كمصدر أساسي. |
+| **Monitoring / Logging MCPs** | غير ضرورية قبل وجود تطبيق قيد التشغيل الفعلي. | عند وجود تطبيق في Production يحتاج مراقبة. |
+| **SonarQube** | بوابة جودة مركزية قوية لكنها تحتاج خادماً + CI. Semgrep + Trivy + Gitleaks تغطي احتياجنا الحالي. | عند اعتماد CI/CD رسمي أو مشروع كبير يحتاج قياساً مستمراً للتغطية/التكرار. |
+| **Sentry MCP** | مراقبة الأخطاء — مفيدة فقط عند وجود تطبيق في Production. حالياً Sentry SDK قاعدة FLAG في التسليم. | عند أول تطبيق Production فعلي. |
+| **k6** | اختبارات أداء/ضغط — لا يوجد اشتراط أداء في عتبات القبول حالياً. | عند أول متطلب أداء (p95, concurrency) في تسليم عميل. |
+
+---
+
+## 5. قواعد استخدام MCPs
+
+### 5.1 القواعد الأساسية
+
+| القاعدة | الشرح |
+|---|---|
+| **Trigger واضح** | أي استخدام MCP يجب أن يكون بناءً على حاجة محددة في `TASK-ID` أو قرار من Tera |
+| **الصلاحية الافتراضية Read-Only** | القراءة هي الأصل. الكتابة استثناء. |
+| **لا أسرار Production** | يمنع استخدام أي أداة مع بيانات أو مفاتيح Production دون عزل تام وإذن صريح |
+| **تسجيل النتائج** | نتيجة أي MCP تُسجل في الملفات الرسمية (`project-control/` المناسب) |
+| **لا تعديل مباشر** | MCP Write يحتاج موافقة صريحة من Tera (أو المستخدم للحالات الحرجة) |
+| **DB Read-Only فقط** | أي MCP Database يكون Read-Only افتراضيًا ولا يُعدّل البيانات |
+| **بيئة اختبارية** | الأدوات تستخدم في بيئة Development أو Staging أولاً |
+| **إبلاغ Tera** | إذا وجدت الأداة مشكلة، تُبلغ Tera بدل اتخاذ قرار بنفسها |
+
+### 5.2 قواعد لكل MCP
+
+| MCP | Read | Write (مع إذن) | Test | Production Access |
+|---|---|---|---|---|
+| Playwright | ✅ UI readable فقط | ❌ | ✅ Smoke/E2E | ❌ ممنوع |
+| Semgrep | ✅ كود (فحص) | ❌ | ✅ Static Analysis | ❌ (لا يحتاج) |
+| Structurizr | ✅ ملفات `.dsl` | ✅ `.dsl` فقط | ✅ Validate/Export (Docker) | ❌ |
+
+> **الأدوات التالية لم تعد MCPs مفعلة** (تصحيح SCP-2026-07-31-001): API Testing (تتم عبر curl/webfetch/Bruno CLI)، Git/GitHub (يتم عبر أدوات Git CLI الموجودة)، Database Read-Only (يتم عبر CLI/استعلامات عند الحاجة المصرّح بها). هذه القدرات **متاحة عبر الأدوات القياسية** دون الحاجة لخوادم MCP إضافية.
+
+---
+
+## 6. ماذا تفعل Tera عند استخدام MCP؟
+
+### 6.1 قبل الاستخدام
+
+1. يحدد Tera الحاجة والمبرر.
+2. يحدد الـ MCP المطلوب.
+3. يحدد الصلاحية (Read / Test / Write with approval).
+4. يحدد البيئة (Development / Staging / Production بإذن).
+5. يسجل القرار في `TASK-ID`.
+
+### 6.2 بعد الاستخدام
+
+1. يراجع Tera نتائج الأداة.
+2. يسجل النتائج في `PROJECT_ACTIVITY_LOG.md`.
+3. إذا كانت النتائج تؤثر على قرارات: يُسجل في `DECISIONS_LOG.md`.
+4. إذا كانت النتائج تؤثر على حالة المهمة: يُحدّث `TASK-ID`.
+
+### 6.3 في حال وجود خطأ أو خرق
+
+```
+إذا تسبب MCP في:
+- تغيير غير مرغوب
+- تعديل بيانات خطأ
+- كشف secret
+- تعطيل خدمة
+
+تتخذ Tera الإجراءات التالية:
+1. توقف الأداة فورًا.
+2. تبلغ المستخدم فورًا.
+3. تسجل الحادثة في ISSUES_AND_GAPS.md.
+4. تطبق Emergency Response حسب التصنيف (Yellow/Orange/Red/Black).
+5. لا تستمر حتى حسم الموقف.
+```
+
+---
+
+## 7. خريطة طريق الأدوات المستقبلية
+
+| المرحلة | الأدوات المضافة | ملاحظة |
+|---|---|---|
+| **حاليًا (2026-07-31)** | MCPs: Playwright, Semgrep, Structurizr — CLI Gates: Semgrep, Trivy, Gitleaks — مكتبات: axe-core, Testcontainers, Bruno — **CI Pipeline: `.github/workflows/tera-ci.yml` (SCP-2026-07-31-002)** | محدودة ومدروسة + خط إصدار آلي |
+| **بعد مشروع متوسط** | Docker/DevOps MCP (إذا بدأ نشر) | فقط إذا تطلب المشروع |
+| **بعد مشروع ERP** | Data Migration MCP (إذا تطلب ERP) | فقط إذا كان هناك ترحيل بيانات |
+| **عند اعتماد Figma** | Figma MCP (للقراءة) | فقط بعد أول مشروع Figma متكرر |
+| **عند وجود Production** | Sentry MCP (قراءة/تحليل فقط)، Monitoring MCP | فقط بعد تشغيل التطبيق فعليًا |
+| **عند اعتماد CI/CD** | SonarQube، k6 (عند متطلبات الأداء) | بعد استقرار أول إصدار رسمي |
+| **بعد استقرار أول إصدار** | dependency-cruiser/NetArchTest، Schemathesis، Stryker (للمنطق الحرج) | عبر بوابة Rollout — مشروع تجريبي واحد ثم قياس ثم تفعيل عام |
+| **عند الحاجة** | Renovate (تحديث التبعيات)، OWASP ZAP (اختبار ديناميكي) | تُقيَّم عند أول حاجة فعلية |
+
+> **تجميد الأدوات (SCP-2026-07-31-002):** لا تُضاف أدوات جديدة قبل استقرار أول إصدار رسمي. كل إضافة مستقبلية تمر ببوابة Rollout: مشروع تجريبي واحد ← قياس ← تفعيل عام.
+
+---
+
+## 8. الملخص — قاعدة الأدوات الذهبية
+
+> **الأداة تخدم الـ Agent، والـ Agent يخدم Tera.**
+>
+> لا MCP بدون Trigger.
+> لا Write بدون موافقة.
+> لا Production بدون خطة.
+> لا سر بدون تغطية.

package/core/tera-system/TeraApplicationQuestionBank.md

@@ -0,0 +1,362 @@
+# Tera Application Question Bank
+
+## Purpose
+
+This is the reference question bank for the **Client Discovery and Smart Interview** process — a two-stage approach that first explores the client's idea through open conversation, then follows with adaptive structured questioning across all domains.
+
+Tera does not ask all questions. Tera selects the right questions at the right time based on previous answers, and always starts with open listening before any structured questioning.
+
+## How to use this bank
+
+1. **Start with Client Discovery Mode** — open listening, understanding summary, confirmation (see `TERA_RUNTIME_PROTOCOLS_CLIENT.md` Section 18).
+2. **Enter Smart Interview only if gaps remain** after the Discovery summary is confirmed.
+3. **Select questions based on gaps** — not all domains, not all questions.
+4. **When the client doesn't know** — propose a default, document as `Assumption`, do not treat as final decision.
+5. **Small projects: 10–15 questions. Medium: 20–35. Complex: deeper per domain.**
+
+## Operational mapping to TCEA 13-domain framework
+
+This bank remains a **question source**, not a completeness contract by itself.
+
+**التعريف الرسمي والترقيم المعتمد للمجالات موجود في المصدر الرسمي:**
+`tera-system/client-helpers/tera-client-engagement-discovery-domains.md`
+
+**ملاحظة حول الترقيم:** الترقيم المستخدم حالياً في أسئلة هذا الملف (Q1.x, Q2.x, ...) مبني على ترقيم سابق. للترقيم المعتمد الحالي، راجع `discovery-domains.md`. أسئلة هذا الملف سيتم إعادة ترقيمها لتتوافق مع المصدر الرسمي في تحديث لاحق.
+
+**Rule:**
+
+```text
+The question bank helps TCEA ask.
+The Discovery Coverage Summary proves TCEA covered.
+```
+
+### Practical mapping guidance
+
+- Current Domain 1 supports: Business Context & Value
+- Current Domain 2 supports: Users & Roles, Workflow & Operations, Scope & MVP, Notifications, Screens & UX
+- Current Domain 3 supports: Data & Content, Reports & Dashboards
+- Current Domain 4 supports: Integrations & APIs, Technical / Hosting / Compliance
+- Current Domain 5 supports: Design & Branding, Screens & UX
+- Current Domain 6 supports: Security & Audit
+- Current Domain 7 supports: Technical / Hosting / Operational follow-up
+
+Acceptance, commercials, warranty, delivery assumptions, and approval-readiness questions may require TCEA to add consulting/commercial questions beyond this bank when needed.
+
+## Assumption Handling
+
+When the client cannot answer a question, use this pattern:
+
+### Response format
+
+```
+إذا لم تكن متأكدًا، أقترح الافتراض التالي:
+- الخيار الموصى به: [الخيار]
+- السبب: [شرح مختصر]
+- الحالة: Assumption — يحتاج تأكيد لاحق
+```
+
+### Documentation format
+
+Record all assumptions in a table (inside `project-inputs/` or in a separate file for medium/large projects):
+
+```text
+| المجال | السؤال | افتراض تيرا | الحالة | يحتاج مراجعة قبل |
+|--------|--------|-------------|--------|------------------|
+| تقني | Web/Mobile | Web App | يحتاج تأكيد | التوقيع على النطاق |
+| صلاحيات | عدد الأدوار | Admin + User | يحتاج تأكيد | التنفيذ |
+```
+
+### Classification
+
+| الحالة | المعنى |
+|--------|--------|
+| `مؤكد` | العميل أجاب بوضوح |
+| `يحتاج تأكيد` | اقتراح Tera — لم يؤكده العميل بعد |
+| `مؤجل` | العميل قال "ربما لاحقاً" |
+| `غير محدد حاليًا` | لم يُطرح السؤال بعد أو العميل لم يقرر |
+
+## 🔍 Research Triggers
+
+Throughout the Question Bank, some questions are marked with `🔍 Research recommended`. This means:
+
+When the client's answer to this question is unclear, uncertain, or the client defers to Tera:
+1. **Search first** before proposing a default.
+2. Present findings with sources.
+3. Let the client choose based on research.
+
+### When research is unavailable or inconclusive
+- Document the limitation clearly.
+- Present as `Unknown — needs client decision` or `Inconclusive research — proceed with caution`.
+- Never present an unresearched opinion as a reliable recommendation.
+
+### Common research triggers by domain
+
+| Domain | Topics likely needing research |
+|--------|-------------------------------|
+| Administrative | Competitor analysis, market standards |
+| Functional | Industry-specific workflows, compliance processes |
+| Data/Reporting | Standard report formats, data regulations |
+| Technical | 🔍 Best libraries, frameworks, APIs, hosting providers |
+| Design/UX | 🔍 Design trends, accessibility standards, UI patterns |
+| Security | 🔍 Regulatory requirements, security standards |
+| Operational | 🔍 Hosting providers, DevOps tools, pricing |
+
+### Quick reference: When to search vs when to use judgment
+
+| Scenario | Action |
+|---|---|
+| Client: "أي بوابة دفع تنصح؟" | 🔍 **Search** — compare options with sources |
+| Client: "كم عدد المستخدمين؟ 5 فقط" | Use judgment — clear answer |
+| Client: "ما أفضل قاعدة بيانات؟" | 🔍 **Search** — depends on stack, volume, budget |
+| Client: "التطبيق بلاريل" | Use judgment — clear technology |
+| Client: "هل أحتاج ERP؟" | 🔍 **Search** — depends on business processes |
+| Client: "موظفين 10، بدون صلاحيات" | Use judgment — simple scenario |
+| Client: "أحتاج استضافة في السعودية" | 🔍 **Search** — local providers, regulations |
+| Client: "ما رأيك في React؟" | Use judgment — well-known technology |
+
+---
+
+## Domain 1: Administrative / Business Context
+
+*Understanding the client, the problem, and the business goal.*
+
+### Essential
+- Q1.1: What is the client name? (if external)
+- Q1.2: Is the client an individual, company, or organization?
+- Q1.3: What is the client's business domain?
+- Q1.4: What problem does this application solve?
+- Q1.5: Who benefits from this application?
+- Q1.6: Is this a new product or replacing an existing system?
+- Q1.7: Is this a paid service, internal tool, or public benefit?
+- Q1.8: Is there a deadline or time constraint?
+
+### Deep dive (when needed)
+- Q1.9: What is the expected number of users at launch? After 6 months?
+- Q1.10: Is there a budget range or cost sensitivity?
+- Q1.11: Are there competitors or similar apps the client knows?
+- Q1.12: Does the client have a business model or monetization plan?
+- Q1.13: Who are the decision makers and stakeholders?
+- Q1.14: What success metrics matter most? (users, revenue, adoption, etc.)
+
+---
+
+## Domain 2: Functional / Operational
+
+*Understanding users, roles, workflows, and feature expectations.*
+
+### Essential
+- Q2.1: Who will use this application? (list user types)
+- Q2.2: What are the 3 most important things each user type does?
+- Q2.3: Do users have different permission levels or roles?
+- Q2.4: Is there a registration / login requirement?
+- Q2.5: What is the main workflow from start to finish?
+- Q2.6: Does the application need to send notifications? (email, SMS, in-app)
+- Q2.7: Does the application need to support multiple languages? Which?
+
+### Deep dive (when needed)
+- Q2.8: Describe each workflow step-by-step: trigger, actions, decisions, outcomes.
+- Q2.9: Are there approval workflows? (e.g., manager approves expense)
+- Q2.10: Does the application need a search or filter feature?
+- Q2.11: Is there a dashboard or analytics view?
+- Q2.12: Does the application manage inventory, stock, or resources?
+- Q2.13: Are there scheduled or automated tasks? (cron, batch jobs)
+- Q2.14: Does the application need a mobile-responsive version?
+- Q2.15: Are there offline use cases?
+- Q2.16: Describe any exceptional or edge-case scenarios.
+
+---
+
+## Domain 3: Data and Reporting
+
+*Understanding data inputs, outputs, storage, and reporting.*
+
+### Essential
+- Q3.1: What data does the application collect or manage?
+- Q3.2: What are the main data entities? (e.g., users, orders, products)
+- Q3.3: Does the application need to import data from external sources?
+- Q3.4: Does the application need to export data? In what format? (PDF, Excel, CSV)
+- Q3.5: Are there required reports or summaries?
+
+### Deep dive (when needed)
+- Q3.6: What is the expected data volume? (records per day/month)
+- Q3.7: How long should data be retained?
+- Q3.8: Are there data archival or deletion requirements?
+- Q3.9: Are there real-time data requirements?
+- Q3.10: Does the application need to generate invoices, receipts, or financial documents?
+- Q3.11: Are there data validation rules or business calculations?
+- Q3.12: Does the client need a data backup or recovery plan?
+- Q3.13: Are there complex reporting queries or cross-table aggregations?
+
+---
+
+## Domain 3b: Content & Messaging (Content-Heavy only — SCP-2026-08-15-016)
+
+*Understanding what the client wants to actually SAY in each screen/page — activated only when Content Type = User-Facing Content / Mixed (موقع، صفحة هبوط، تسويق، محتوى).*
+
+### Essential (Content-Heavy only)
+- Q3b.1: Content Type? (Application Data / User-Facing Content / Mixed)
+- Q3b.2: ما الغرض من هذه الشاشة/الصفحة؟ (Purpose)
+- Q3b.3: لمن هذه الشاشة؟ (Audience)
+- Q3b.4: ما الرسالة الأساسية التي يجب أن يفهمها الزائر؟ (Primary Message)
+- Q3b.5: ما المحتوى المطلوب ظهوره؟ (Required Content Blocks)
+- Q3b.6: ما CTA المطلوب (إن وُجد)؟ وإلى أين؟
+- Q3b.7: ما المحتوى الممنوع/الحساس؟ (Forbidden — راجع D-015)
+- Q3b.8: ما Claims المسموح ادعاؤها؟ (من قرارات Discovery — أرقام موثقة في مصادر الحقيقة فقط)
+- Q3b.9: ما الأولويات بين الرسائل في هذه الشاشة؟ (Content Priorities)
+- Q3b.10: من Content Owner / Source المعتمد؟
+
+> **التفعيل:** تُستخدم هذه الأسئلة ضمن **Content Confirmation Gate** (بروتوكول التحضير §7.5) بعد إنتاج `07_SCREENS_AND_UI_STRUCTURE.md` وقبل التصميم النهائي. التطبيقات القياسية (Application Data فقط) لا تستخدمها — Anti-Bloat.
+
+---
+
+## Domain 4: Technical
+
+*Understanding technology stack, integrations, and environment.*
+
+### Essential
+- Q4.1: Is the technology stack already decided? What is it?
+- Q4.2: What type of application? (web, mobile, desktop, hybrid)
+- Q4.3: What database is required? (if any)
+- Q4.4: 🔍 Are there external integrations or APIs? (payment gateways, third-party services, legacy systems)
+- Q4.5: 🔍 What is the target environment? (cloud, on-premise, hybrid)
+- Q4.6: Are there any forbidden technologies or libraries?
+
+### Deep dive (when needed)
+- Q4.7: Is there an existing codebase, database, or design system?
+- Q4.8: 🔍 Does the application need to be containerized? (Docker, Kubernetes)
+- Q4.9: 🔍 Are there performance or scalability requirements?
+- Q4.10: What is the expected uptime or SLA?
+- Q4.11: 🔍 Does the application need CI/CD pipeline?
+- Q4.12: 🔍 Are there specific hosting providers preferred or required?
+- Q4.13: Does the client prefer specific frameworks or languages?
+- Q4.14: Are there API versioning requirements?
+- Q4.15: Does the application need webhooks or event-driven architecture?
+- Q4.16: Is there a dev/test/prod environment requirement?
+
+### Mobile-specific (when application type = Mobile)
+- Q4.17: Is the target platform Android, iOS, or both?
+- Q4.18: 🔍 Does the application need offline mode? What data should be available offline?
+- Q4.19: 🔍 Does the application need push notifications? (FCM, local, both)
+- Q4.20: Does the application need device hardware? (camera, GPS, fingerprint, NFC, Bluetooth, barcode scanner)
+- Q4.21: What is the minimum supported Android/iOS version?
+- Q4.22: Are there specific device classes to support? (phones only, tablets, foldables)
+- Q4.23: Will the app be published on Google Play, Apple App Store, or both?
+- Q4.24: Does the client have an Apple Developer account ($99/year)?
+- Q4.25: 🔍 Does the application need background execution? (location tracking, sync, music playback)
+- Q4.26: 🔍 Are there specific accessibility requirements? (screen readers, large fonts, high contrast)
+- Q4.27: 🔍 Does the application need cross-platform framework? (Flutter vs React Native vs native)
+- Q4.28: Does the client have existing APIs or will new APIs be built?
+- Q4.29: 🔍 Does the application need deep linking or universal links?
+- Q4.30: Is there a requirement for app widgets or home screen widgets?
+
+---
+
+## Domain 5: Design and UX
+
+*Understanding visual identity, user experience, and design references.*
+
+### Essential
+- Q5.1: Does the client have a logo, brand colors, or existing style guide?
+- Q5.2: 🔍 Are there reference applications or websites the client likes?
+- Q5.3: Are there examples the client explicitly dislikes?
+- Q5.4: 🔍 Does the client prefer a specific design style? (modern, minimal, corporate, playful)
+- Q5.5: Does the application need to be RTL-friendly? (Arabic, Hebrew)
+- Q5.6: Does the client have existing UI components or a design system?
+
+### Deep dive (when needed)
+- Q5.7: Are there specific color palettes or hex codes?
+- Q5.8: What typography or fonts are preferred?
+- Q5.9: Are there icons or illustrations to use?
+- Q5.10: 🔍 Does the client want a mobile-first design?
+- Q5.11: 🔍 Are there accessibility requirements? (WCAG, screen readers)
+- Q5.12: Does the client have wireframes, mockups, or Figma designs?
+- Q5.13: Describe the desired layout or navigation style. (sidebar, top nav, tabbed)
+- Q5.14: Are there form-heavy screens or content-heavy screens?
+- Q5.15: What is the tone of the interface? (professional, casual, educational)
+- Q5.16: Should Tera propose 2-3 design directions using internal kits or `getdesign.md` references?
+- Q5.17: Does the client approve using an external DESIGN.md as inspiration, with project-specific branding overrides?
+
+---
+
+## Domain 6: Security and Permissions
+
+*Understanding authentication, authorization, data sensitivity, and compliance.*
+
+### Essential
+- Q6.1: 🔍 Does the application need user authentication? (email/password, SSO, OAuth, social login)
+- Q6.2: Are there different user roles with different permissions?
+- Q6.3: 🔍 Does the application handle sensitive personal data?
+- Q6.4: 🔍 Is there a compliance requirement? (GDPR, HIPAA, SOC2, local regulations)
+- Q6.5: Does the application need audit logs or activity tracking?
+- Q6.6: 🔍 Are there file uploads or document storage? What type?
+
+### Deep dive (when needed)
+- Q6.7: What is the authentication method? (JWT, session-based, OAuth2, SAML)
+- Q6.8: Are there multi-factor authentication requirements?
+- Q6.9: Describe the role hierarchy and permission model.
+- Q6.10: Are there IP restrictions or geographic restrictions?
+- Q6.11: Does the application need encryption at rest and in transit?
+- Q6.12: Are there third-party identity providers? (Azure AD, Okta, Google)
+- Q6.13: Are there data anonymization or pseudonymization needs?
+- Q6.14: What is the data classification level? (public, internal, confidential, restricted)
+- Q6.15: Are there security penetration testing requirements?
+
+---
+
+## Domain 7: Operational and Deployment
+
+*Understanding hosting, deployment, maintenance, and delivery.*
+
+### Essential
+- Q7.1: 🔍 Where will the application be hosted? (cloud provider, on-premise, hybrid)
+- Q7.2: Who will maintain the application after delivery?
+- Q7.3: Is there a domain name or SSL certificate already available?
+- Q7.4: 🔍 Are there email service requirements? (transactional emails, notifications)
+- Q7.5: What is the expected timeline for the first release?
+
+### Deep dive (when needed)
+- Q7.6: Is there an IT team that will manage deployment?
+- Q7.7: Are there specific DevOps or infrastructure tools in use?
+- Q7.8: Does the application need monitoring and alerting? (errors, performance, uptime)
+- Q7.9: Are there backup and disaster recovery requirements?
+- Q7.10: Is there a maintenance or support period after delivery?
+- Q7.11: Does the application need a custom domain or subdomain?
+- Q7.12: What is the deployment frequency expectation?
+- Q7.13: Are there API rate limiting or throttling requirements?
+- Q7.14: Does the client need a staging or UAT environment?
+- Q7.15: Are there specific logging or observability requirements?
+
+---
+
+## After Questions: Suggestions and Improvements Phase
+
+Once all relevant domains have been covered and Tera has a complete picture, proceed to:
+
+1. **Summarize understanding** — Confirm with the user/client.
+2. **Identify gaps** — Any area that still needs clarification.
+3. **Propose improvements** — Tera may suggest:
+   - Features that improve the core goal
+   - Technologies that fit the requirements
+   - Simplifications or scope reductions
+   - Deferrals for non-essential items
+4. **Classify each suggestion** as:
+   - `Recommended — Include now`
+   - `Recommended — Consider for later phase`
+   - `Informational — For awareness only`
+   - `Deferred — Not needed for MVP`
+   - `Out of scope — Does not align with goals`
+5. **Document all suggestions separately** from confirmed client requirements.
+6. **Final confirmation** before moving to formal preparation.
+
+---
+
+## Usage Rules
+
+1. **Tera does not ask all questions.** Select the essential ones first, then deep-dive only in domains that need it.
+2. **Start with Domain 1 (Administrative), Domain 2 (Functional), and Domain 4 (Technical) essentials.** These give the core picture.
+3. **Analyze after each batch.** Identify gaps, dependencies, and unexpected areas before choosing the next batch.
+4. **Group questions in small batches.** 4-7 questions per round is comfortable.
+5. **Document answers immediately** in `project-inputs/` files.
+6. **After the interview is complete**, transition to the Suggestions and Improvements phase.
+7. **For external clients**, Majed acts as intermediary. Tera phrases questions for forwarding.
+8. **Suggested improvements must be clearly separated** from confirmed requirements.