@tera-system/core 0.1.0

package/core/tera-system/knowledge-base/OPENHANDS_ARCHITECTURE_REFERENCE.md

@@ -0,0 +1,243 @@
+# OpenHands — مرجع معماري للدراسة المستقبلية
+
+> **أنشئ:** 2026-07-26
+> **المصدر:** https://github.com/OpenHands/OpenHands (82.2k★)
+> **الغرض:** ملف مرجعي لدراسة OpenHands لاحقاً وتطبيق مفاهيمه على Tera
+> **حالة الدراسة:** ⏳ لم تبدأ بعد — أنشئ للرجوع إليه
+
+---
+
+## 1. ما هو OpenHands؟
+
+منصة **مفتوحة المصدر** لتشغيل وإدارة العملاء البرمجيين (Coding Agents) على نطاق واسع.
+ليست مجرد IDE أو CLI — بل **نظام تشغيل كامل للعملاء**.
+
+### الإحصائيات
+- ⭐ 82.2k★
+- 🍴 10.5k Fork
+- 📝 7,082 Commit
+- 📜 Apache 2.0 License
+
+---
+
+## 2. المكونات المعمارية الأساسية
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                    OpenHands System                         │
+├────────────────────────────────────────────────────────────┤
+│                                                            │
+│  ┌───────────────────────┐                                 │
+│  │    Agent Canvas       │ ← واجهة تحكم Frontend (UI)      │
+│  │   @openhands/agent-   │    تبوك: localhost:8000          │
+│  │     canvas            │    تشغيل محلي أو سحابي          │
+│  └──────────┬────────────┘                                 │
+│             │ HTTP/REST                                    │
+│  ┌──────────▼────────────┐                                 │
+│  │    Agent Server       │ ← REST API لتشغيل العملاء       │
+│  │  (software-agent-sdk) │    • يشغّل عدة عملاء على Server │
+│  │                       │    • يمكن تشغيل Servers متعددة  │
+│  └──────────┬────────────┘    • Local / Docker / VM / Cloud│
+│             │                                              │
+│  ┌──────────▼────────────┐                                 │
+│  │  Automation Server    │ ← تشغيل مجدول + أحداث          │
+│  │  (github.com/         │    • Cron jobs                 │
+│  │   OpenHands/          │    • Webhooks (GitHub, Linear)  │
+│  │   automation)         │    • تكامل Slack, Discord       │
+│  └────────────────────────┘                                 │
+│                                                            │
+│  ┌────────────────────────┐                                │
+│  │  ACP (Agent-Client     │ ← بروتوكول تواصل موحّد        │
+│  │  Protocol)             │    • أي عميل (Claude, Codex,   │
+│  │                        │      Gemini, OpenHands)        │
+│  │                        │    • يتواصل مع أي Server       │
+│  └────────────────────────┘                                │
+│                                                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Agent Canvas بالتفصيل
+
+| الخاصية | الوصف |
+|----------|--------|
+| **التركيب** | `npm install -g @openhands/agent-canvas` |
+| **التشغيل** | `agent-canvas` → localhost:8000 |
+| **التقسيم** | `--frontend-only` لواجهة فقط، `--backend-only` لخادم فقط |
+| **الغرض** | واجهة مرئية لعرض وتشغيل ومراقبة العملاء |
+
+### الميزات
+- تشغيل عدة عملاء بالتوازي
+- Dashboard لكل عميل (حالته، مخرجاته، سجلاته)
+- التبديل بين Backends مختلفة دون فقدان السياق
+- إضافة Backends جديدة من الواجهة نفسها
+
+---
+
+## 4. Agent Server بالتفصيل
+
+```
+Agent Canvas → HTTP REST → Agent Server → Agent (OpenHands/Claude/Codex)
+```
+
+| الخاصية | الوصف |
+|----------|--------|
+| **التشغيل** | محلي، Docker، VM، Mac Mini، سحابة |
+| **اللغة** | Python (uv) |
+| **REST API** | نعم — endpoints لتشغيل وإدارة العملاء |
+| **Multi-Server** | يمكن التبديل بين Servers متعددة |
+| **Sandbox** | اختياري — Docker isolation |
+
+### أين يُشغّل؟
+- مباشرة على اللابتوب (⚠️ وصول كامل للملفات)
+- على Mac Mini مخصص
+- على VM في السحابة
+- داخل Docker (موصى به)
+- OpenHands Cloud (تجاري)
+
+---
+
+## 5. Automation Server
+
+| الخاصية | الوصف |
+|----------|--------|
+| **الجدولة** | Cron — مجدولة زمنياً |
+| **الأحداث** | Webhooks — GitHub, Linear, Slack |
+| **التكاملات** | Slack, GitHub, Notion, Datadog |
+| **الغرض** | تشغيل العملاء دون تدخل يدوي |
+
+### أمثلة
+- "كل صباح: راجع الـ PRs المفتوحة وقدم ملخصاً"
+- "عند إغلاق Issue → حلل السبب الجذري"
+- "عند Push إلى main → شغّل اختبارات الأمان"
+
+---
+
+## 6. ACP — Agent-Client Protocol
+
+**هذا أهم ما في OpenHands معمارياً.**
+
+```
+[Agent Client Protocol - ACP]
+  ┌─────────┐      ┌──────────────┐
+  │ Claude  │      │  OpenHands   │
+  │  Code   │←────→│  Agent       │
+  └─────────┘      └──────────────┘
+  ┌─────────┐      ┌──────────────┐
+  │  Codex  │←────→│  Agent       │
+  └─────────┘      └──────────────┘
+  ┌─────────┐      ┌──────────────┐
+  │ Gemini  │←────→│  Agent       │
+  └─────────┘      └──────────────┘
+```
+
+- بروتوكول REST موحّد
+- أي عميل يتوافق مع ACP يعمل مع أي Server يدعم ACP
+- يسمح بالتبديل بين العملاء دون تغيير البنية التحتية
+- **يذكّرني بـ TeraSubAgents.md لكن كبروتوكول رسمي**
+
+---
+
+## 7. مقارنة مع Tera — الوضع الحالي
+
+| المفهوم | OpenHands | Tera (حالياً) |
+|---------|-----------|---------------|
+| **واجهة تحكم** | Agent Canvas (UI) | ❌ لا يوجد |
+| **تشغيل العملاء** | Agent Server (REST) | ✅ task tool + .opencode/agents/ |
+| **أتمتة مجدولة** | Automation Server (Cron) | ❌ يدوي بالكامل |
+| **بروتوكول موحّد** | ACP | 🟡 TeraSubAgents.md (نصي) |
+| **عزل العملاء** | Sandbox (Docker) | ❌ لا يوجد |
+| **Multi-Backend** | Local + Docker + VM + Cloud | ❌ جهاز واحد |
+| **تكامل خارجي** | Slack, GitHub, Linear, Notion | ❌ لا يوجد |
+| **التوسع** | أفقي (Servers متعددة) | 🟡 عمودي (عملاء أكثر) |
+
+---
+
+## 8. ما يمكن استلهامه لتطوير Tera
+
+### 8.1 ACP → TeraSubAgents.md v2
+تحويل TeraSubAgents.md من "ملف تعريف" إلى "بروتوكول اتصال" يحدد:
+- كيف يستدعي عميل عميلاً آخر
+- ما هي Request/Response format
+- كيف يُدار السياق بين العملاء
+
+### 8.2 Agent Canvas → Tera Dashboard
+لوحة تحكم لـ Majed:
+- يرى كل العملاء (TeraAgent, Engineering, UI, QA...)
+- حالة كل عميل (شغال؟ منتظر؟ مكتمل؟)
+- سجلات ومخرجات كل عميل
+
+### 8.3 Automation Server → Tera Scheduler
+تشغيل مهام دورية:
+- "افحص جميع المشاريع بـ Trivy كل أسبوع"
+- "أرسل تقرير الجودة كل يوم جمعة"
+- "راقب تحديثات الأمان في dependencies"
+
+### 8.4 Agent Server → Tera Execution Layer
+فصل "من يقرر" عن "من ينفذ":
+- TeraAgent يقرر فقط (كما هو الآن)
+- Execution Layer جديد يشغّل العملاء (مثل Agent Server)
+- يمكن تشغيل Execution Layer على Docker أو VM
+
+---
+
+## 9. سيناريو التطبيق الجذري (نسخة أخرى من Tera)
+
+```
+┌──────────────────────────────────────────────┐
+│              Tera v2 (مقترح)                  │
+├──────────────────────────────────────────────┤
+│                                              │
+│  ┌──────────────────────┐                    │
+│  │   Tera Dashboard    │ ← UI لإدارة العملاء │
+│  ├──────────────────────┤                    │
+│  │   Tera Execution     │ ← REST API Layer   │
+│  │   Server             │    لتشغيل العملاء   │
+│  ├──────────────────────┤                    │
+│  │   Tera Protocol      │ ← ACP-like protocol│
+│  │   (TP-1)             │    للتواصل بين      │
+│  │                      │    العملاء          │
+│  ├──────────────────────┤                    │
+│  │   Tera Scheduler     │ ← Cron + Events   │
+│  ├──────────────────────┤                    │
+│  │   Sandbox Manager    │ ← Docker isolation │
+│  └──────────────────────┘                    │
+│                                              │
+│  ════════════════════════════════════════     │
+│                                              │
+│  يبقى Tera v1 (الحالي) كما هو للإنتاج.       │
+│  Tera v2 يُبنى بالتوازي كإعادة هيكلة.         │
+│                                              │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+## 10. روابط مهمة للدراسة
+
+| الرابط | الوصف |
+|--------|--------|
+| https://github.com/OpenHands/OpenHands | المستودع الرئيسي |
+| https://github.com/OpenHands/software-agent-sdk | الـ SDK الرسمي للـ Agent و Agent Server |
+| https://github.com/OpenHands/agent-canvas | واجهة التحكم الأمامية |
+| https://github.com/OpenHands/automation | سيرفر الأتمتة |
+| https://docs.openhands.dev/overview/introduction | التوثيق الرسمي |
+| https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents | ACP Protocol specs |
+| https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm | دليل Self-Hosting |
+
+---
+
+## 11. حالة الدراسة
+
+- [ ] قراءة ACP Specifications
+- [ ] تحليل Agent Server Architecture
+- [ ] تحليل Agent Canvas Architecture
+- [ ] دراسة Automation Server
+- [ ] مقارنة مع TeraSubAgents.md
+- [ ] إنتاج SYSTEM_CHANGE_PROPOSAL للتحسينات المستوحاة
+- [ ] بدء Tera v2 بالتوازي (اختياري)
+
+---
+
+> **ملاحظة:** هذا الملف مرجعي بحت. أي دراسة أو تطبيق يتطلب الرجوع إلى المصادر الأصلية والموافقة على SYSTEM_CHANGE_PROPOSAL قبل التنفيذ.

package/core/tera-system/knowledge-base/manufacturing/00_INDEX.md

@@ -0,0 +1,32 @@
+# Manufacturing Knowledge Base Index
+
+Owner: Majed
+Primary consumer: `production-erp-expert`
+Location: `tera-system/knowledge-base/manufacturing/`
+
+## Status Rule
+
+Files marked `DRAFT_PLACEHOLDER` are not sufficient sources. The Production ERP Expert may list them as pending, but must not treat them as verified knowledge until Majed marks them `READY`.
+
+## Files
+
+| File | Purpose | Status |
+|---|---|---|
+| `01_MANUFACTURING_ERP_CORE_CONCEPTS.md` | Core manufacturing ERP concepts | DRAFT_PLACEHOLDER |
+| `02_SAP_MANUFACTURING_RESEARCH.md` | SAP manufacturing research | DRAFT_PLACEHOLDER |
+| `03_DYNAMICS_365_MANUFACTURING_RESEARCH.md` | Dynamics 365 manufacturing research | DRAFT_PLACEHOLDER |
+| `04_ORACLE_MANUFACTURING_RESEARCH.md` | Oracle manufacturing research | DRAFT_PLACEHOLDER |
+| `05_ODOO_MANUFACTURING_RESEARCH.md` | Odoo manufacturing research | DRAFT_PLACEHOLDER |
+| `06_ERPNEXT_MANUFACTURING_RESEARCH.md` | ERPNext manufacturing research | DRAFT_PLACEHOLDER |
+| `07_MANUFACTURING_COSTING_GUIDE.md` | Manufacturing costing guide | DRAFT_PLACEHOLDER |
+| `08_PRODUCTION_DISCOVERY_QUESTIONS.md` | Production discovery questions | DRAFT_PLACEHOLDER |
+| `09_MANUFACTURING_BLUEPRINT_CHECKLIST.md` | Manufacturing blueprint checklist | DRAFT_PLACEHOLDER |
+| `10_PRODUCTION_TEST_SCENARIOS.md` | Production test scenarios | DRAFT_PLACEHOLDER |
+| `11_QUALITY_REWORK_AND_SCRAP_GUIDE.md` | Quality, rework, and scrap guide | DRAFT_PLACEHOLDER |
+| `12_MRP_AND_PLANNING_GUIDE.md` | MRP and planning guide | DRAFT_PLACEHOLDER |
+| `13_LOCAL_AND_REGIONAL_MANUFACTURING_CONTEXT.md` | Local/regional manufacturing context | DRAFT_PLACEHOLDER |
+| `14_VENDOR_COMPARISON_MATRIX.md` | Vendor comparison matrix | DRAFT_PLACEHOLDER |
+
+## Update Rule
+
+Majed updates research content. When a file becomes reliable for use, change its status here and inside the file from `DRAFT_PLACEHOLDER` to `READY`.

package/core/tera-system/knowledge-base/manufacturing/01_MANUFACTURING_ERP_CORE_CONCEPTS.md

@@ -0,0 +1,7 @@
+# 01 — Manufacturing ERP Core Concepts
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Core concepts for production ERP: manufacturing models, BOM/formula, routing, work centers, production orders, WIP, MRP, costing, quality, and inventory integration.

package/core/tera-system/knowledge-base/manufacturing/02_SAP_MANUFACTURING_RESEARCH.md

@@ -0,0 +1,7 @@
+# 02 — SAP Manufacturing Research
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: SAP manufacturing concepts, production orders, BOM/routing, MRP, costing, quality, WIP, and vendor-specific behavior.

package/core/tera-system/knowledge-base/manufacturing/03_DYNAMICS_365_MANUFACTURING_RESEARCH.md

@@ -0,0 +1,7 @@
+# 03 — Dynamics 365 Manufacturing Research
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Microsoft Dynamics 365 Supply Chain Management manufacturing research and vendor-specific production behavior.

package/core/tera-system/knowledge-base/manufacturing/04_ORACLE_MANUFACTURING_RESEARCH.md

@@ -0,0 +1,7 @@
+# 04 — Oracle Manufacturing Research
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Oracle Fusion Cloud Manufacturing research and vendor-specific manufacturing behavior.

package/core/tera-system/knowledge-base/manufacturing/05_ODOO_MANUFACTURING_RESEARCH.md

@@ -0,0 +1,7 @@
+# 05 — Odoo Manufacturing Research
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Odoo Manufacturing research, BOM, work orders, planning, quality, inventory, and costing considerations.

package/core/tera-system/knowledge-base/manufacturing/06_ERPNEXT_MANUFACTURING_RESEARCH.md

@@ -0,0 +1,7 @@
+# 06 — ERPNext Manufacturing Research
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: ERPNext manufacturing research, work orders, BOM, stock entries, subcontracting, and costing behavior.

package/core/tera-system/knowledge-base/manufacturing/07_MANUFACTURING_COSTING_GUIDE.md

@@ -0,0 +1,7 @@
+# 07 — Manufacturing Costing Guide
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Production costing concepts: standard cost, actual cost, weighted average, WIP, variance, scrap, rework, overhead, and accounting impact.

package/core/tera-system/knowledge-base/manufacturing/08_PRODUCTION_DISCOVERY_QUESTIONS.md

@@ -0,0 +1,7 @@
+# 08 — Production Discovery Questions
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Interview questions across the full production lifecycle: profile, product structure, BOM, routing, resources, planning, execution, inventory, WIP, quality, costing, reports, and controls.

package/core/tera-system/knowledge-base/manufacturing/09_MANUFACTURING_BLUEPRINT_CHECKLIST.md

@@ -0,0 +1,7 @@
+# 09 — Manufacturing Blueprint Checklist
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Checklist for reviewing manufacturing blueprints before preparation or implementation.

package/core/tera-system/knowledge-base/manufacturing/10_PRODUCTION_TEST_SCENARIOS.md

@@ -0,0 +1,7 @@
+# 10 — Production Test Scenarios
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Functional, integration, costing, inventory, quality, rework, scrap, and exception test scenarios for production ERP.

package/core/tera-system/knowledge-base/manufacturing/11_QUALITY_REWORK_AND_SCRAP_GUIDE.md

@@ -0,0 +1,7 @@
+# 11 — Quality, Rework, and Scrap Guide
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Quality inspection, rejection, rework, scrap, accept-with-deviation, quality hold, inventory status, costing impact, and approval rules.

package/core/tera-system/knowledge-base/manufacturing/12_MRP_AND_PLANNING_GUIDE.md

@@ -0,0 +1,7 @@
+# 12 — MRP and Planning Guide
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: MRP, MPS, demand planning, material requirements, lead time, safety stock, capacity planning, and production scheduling.

package/core/tera-system/knowledge-base/manufacturing/13_LOCAL_AND_REGIONAL_MANUFACTURING_CONTEXT.md

@@ -0,0 +1,7 @@
+# 13 — Local and Regional Manufacturing Context
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Local/regional manufacturing practices, terminology, business constraints, compliance notes, and implementation realities relevant to Majed's work.

package/core/tera-system/knowledge-base/manufacturing/14_VENDOR_COMPARISON_MATRIX.md

@@ -0,0 +1,7 @@
+# 14 — Vendor Comparison Matrix
+
+Status: DRAFT_PLACEHOLDER — Content pending Majed research.
+
+Rule: This file is not a sufficient source until Majed fills and marks it as READY.
+
+Purpose: Comparison matrix for common and vendor-specific manufacturing ERP patterns across SAP, Dynamics 365, Oracle, Odoo, ERPNext, and other relevant systems.