@tera-system/core 0.1.0

package/core/tera-system/profiles/phaser-react-node.md

@@ -0,0 +1,302 @@
+# Technology Profile: phaser-react-node
+
+> **Status:** ✅ **Approved** — معتمد من Majed (2026-07-29)
+> **تاريخ:** 2026-07-29
+> **المشروع المستهدف:** مشروع تجريبي سابق — لعبة Web 2D (أُزيل من clients/ 2026-08-15)
+> **Source:** `clients/CLIENT-NAMAAGAMES/applications/APP-FARM-WEB/project-preparation/08_TECHNICAL_ARCHITECTURE.md`
+> **ملاحظة (2026-08-15):** المشروع المصدر كان تجريبياً وأُزيل من `clients/` — المسار أعلاه إسناد تاريخي فقط، والمحتوى الأصلي محفوظ في Git history. البروفايل نفسه ساري المفعول كنمط تقني معتمد.
+
+---
+
+## 1. Profile Identity
+
+| البند | القيمة |
+|-------|--------|
+| Profile ID | `phaser-react-node` |
+| Language | TypeScript (عبر المشروع كاملاً) |
+| Game Engine | Phaser 4 (via `phaserjs/template-react-ts`) |
+| UI Framework | React 18+ + TypeScript |
+| State Management | Zustand + TanStack Query |
+| Backend | Node.js + TypeScript (Express.js مُوصى به) |
+| Database | PostgreSQL |
+| ORM | Prisma (مُوصى به) / Drizzle |
+| Validation | Zod (مشترك بين Client و Server) |
+| Build Tool | Vite |
+| Testing | Vitest |
+| Auth | JWT (`jsonwebtoken` + `bcrypt`) |
+| API Protocol | REST |
+| Maps Editor | Tiled Map Editor (JSON → Phaser) |
+| PWA | نعم (Vite PWA plugin) |
+| Package Manager | npm |
+| Code Quality | ESLint + Prettier |
+| UI Component Library | shadcn/ui (لمكونات React) |
+| Integration Pattern | `phaserjs/template-react-ts` (Same-DOM + DOM Overlays + EventBus) |
+
+---
+
+## 2. Applicability
+
+Web Game projects باستخدام **Phaser 3** (Canvas 2D rendering) + **React UI Shell** (قوائم وقوالب فوق اللعبة) + **Node.js Backend** (REST API) + **PostgreSQL**.
+
+**نمط اللعبة:** 2D Top-Down Pixel Art — ألعاب إدارة/محاكاة/زراعة.
+
+**لا ينطبق على:**
+- ألعاب 3D (Unity, Three.js, Unreal)
+- ألعاب Isometric (زاوية مختلفة، تحتاج محرك مختلف)
+- ألعاب MOBA/MMO (تحتاج WebSockets/Real-time)
+- تطبيقات ويب بدون محرك ألعاب (استخدم `nextjs-prisma` أو `dotnet-blazor-ef`)
+
+---
+
+## 3. Default Execution Order
+
+```
+Phase 1A — Vertical Slice (2-3 months)
+  └─ 1. Scaffold: phaserjs/template-react-ts + إضافة المكتبات
+  └─ 2. Backend scaffold: Express + TypeScript + Prisma + PostgreSQL
+  └─ 3. Vertical Slice: محصول واحد (قمح) + حقل + متجر + حسابات + تجربة لعب أساسية
+
+Phase 1B — MVP Batches
+  └─ Batch 1: 5 محاصيل + حقل + نظام نمو
+  └─ Batch 2: حيوانات (2) + حظائر
+  └─ Batch 3: مصانع (2) + وصفات
+  └─ Batch 4: مخزون (Zustand + TanStack Query) + طلبات
+  └─ Batch 5: مستويات (15-20) + XP
+  └─ Batch 6: Rules Engine + مهام (20-30 قالب)
+  └─ Batch 7: توسعة أرض (2-3)
+  └─ Batch 8: Admin Panel (CRUD كامل)
+  └─ Batch 9: إشعارات داخل اللعبة
+  └─ Batch 10: Server-Authoritative كامل + Rate Limiting
+  └─ Batch 11: اختبارات + إصلاحات + توثيق
+
+Phase 2 (Post-Launch)
+  └─ دفع حقيقي، Social Login، أحداث موسمية
+```
+
+---
+
+## 4. First Task Rule
+
+**أول مهمة:** Vertical Slice Foundation — تهيئة المشروع بأكمله وتجربة زراعة محصول واحد كاملة.
+
+النطاق:
+1. استنساخ `phaserjs/template-react-ts` ← تسمية `farm-game`
+2. إضافة: `zustand`, `@tanstack/react-query`, `zod`, `react-router-dom`, `lucide-react`
+3. إنشاء Backend: `server/` مع Express + TypeScript + Prisma + PostgreSQL
+4. Prisma schema: Crop, Player, Farm, LandPlot, Field, Inventory, Item, Session
+5. بيانات أولية (Seed): محصول قمح (4 مراحل نمو، duration 60s للتطوير)
+6. Phaser Scene أساسية: FarmScene مع TileMap مبسط + حقل واحد
+7. عمليات: زراعة (POST /api/farm/plant) ← حصاد (POST /api/farm/harvest) ← تخزين
+8. React UI: تسجيل/دخول + متجر (شراء بذور قمح) + مخزون (عرض القمح)
+9. PWA: تفعيل عبر `vite-plugin-pwa`
+10. اختبار: Vitest + API test (supertest)
+
+**معيار النجاح:** اللاعب يستطيع تسجيل حساب ← شراء بذور ← زراعة ← انتظار ← حصاد ← رؤية القمح في المخزون.
+
+---
+
+## 5. Scaffold Rules
+
+### Phaser + React Client
+```bash
+git clone https://github.com/phaserjs/template-react-ts.git farm-game
+cd farm-game
+npm install
+npm install zustand @tanstack/react-query react-router-dom zod lucide-react
+npm install -D vite-plugin-pwa
+```
+
+### Backend Server
+```bash
+mkdir server && cd server
+npm init -y
+npm install express typescript @types/node @types/express
+npm install prisma @prisma/client
+npm install jsonwebtoken bcrypt zod express-rate-limit cors
+npm install -D ts-node nodemon vitest supertest @types/jest
+npx tsc --init
+npx prisma init
+```
+
+### Shared Types
+```bash
+mkdir shared
+# shared/types/ – API contracts, game types (مشتركة مع client عبر tsconfig paths)
+```
+
+### Integration
+```bash
+# PhaserGame.tsx ← قالب من phaserjs/template-react-ts
+# EventBus.ts ← Phaser.Events.EventEmitter (4 أسطر)
+# استخدام "Same-DOM + DOM Overlays" — انظر 08_TECHNICAL_ARCHITECTURE §13
+```
+
+**معامل الأمان:**
+- لا تخزين JWT في localStorage (استخدم httpOnly cookie أو in-memory)
+- Prisma DATABASE_URL في .env (ليس في الكود)
+- CORS: تقييد بـ origin التطبيق فقط
+
+---
+
+## 6. ORM / Database Rules
+
+### Prisma Schema — الكيانات الأساسية
+
+```prisma
+// Game Data (Data-Driven)
+model Crop {
+  id          String   @id @default(cuid())
+  name        String
+  nameAr      String
+  stages      Int      // 4-5 مراحل نمو
+  durationSec Int      // وقت النمو بالثواني
+  seedCost    Int      // سعر البذور
+  sellPrice   Int      // سعر البيع
+  unlockLevel Int      // مستوى الفتح
+  spriteKey   String
+  isActive    Boolean  @default(true)
+  createdAt   DateTime @default(now())
+}
+
+model Animal { /* name, nameAr, feedConsumed, productionDuration, productType, price, unlockLevel, spriteKey */ }
+model Product { /* name, nameAr, type, sellPrice */ }
+model Recipe { /* inputProducts (JSON), outputProductId, durationSec, factoryType */ }
+model Order { /* productId, quantity, rewardCoins, rewardXp, unlockLevel, isActive */ }
+model QuestTemplate { /* name, description, objectiveType, objectiveTarget, rewards (JSON), questType, unlockLevel, isDaily */ }
+model Reward { /* type, value, quantity, probability */ }
+
+// Player Data
+model Player { /* id, email, passwordHash, createdAt, lastLoginAt */ }
+model Farm { /* id, playerId, coins, xp, level */ }
+model LandPlot { /* id, farmId, plotIndex, isUnlocked, unlockCost, unlockLevel, plotType */ }
+model Field { /* id, landPlotId, currentCrop, plantedAt, harvestAt, isReady */ }
+model Barn { /* id, landPlotId, animalType, lastFedAt, lastCollectedAt, animalCount */ }
+model Factory { /* id, landPlotId, factoryType, currentRecipe, startedAt, completedAt */ }
+model Inventory { /* id, farmId, capacity */ }
+model Item { /* id, inventoryId, itemType, itemId, quantity */ }
+model PlayerProgress { /* id, playerId, level, xp, unlockedContent (JSON) */ }
+model PlayerQuest { /* id, playerId, questTemplateId, progress, isCompleted, isClaimed, expiresAt */ }
+model Session { /* id, playerId, token, expiresAt */ }
+```
+
+### Migration Rules
+- `npx prisma migrate dev --name <name>` ← للتطوير فقط
+- `npx prisma migrate deploy` ← للإنتاج
+- `npx prisma generate` ← بعد كل تغيير في schema
+- لا تطبق migration على قاعدة بيانات إنتاج دون مراجعة
+
+### Seed Data
+```bash
+npx prisma db seed
+# prisma/seed.ts ← بيانات المحاصيل والحيوانات والمنتجات والوصفات والمهام
+```
+
+---
+
+## 7. CLI Side Effects
+
+| الأمر | التأثير |
+|-------|---------|
+| `npx prisma migrate dev` | يعدّل قاعدة البيانات |
+| `npx prisma generate` | يجدد Prisma Client |
+| `npx prisma db seed` | يُدخل البيانات الأولية |
+| `npm install <pkg>` | يضيف مكتبات |
+| `npm run dev` | يشغل خوادم التطوير (Vite + Express) |
+| `npx vitest run` | يشغل الاختبارات |
+
+---
+
+## 8. Forbidden Defaults
+
+| البند | السبب |
+|:------|:------|
+| ❌ **WebSockets / Socket.io** | تعقيد غير مبرر لـ v1. REST + TanStack Query polling كافٍ |
+| ❌ **Redux Toolkit** | TanStack Query + Zustand يغطيان كل الحالات |
+| ❌ **Physics Engine (Matter.js)** | Top-Down pixel art لا تحتاج فيزياء — يزيد حجم الحزمة |
+| ❌ **Three.js / 3D** | خارج نطاق اللعبة 2D pixel art |
+| ❌ **CSS Framework غير Tailwind** | Tailwind CSS v4 هو المعيار مع shadcn/ui |
+| ❌ **Cron / Timer خارجي** | Time Lazy Evaluation (server_timestamp + duration) — لا Cron |
+| ❌ **AI توليدي للمهام** | Rules Engine فقط — قرار العميل رقم 15 |
+| ❌ **تخزين JWT مباشر** | httpOnly cookie أو in-memory — لا localStorage |
+
+---
+
+## 9. Pre-Execution Gate Additions
+
+بالإضافة إلى `TeraPreExecutionGate.md` العام، أضف:
+
+- [ ] **Phaser config**: هل Phaser.Game config متوافقة مع حجم الشاشة المطلوب؟
+- [ ] **Prisma schema**: هل schema متوافقة مع 06_DATA_MODEL_PREPARATION.md؟
+- [ ] **Dev server**: هل Vite dev server & Express dev server يشتغلان معاً (proxy)؟
+- [ ] **Seed data**: هل البيانات الأولية (محصول واحد على الأقل) جاهزة للاختبار؟
+- [ ] **JWT secret**: هل هو متغير بيئي (وليس hardcoded)؟
+- [ ] **Asset pipeline**: هل الأصول الفنية (CC0) موجودة في مسار `client/src/game/assets/`؟
+
+---
+
+## 10. Acceptance Criteria Patterns
+
+| النوع | معيار القبول |
+|:------|:------------|
+| **Phaser Scene** | ✅ تظهر بدون أخطاء Console، التفاعل (نقر/زراعة) يعمل |
+| **Game Loop** | ✅ زراعة → انتظار → حصاد → تخزين → رؤية في المخزون |
+| **REST API** | ✅ POST/GET مع JWT → 200, بدون JWT → 401, invalid → 400 |
+| **React UI** | ✅ تعرض البيانات الصحيحة من API، Skeleton Loading، Toast, Empty States |
+| **Server-Auth** | ✅ لا يمكن تزوير طلب (coins, items, time) |
+| **PWA** | ✅ يمكن تثبيتها من المتصفح (manifest + service worker) |
+| **Test** | ✅ `vitest run` يمر بدون فشل |
+| **Rules Engine** | ✅ مهام مناسبة للمستوى، لا تكرار، جوائز من قائمة محددة |
+| **Admin Panel** | ✅ CRUD لكل كيان Game Data، تعديل أسعار/أوقات |
+
+---
+
+## 11. Technology Stack Diagram
+
+```
+┌─────────────────────────────────────────────────┐
+│                  CLIENT (Browser)                 │
+│  ┌───────────────────┐  ┌──────────────────────┐ │
+│  │  Phaser 3 Canvas   │  │   React UI Shell     │ │
+│  │  (Game Loop,       │  │   (Inventory, Shop,  │ │
+│  │   TileMap, Sprites)│  │    Quests, Admin)    │ │
+│  └─────────┬─────────┘  └──────────┬───────────┘ │
+│            └──────────┬─────────────┘             │
+│                  Zustand + TanStack Query         │
+│                       │  REST + JWT               │
+└───────────────────────┼──────────────────────────┘
+                        │
+┌───────────────────────┼──────────────────────────┐
+│              ┌────────▼────────┐                  │
+│              │  Node.js + TS   │                  │
+│              │  Express.js     │                  │
+│              │  Server-Auth    │                  │
+│              │  Rules Engine   │                  │
+│              └────────┬────────┘                  │
+│                       │ Prisma ORM                │
+│              ┌────────▼────────┐                  │
+│              │   PostgreSQL    │                  │
+│              │  (Game + Player)│                  │
+│              └─────────────────┘                  │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## 12. Agent Routing for this Profile
+
+| Task Type | Agent |
+|:----------|:------|
+| Phaser 3 game scenes, entities, systems, sprites, tilemaps, physics | `engineering-agent-phaser` |
+| React UI (functional: hooks, state, API, Zustand stores, TanStack Query) | `engineering-agent-typescript` |
+| Backend API (Express routes, middleware, Prisma, JWT, validation) | `engineering-agent-typescript` |
+| Shared types, Zod schemas, API contracts | `engineering-agent-typescript` |
+| React↔Phaser integration bridge (EventBus, state sync) | `engineering-agent-typescript` |
+| Visual UI design (Tailwind, shadcn/ui, RTL, responsive) | `ui-designer` |
+| .NET / C# | `engineering-agent-dotnet` |
+| General (fallback — no specialist matches) | `engineering-agent` |
+
+---
+
+> **Draft v1 — 2026-07-29**
+> **الحالة:** 🟡 Draft — بانتظار اعتماد Majed
+> **المصدر:** 08_TECHNICAL_ARCHITECTURE.md + PROFILES_INDEX.md + TEMPLATE.md

package/core/tera-system/profiles/react-pwa.md

@@ -0,0 +1,97 @@
+# Technology Profile: react-pwa
+
+> **الحالة:** ✅ **Approved — Active** (PREP-D-002 مسودة → PREP-D-016 تفعيل 2026-08-01)
+> **المشروع المرجعي:** مشروع تجريبي سابق (أُزيل من clients/ 2026-08-15) — PWA محلي عربي (RTL)
+> **المرجع الحاكم للمحتوى التقني:** `project-preparation/08_TECHNICAL_ARCHITECTURE.md` (Module Baseline Approved)
+
+## 1. Profile Identity
+
+- Profile ID: `react-pwa`
+- Language: TypeScript (strict)
+- Framework: React 18 + Vite (SPA)
+- Database: IndexedDB عبر مكتبة `idb`
+- ORM: لا ORM — `idb` raw فوق IndexedDB (لا Dexie إلا عند ضرورة موثقة)
+- Package Manager / CLI: npm + Vite CLI
+- Default Project Type: Web PWA (SPA) — Offline Standalone محلي
+
+## 2. Applicability
+
+يُستخدم لهذا النوع من التطبيقات:
+
+- PWA محلية (Offline Standalone) تعمل دون إنترنت بعد التثبيت.
+- تطبيقات قراءة/محتوى عربية RTL (كتاب/دليل/مرجع) ببيانات محلية IndexedDB.
+- تطبيقات بدون Backend وبدون خدمة مركزية (لا مصادقة خادم، لا مزامنة سحابية).
+- توزيع الكود: dist ثابت يُخدم عبر خادم محلي localhost أو استضافة HTTPS.
+- ⚠️ لا يُدعم فتح `index.html` مباشرة (`file://`) — PWA وService Worker يتطلبان localhost/HTTPS.
+
+## 3. Default Execution Order
+
+1. الإقلاع والبنية: Vite scaffold + TypeScript + Tailwind CSS (RTL) + React Router.
+2. طبقة التخزين: `db/` — idb schema (13 مخزناً) + ترقية الإصدار.
+3. الترخيص أولاً: WebCrypto verify (RSA-PSS 4096, SHA-256) — شاشة S-01.
+4. حزم المحتوى: تحقق التوقيع + Hash كل ملف قبل الكتابة (S-14).
+5. الوحدات الوظيفية: Reading → Search (Fuse.js + تطبيع عربي) → Bookmarks/Notes → Quizzes → Flashcards → Quick-Ref → Settings → PWA.
+6. إثباتات Technical Proofs P1–P5 تُنفَّذ **أول** قبل بناء الوحدات الكاملة (§10 في 08).
+7. البناء النهائي: dist ثابت (PWA) + فحص الحجم.
+
+## 4. First Task Rule
+
+أول مهمة تنفيذ آمنة: **إثبات تقني رقم P1/P2 (البحث العربي + عرض MD RTL)** ضمن Technical Proofs — نطاق مصغّر يثبت المخاطر التقنية الأعلى (تطبيع عربي، تخطيط RTL، عرض MD) قبل أي بناء واسع للوحدات.
+
+> لا يبدأ أي TASK-COD كامل للوحدات قبل اجتياز P1–P5 الموثق (DG-07) وإغلاق بوابات الجاهزية.
+
+## 5. Scaffold Rules
+
+- Scaffold: `npm create vite@latest <app> -- --template react-ts`.
+- إضافات مرخّصة: `tailwindcss` (v3+)، `react-router-dom`، `zustand`، `idb`، `fuse.js`، `vite-plugin-pwa`، `remark`/`rehype` (unified)، `crypto-js` غير مرخص — التحقق عبر `crypto.subtle` فقط.
+- الافتراضي الصارم: لا مكتبات UI ثقيلة (MUI/Ant)؛ التوكينز من `28_UI_UX_GUIDELINES.md` كـ CSS Variables.
+- الإعدادات: `dir="rtl"` و `lang="ar"` على الجذر؛ Tailwind مع توكينز المشروع.
+- لا يُستخدم سكربت توليد تلقائي يعدّل ملفات الحوكمة خارج نطاق المهمة.
+
+## 6. ORM / Database Rules
+
+- قاعدة البيانات: IndexedDB عبر `idb`.
+- المخازن (13) وفق `06_DATA_MODEL_PREPARATION.md` §1.3 و 08 §11 — لا إضافة/حذف بدون تحديث موثق للـ schema.
+- الترقية: `onupgradeneeded` بإصدار schema (versioned migrations) — increment فقط.
+- الاتساق: Zustand store هو المصدر الحي؛ الكتابة إلى idb عبر write-through subscription.
+- محتوى القراءة فقط (contentTree/searchIndex/quizBank/flashcards) لا يُكتب إلا أثناء تثبيت الحزمة (transaction واحد).
+- لا ORM علائقي، لا SQL، لا خادم قاعدة بيانات.
+
+## 7. CLI Side Effects
+
+أوامر تُنشئ ملفات/تُعدّل config أو state:
+
+- `npm create vite` (scaffold) — ينشئ المشروع.
+- `npm install <pkg>` — يعدّل package.json/package-lock.
+- `vite build` / `npm run build` — ينتج dist/ + precache SW.
+- `npx serve dist` / خادم static محلي — تشغيل PWA عبر localhost (لا `file://`).
+- `docker run nginx` (اختياري) — استضافة ثابتة للحزمة.
+- `node tools/tera-tool build-package` — بناء حزمة محتوى موقّعة (لدى Tera فقط، لا يُوزَّع).
+
+## 8. Forbidden Defaults
+
+- ❌ لا Backend/API خادم، لا مزامنة سحابية، لا تحديث مركزي (القيد §5 من الـ Amendment).
+- ❌ لا Runtime rebuild لحزم المحتوى في v1.
+- ❌ لا تضمين `private.pem` أو `tools/tera-tool` في نسخة العميل.
+- ❌ لا Device Binding صارم في MVP (الترخيص لكل عميل — PREP-D-013).
+- ❌ لا إلغاء ترخيص عن بعد، لا خدمة ترخيص مركزية.
+- ❌ لا مكتبات UI ثقيلة أو CSS Modules خام افتراضياً.
+- ❌ لا `file://` كطريقة تشغيل.
+
+## 9. Pre-Execution Gate Additions
+
+إضافات محددة للبوابة (مع `tera-system/TeraPreExecutionGate.md`):
+
+- [ ] المهمة ضمن نطاق ملفات Baseline معتمدة (08 وما بعدها).
+- [ ] Active Technology Profile `react-pwa` محمّل.
+- [ ] لا كتابة خارج النطاق المصرح به في المهمة.
+- [ ] إثباتات P1–P5 (إن طُبّقت) موثقة النتائج قبل بناء الوحدات الكاملة.
+- [ ] أي تغيير على المحتوى المجمد (Content Freeze v1) = Change Request أولاً.
+
+## 10. Acceptance Criteria Patterns
+
+- الواجهة تعمل RTL صحيحاً من 360px إلى 1920px دون كسر تخطيط.
+- PWA تُثبَّت وتعمل Offline (F8.1/F8.2/F8.3) عبر localhost/HTTPS.
+- البحث العربي يعيد نتائج صحيحة لتطبيع الهمزات/التشكيل/التاء المربوطة خلال < 300ms.
+- الترخيص: مفتاح صالح يفتح، منتهٍ يعرض تجديد، مرفوض يعرض رسالة — دون قفل قاسٍ.
+- كل شاشة S-01..S-14 مطابقة لـ `07_SCREENS_AND_UI_STRUCTURE.md` وتوكينز `28_UI_UX_GUIDELINES.md`.

package/core/tera-system/runtime/CLIENT_DISCOVERY_PROTOCOL.md

@@ -0,0 +1,145 @@
+# Client Discovery and Smart Interview Protocol
+
+Guide the preparation agent (ApplicationBlueprintAgent / مُهندس — SCP-2026-07-28-118) through the complete pre-intake and intake process — from first client conversation through structured questioning to confirmed understanding — before any formal preparation or implementation begins.
+
+**Process overview:**
+```text
+Client Discovery Mode → Open conversation, understanding, confirmation
+       ↓
+Project Intake Gate → Readiness check (TeraProjectIntakePolicy.md)
+       ↓
+Smart Interview (if needed) → Structured adaptive questioning
+```
+
+---
+
+## Stage 1: Client Discovery Mode
+
+This is the **first conversation** with the client. A dialogue, not a questionnaire.
+
+### Phase 0: Open Listening
+Start with a simple open question — do not interrupt or launch into structured questions. Let the client explain freely. Tera listens and notes: core idea, problem, expected users, specific requirements, constraints, technical references.
+
+### Phase 1: Understanding Summary
+After the client finishes, produce a concise summary and ask: "هل هذا فهمي صحيح؟". **Do not proceed until the client confirms or corrects the summary.**
+
+### Decision: Proceed or Discovery Continues
+- **Clear enough** → Proceed to **Project Intake Gate**
+- **Major gaps** → Proceed to **Smart Interview** (Stage 2)
+- **Client unsure** → Smart Interview, starting with essential questions
+
+---
+
+## Stage 2: Smart Interview (Structured Adaptive Questioning)
+
+Reference source: `tera-system/TeraApplicationQuestionBank.md`
+Domain structure: `tera-system/client-helpers/tera-client-engagement-discovery-domains.md`
+
+### Phase 2: Opening Round
+Start with essential questions from core domains: Business & Goals, Users Roles & Access, Data & Content. Keep to 5–7 focused questions.
+
+### Phase 3: Analysis
+After each round, determine: which domains are covered, which have gaps, any unexpected topics needing follow-up.
+
+### Phase 4: Adaptive Rounds
+Select next batch from Question Bank based on analysis. Cover biggest gaps first. Keep each batch small (3–6 questions). Alternate domains to avoid fatigue.
+
+Continue Question → Analyze → Select cycle until all relevant domains are sufficiently covered.
+
+### Phase 5: Final Summary + Confirmation
+Produce comprehensive understanding summary. Present for user confirmation. Document in `project-inputs/`.
+
+### Phase 6: Suggestions and Improvements
+After confirmed understanding, Tera may propose features, technologies, simplifications, or deferrals. Each must be classified:
+
+- `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`
+
+Suggestions must be clearly separated from confirmed requirements.
+
+### Phase 7: Proposal Generation (Client Output)
+After understanding is confirmed, generate the **Application Proposal** (template: `tera-workshop/client-templates/commercial/APPLICATION_PROPOSAL_TEMPLATE.md`). Captures: understanding, users & roles, scope (Core MVP + Out of Scope), requirements, assumptions, roadmap, approval section.
+
+Generate under `clients/.../client-approval/` for external projects, `project-inputs/` for internal. **Do not proceed to formal preparation until client approves.**
+
+---
+
+## Assumption Handling
+
+```text
+When the client does not know an answer, Tera does not stop.
+Tera proposes a reasonable default — but records it as an assumption,
+not as a final decision.
+```
+
+| Scenario | Tera's action |
+|---|---|
+| Client: "لا أعرف" | Propose suitable default with reasoning |
+| Client: "ليس الآن" | Classify as `Deferred — Future consideration` |
+| Client: "ما عندي فكرة" | Suggest common approach, flag as assumption |
+| Client: "لا يوجد وقت" | Propose, document as `Recommended default — needs confirmation` |
+
+Format:
+```text
+| المجال | السؤال | الافتراض المقترح | الحالة | تاريخ المراجعة |
+|--------|--------|-----------------|--------|----------------|
+```
+
+Output: Small projects → inside `project-inputs/01_APPLICATION_IDEA.md`. Medium/large → separate `ASSUMPTIONS_AND_OPEN_QUESTIONS.md`. External clients → referenced in `SCOPE_OF_WORK.md`.
+
+---
+
+## Smart Selection Rules
+
+| If the user... | Then prioritize... |
+|---|---|
+| Has clear technical preferences | Domain 4 (Technical) deep dive |
+| Is unsure about technology | Start with Domain 2 (Functional), defer Technical |
+| Mentions data-heavy features | Domain 3 (Data and Reporting) |
+| Mentions visual design or brand | Domain 5 (Design and UX) |
+| Mentions sensitive data or multiple roles | Domain 6 (Security and Permissions) |
+| Has specific hosting/deployment needs | Domain 7 (Operational and Deployment) |
+| Has existing system being replaced | Deep dive into Domain 2 (migration workflows) |
+| Is an external client | Start with Domain 1 (client context), then standard flow |
+
+### Batch Size by User Type
+
+| User type | Batch size |
+|---|---|
+| Internal (Majed) | 5–7 questions per round |
+| External client (via Majed) | 3–5 questions per round |
+| Busy or impatient user | 3–4 questions per round |
+
+### Adaptive Depth by Project Size
+
+| Size | Approximate length |
+|---|---|
+| Simple / small app | 10–15 questions total |
+| Medium app | 20–35 questions |
+| Complex / ERP / SaaS | Multiple rounds, deeper per domain |
+
+---
+
+## Documentation Rules
+
+- Document each answer immediately in `project-inputs/` as the interview proceeds.
+- Do not leave materially important answers only in chat history.
+- For external clients, document also in `clients/.../CLIENT_PROFILE.md`.
+- At the end: `project-inputs/01_APPLICATION_IDEA.md` reflects the full picture.
+- Assumptions must be separately tracked.
+
+---
+
+## Relationship to Other Protocols
+
+- This protocol runs **before** formal preparation.
+- After proposal approval → `TeraProjectIntakePolicy.md` readiness checks apply.
+- `Application Discovery Protocol` runs **after** proposal approval.
+- `Client Approval Workflow Protocol` (in TeraClientPolicy.md) remains unchanged.
+
+---
+
+*هذا الملف مقتبس من §18 من `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (النسخة الأصلية) مع اختصار الأجزاء المكررة والإحالة لملفات السياسات.*

package/core/tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md

@@ -0,0 +1,124 @@
+# Domain Intelligence and Research Protocol
+
+Domain Intelligence is a conditional layer for source-grounded business/domain understanding. It covers all research activities — during Client Discovery, during the Smart Interview, before formal preparation, and at any point when Tera or the user needs external information.
+
+**Core rule:**
+```text
+Research informs. Domain analysis recommends. Tera decides.
+```
+
+---
+
+## 1. Advisory-Only Rules
+
+- Domain research is advisory, not scope.
+- Domain analysis is advisory, not requirements.
+- External references are not automatic project scope.
+- No external source overrides `PROJECT_RULES.md` or approved project decisions.
+- Tera remains the final decision owner.
+- Research findings must be source-grounded and source-tiered.
+- **No recommendation may be presented as fact without a source or cited reference.**
+
+---
+
+## 2. The No-Guessing Rule
+
+```text
+When Tera does not have reliable, source-grounded knowledge about a topic,
+Tera must search before assuming.
+
+A "reasonable default" without research is acceptable only for:
+- Trivial, well-known, universally established patterns (e.g., email/password login)
+- The client's own stated preference
+- When the user explicitly says "اختر أنت" or "افترض أنسب"
+
+For everything else: SEARCH FIRST, THEN RECOMMEND.
+```
+
+If research is unavailable or inconclusive: document the limitation clearly, present as `Unknown — needs client decision`, never present an unresearched opinion as a reliable recommendation.
+
+---
+
+## 3. Research Depth Levels
+
+| Level | When to use | Typical output |
+|---|---|---|
+| **Quick Search** | Real-time during discovery; simple fact-finding | 2–4 sentence summary with source |
+| **Focused Research** | Specific question with multiple options | Comparison table, pros/cons, source tiers |
+| **Deep Research** | Full domain analysis (ERP, compliance, complex domain) | Research Brief + DomainExpertAgent report |
+
+Use the smallest sufficient research depth. Escalate only when justified.
+
+---
+
+## 4. Research Triggers
+
+- **During Client Discovery:** when client mentions unfamiliar topic → real-time Quick Search
+- **During Smart Interview:** when Question Bank marks `[Research recommended]`
+- **On-demand:** Majed explicitly asks for research
+- **Before Formal Preparation:** DomainResearchAgent + DomainExpertAgent pipeline for significant domain complexity
+
+---
+
+## 5. Source Policy
+
+| Tier | Type | Usage |
+|---|---|---|
+| Tier 1 | Official documentation, standards, authoritative sources | Primary reference |
+| Tier 2 | Books, whitepapers, reputable professional material | Supporting reference |
+| Tier 3 | General blogs and community examples | Supplementary only |
+| Forbidden | Unverifiable, weak, copied, unclear, or marketing-only content | Never use |
+
+Reference-system rule: SAP / Oracle / Odoo / Dynamics may be used as reference sources, not mandatory blueprints.
+
+---
+
+## 6. Research Brief Rule
+
+```text
+No open-ended domain research without a Research Brief.
+```
+
+Exception: Quick Search during Client Discovery does not need a formal brief — but must still cite sources.
+
+---
+
+## 7. Mode Detection
+
+| If task comes from... | Mode | Pipeline |
+|---|---|---|
+| TeraAgent | **Software Mode** | DomainResearchAgent → DomainExpertAgent → classification by MVP/later/scope |
+| TCEA (مستشار) | **Consulting Mode** | DomainResearchAgent → DomainExpertAgent → [Research Hint] → Majed confirms scope |
+
+---
+
+## 8. Agent Boundaries
+
+**DomainResearchAgent:**
+- Collects and summarizes source-grounded information; must cite sources and source tiers.
+- Must not decide scope, create tasks, or modify project files.
+- For details: see `.opencode/agents/domain-research-agent.md` §6 (How This Agent Works).
+
+**DomainExpertAgent:**
+- Analyzes research, converts into practical business concepts, workflows, risks, and options.
+- Must classify recommendations by MVP/later/out-of-scope/decision-needed.
+- Must not expand MVP or override project rules.
+- For details: see `.opencode/agents/domain-expert-agent.md` §6 (How This Agent Works).
+
+---
+
+## 9. Documentation of Research-Backed Recommendations
+
+Every research-backed recommendation must include:
+
+```text
+المصدر: [اسم المصدر + رابط]
+مستوى المصدر: Tier 1 / 2 / 3
+الملخص: [ما وجدته]
+سبب الاختيار: مناسب / غير مناسب (سبب: ...)
+التصنيف: [Include now / Recommended / Defer / Out of Scope / Needs User Decision]
+```
+
+---
+
+*هذا الملف مقتبس من §12 من `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (النسخة الأصلية) بعد اختصار الإجراءات التفصيلية والإحالة لتعريفات العملاء.*