Document FlowDefinition fields in the JSON schema

Add a description and examples to every FlowDefinition field and
standardize on `typing.Literal`, so the generated JSON schema documents
itself — each action discriminator, state branch, and config option
explains what it is and shows a realistic value.

Examples live on individual fields only, never at the model level, which
keeps the schema readable for tooling that renders field-level help.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.github/workflows/vulnerability-scan.yml

@@ -64,6 +64,7 @@ jobs:
             --ignore-vuln PYSEC-2025-197 \
             --ignore-vuln PYSEC-2025-210 \
             --ignore-vuln PYSEC-2026-139 \
+            --ignore-vuln GHSA-rrmf-rvhw-rf47 \
             --ignore-vuln PYSEC-2025-211 \
             --ignore-vuln PYSEC-2025-212 \
             --ignore-vuln PYSEC-2025-213 \
@@ -71,7 +72,8 @@ jobs:
             --ignore-vuln PYSEC-2025-215 \
             --ignore-vuln PYSEC-2025-216 \
             --ignore-vuln PYSEC-2025-217 \
-            --ignore-vuln PYSEC-2025-218
+            --ignore-vuln PYSEC-2025-218 \
+            --ignore-vuln GHSA-f4j7-r4q5-qw2c
         # Ignored CVEs:
         #   PYSEC-2024-277      - joblib 1.5.3: disputed; NumpyArrayWrapper only used with trusted caches
         #   PYSEC-2026-89       - markdown 3.10.2: DoS via malformed HTML; fix 3.8.1 — already past, advisory range is stale
@@ -80,7 +82,11 @@ jobs:
         #   PYSEC-2025-183      - pyjwt 2.12.1: disputed weak-encryption claim; key length is application-chosen
         #   PYSEC-2025-189..197 - torch 2.11.0: memory-corruption/DoS in functions only reachable via untrusted models; no fix available
         #   PYSEC-2025-210, PYSEC-2026-139 - torch 2.11.0: profiler/deserialization issues; no fix available
+        #   GHSA-rrmf-rvhw-rf47 - torch 2.11.0 (CVE-2025-3000, alias of PYSEC-2025-194): memory corruption in torch.jit.script, CVSS 1.9, local-only; affected <=2.12.0, no fix available. pip-audit reports it under the GHSA id so the PYSEC ignore above does not catch it.
         #   PYSEC-2025-211..218 - transformers 5.5.4: deserialization/code injection via malicious model checkpoints; no fix available
+        #   GHSA-f4j7-r4q5-qw2c - chromadb 1.1.1 (CVE-2026-45829): pre-auth RCE via /api/v2/tenants/{tenant}/databases/{db}/collections when trust_remote_code=true.
+        #                         Advisory: vulnerable >=1.0.0,<=1.5.9, firstPatchedVersion=none. We only use chromadb.PersistentClient (lib/crewai/src/crewai/rag/chromadb/factory.py)
+        #                         and chromadb.utils.embedding_functions; the chromadb HTTP server is never started, so the vulnerable route is not exposed.
         continue-on-error: true
 
       - name: Display results

.gitignore

@@ -31,3 +31,5 @@ chromadb-*.lock
 blogs/*
 secrets/*
 UNKNOWN.egg-info/
+demos/*
+.crewai/*

.pre-commit-config.yaml

@@ -28,7 +28,35 @@ repos:
     hooks:
       - id: pip-audit
         name: pip-audit
-        entry: bash -c 'source .venv/bin/activate && uv run pip-audit --skip-editable --ignore-vuln CVE-2026-3219' --
+        # Keep this ignore list in sync with .github/workflows/vulnerability-scan.yml.
+        entry: >-
+          bash -c 'source .venv/bin/activate && uv run pip-audit --skip-editable
+          --ignore-vuln PYSEC-2024-277
+          --ignore-vuln PYSEC-2026-89
+          --ignore-vuln PYSEC-2026-97
+          --ignore-vuln PYSEC-2025-148
+          --ignore-vuln PYSEC-2025-183
+          --ignore-vuln PYSEC-2025-189
+          --ignore-vuln PYSEC-2025-190
+          --ignore-vuln PYSEC-2025-191
+          --ignore-vuln PYSEC-2025-192
+          --ignore-vuln PYSEC-2025-193
+          --ignore-vuln PYSEC-2025-194
+          --ignore-vuln PYSEC-2025-195
+          --ignore-vuln PYSEC-2025-196
+          --ignore-vuln PYSEC-2025-197
+          --ignore-vuln PYSEC-2025-210
+          --ignore-vuln PYSEC-2026-139
+          --ignore-vuln GHSA-rrmf-rvhw-rf47
+          --ignore-vuln PYSEC-2025-211
+          --ignore-vuln PYSEC-2025-212
+          --ignore-vuln PYSEC-2025-213
+          --ignore-vuln PYSEC-2025-214
+          --ignore-vuln PYSEC-2025-215
+          --ignore-vuln PYSEC-2025-216
+          --ignore-vuln PYSEC-2025-217
+          --ignore-vuln PYSEC-2025-218
+          --ignore-vuln GHSA-f4j7-r4q5-qw2c' --
         language: system
         pass_filenames: false
         stages: [pre-push, manual]

conftest.py

@@ -11,7 +11,99 @@ from typing import Any
 
 from dotenv import load_dotenv
 import pytest
-from vcr.request import Request  # type: ignore[import-untyped]
+
+
+def _patch_vcrpy_aiohttp_compat() -> None:
+    """Keep vcrpy's aiohttp stub working under aiohttp 3.14.0.
+
+    aiohttp 3.14.0 (pulled in to fix GHSA-jg22-mg44-37j8 and GHSA-hg6j-4rv6-33pg):
+      * removed ``aiohttp.streams.AsyncStreamReaderMixin`` (folded into ``StreamReader``),
+        which vcrpy's ``MockStream`` still subclasses -- vcr's patch machinery then raises
+        ``AttributeError`` at collection time; and
+      * added a required ``stream_writer`` keyword-only arg to ``ClientResponse.__init__``,
+        which vcrpy's ``MockClientResponse`` does not pass -- raising ``TypeError`` at
+        cassette playback.
+
+    Restore the mixin, then rebuild ``MockClientResponse``'s ``super().__init__`` call from
+    the live ``ClientResponse`` signature (defaulting every required keyword-only arg to
+    ``None``, mirroring vcrpy's original call) so it also survives future aiohttp additions.
+    """
+    import asyncio
+    import inspect
+
+    from aiohttp import streams
+    from aiohttp.client_reqrep import ClientResponse
+
+    if not hasattr(streams, "AsyncStreamReaderMixin"):
+
+        class AsyncStreamReaderMixin:
+            __slots__ = ()
+
+            def __aiter__(self) -> streams.AsyncStreamIterator[bytes]:
+                return streams.AsyncStreamIterator(self.readline)  # type: ignore[attr-defined]
+
+            def iter_chunked(self, n: int) -> streams.AsyncStreamIterator[bytes]:
+                return streams.AsyncStreamIterator(lambda: self.read(n))  # type: ignore[attr-defined]
+
+            def iter_any(self) -> streams.AsyncStreamIterator[bytes]:
+                return streams.AsyncStreamIterator(self.readany)  # type: ignore[attr-defined]
+
+            def iter_chunks(self) -> streams.ChunkTupleAsyncStreamIterator:
+                return streams.ChunkTupleAsyncStreamIterator(self)  # type: ignore[arg-type]
+
+        streams.AsyncStreamReaderMixin = AsyncStreamReaderMixin  # type: ignore[attr-defined]
+
+    # Importing the stub builds MockStream/MockClientResponse, so it must run after the
+    # mixin is restored above.
+    import vcr.stubs.aiohttp_stubs as aiohttp_stubs  # type: ignore[import-untyped]
+
+    if getattr(aiohttp_stubs.MockClientResponse, "_crewai_aiohttp_patched", False):
+        return
+
+    keyword_only = [
+        name
+        for name, param in inspect.signature(ClientResponse.__init__).parameters.items()
+        if param.kind is inspect.Parameter.KEYWORD_ONLY
+    ]
+
+    class _NullStreamWriter:
+        # aiohttp 3.14.0 reads stream_writer.output_size in the "request already
+        # sent" branch (writer is None), so None is not enough -- supply a stub.
+        output_size = 0
+
+    fallback_loop: list[asyncio.AbstractEventLoop] = []
+
+    def _resolve_loop() -> asyncio.AbstractEventLoop:
+        # MockClientResponse is normally built inside aiohttp's running loop, so
+        # prefer that. In a sync context there is no running loop; avoid
+        # asyncio.get_event_loop(), which on 3.12+ emits a DeprecationWarning
+        # (and can RuntimeError) when no current loop is set. Use one cached
+        # loop instead -- the mock only stores it and calls loop.get_debug().
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            if not fallback_loop:
+                fallback_loop.append(asyncio.new_event_loop())
+            return fallback_loop[0]
+
+    def _mock_client_response_init(
+        self: Any, method: str, url: Any, request_info: Any = None
+    ) -> None:
+        kwargs: dict[str, Any] = dict.fromkeys(keyword_only)
+        kwargs["request_info"] = request_info
+        if "loop" in kwargs:
+            kwargs["loop"] = _resolve_loop()
+        if "stream_writer" in kwargs:
+            kwargs["stream_writer"] = _NullStreamWriter()
+        ClientResponse.__init__(self, method, url, **kwargs)
+
+    aiohttp_stubs.MockClientResponse.__init__ = _mock_client_response_init
+    aiohttp_stubs.MockClientResponse._crewai_aiohttp_patched = True
+
+
+_patch_vcrpy_aiohttp_compat()
+
+from vcr.request import Request  # type: ignore[import-untyped]  # noqa: E402
 
 
 try:

docs/ar/changelog.mdx

@@ -4,6 +4,248 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="11 يونيو 2026">
+  ## v1.14.7
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow.
+  - عرض السبب الحقيقي للإنهاء، ومعلمات العينة، وresponse.id في أحداث LLM.
+  - تصنيف مشغلات DSL كزخارف واعية للمسار.
+  - إضافة واجهة برمجة تطبيقات الدردشة لتدفقات المحادثة.
+  - جعل واجهة القفل قابلة للتجاوز.
+  - بناء FlowDefinition من بيانات التعريف الخاصة بـ Flow DSL.
+  - إضافة مزود LLM من Snowflake Cortex الأصلي.
+  - إضافة دعم لملفات الوكلاء المدربين من crew.
+
+  ### إصلاحات الأخطاء
+  - إصلاح نقطة التحقق لإعادة بناء BaseLLM مخصص كـ LLM ملموس عند الاستعادة.
+  - تقييد الاستعادة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف.
+  - تحديد حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيل المتزامن.
+  - إصلاح إعدادات التتبع على crewai-login.
+  - احترام suppress_flow_events لأحداث تنفيذ الطريقة.
+  - استعادة [project.scripts] في حزمة crewai لتثبيت أداة uv.
+  - حل مشكلات CVE الخاصة بـ pip-audit لـ aiohttp وdocling وdocling-core.
+  - إصلاح إدخال الملفات الذي لا يعمل بشكل موثوق.
+  - إصلاح تاريخ نتائج أدوات Snowflake Claude غير المكتملة.
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7.
+  - تحديث وثائق جامع OpenTelemetry.
+  - تحديث دليل NVIDIA Nemotron LLM.
+  - إضافة دليل تكامل Databricks.
+  - إضافة دليل تكامل Snowflake.
+
+  ### الأداء
+  - تحسين سرعة استيراد crewai من خلال تحميل مستندات docling بشكل كسول.
+
+  ### إعادة الهيكلة
+  - تبسيط تقييم شروط التدفق ليكون بلا حالة لكل حدث.
+  - فصل منطق المحادثة عن وقت التشغيل وإضافة تعريف المحادثة.
+  - تقسيم `flow.py` إلى DSL، وتعريف، ووقت تشغيل.
+
+  ## المساهمون
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="10 يونيو 2026">
+  ## v1.14.7rc2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - استعادة البوابة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7rc1
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="10 يونيو 2026">
+  ## v1.14.7rc1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة `reset_runtime_state` لإطلاق حالة الحافلة المتراكمة
+  - التعامل مع دعم كل من الموجهات المخصصة
+  - فصل منطق المحادثة عن وقت التشغيل وإضافة `conversational_definition`
+
+  ### إصلاحات الأخطاء
+  - إصلاح نطاق حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيلات المتزامنة
+  - إصلاح إعدادات القياس عن بُعد على `crewai-login`
+  - إصلاح احترام `suppress_flow_events` لفعاليات تنفيذ الأساليب
+
+  ### الوثائق
+  - تحديث صور OpenTelemetry
+  - تحديث الوثائق لتعكس الحالة الجديدة لجمع بيانات OpenTelemetry
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7a4
+
+  ### إعادة الهيكلة
+  - تبسيط تقييم شرط التدفق ليكون بلا حالة لكل حدث
+  - تحسين دورة توجيه المحادثة مع تقليل مسار واحد
+
+  ## المساهمون
+
+  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
+
+</Update>
+
+<Update label="9 يونيو 2026">
+  ## v1.14.7a4
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - نقل وقت التشغيل @listen/@router لقراءة من FlowDefinition
+  - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7a3
+
+  ## المساهمون
+
+  @greysonlalonde, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="8 يونيو 2026">
+  ## v1.14.7a3
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح تعرض `ask_for_human_input` في `AgentExecutor` التجريبي
+  - حل مشكلات CVEs الخاصة بـ pip-audit لـ `aiohttp`، `docling`، `docling-core`، و `pip`
+
+  ### إعادة هيكلة
+  - نقل `@start` لقراءة من `FlowDefinition`
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7a2
+
+  ## المساهمون
+
+  @greysonlalonde، @lorenzejay، @vinibrsl
+
+</Update>
+
+<Update label="5 يونيو 2026">
+  ## v1.14.7a2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة دعم تتبع تدفقات المحادثة.
+  - تحديث وثائق تدفق المحادثة لاستخدام `handle_turn`.
+  - عرض السبب الحقيقي لإنهاء المحادثة، ومعلمات العينة، و`response.id` في أحداث LLM.
+  - تصنيف مشغلات DSL كزخارف واعية بالمسار.
+  - تنفيذ واجهة برمجة التطبيقات للدردشة لتدفقات المحادثة.
+  - جعل قفل الخلفية قابلاً للتجاوز في متجر القفل.
+  - تقسيم أحادي تدفق DSL إلى وحدات زخرفية مركزة.
+  - تسطيح استخدام ذاكرة التخزين المؤقت LiteLLM/أعداد الأسباب الفرعية في `_usage_to_dict`.
+  - بناء `FlowDefinition` من بيانات التعريف الخاصة بتدفق DSL.
+
+  ### الوثائق
+  - إضافة دليل NVIDIA Nemotron LLM.
+  - توثيق عمليات نشر المونوريبو.
+  - تحديث سجل التغييرات والإصدار لـ v1.14.7a1.
+
+  ## المساهمون
+
+  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="3 يونيو 2026">
+  ## v1.14.7a1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a1)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة دعم ملفات الوكلاء المدربين
+  - إضافة مزود LLM الأصلي لـ Snowflake Cortex
+  - إضافة دليل تكامل Databricks
+  - إضافة دليل تكامل Snowflake
+
+  ### إصلاحات الأخطاء
+  - إصلاح CLI عن طريق استعادة `[project.scripts]` في حزمة crewai لتثبيت أداة UV
+  - حل مشكلات موثوقية إدخال الملفات
+  - إصلاح تاريخ نتائج الأدوات غير المكتملة في Snowflake Claude
+  - التعامل مع استدعاءات الأدوات الممثلة كسلاسل لـ Snowflake Claude
+  - إعادة تفعيل مستمعي `or_` متعدد المصادر عبر دورات مدفوعة بالموجه
+
+  ### الأداء
+  - تحسين سرعة استيراد crewai عن طريق تحميل استيرادات docling بشكل كسول
+
+  ### إعادة هيكلة
+  - تقسيم `flow.py` إلى DSL، تعريف، وتشغيل
+
+  ## المساهمون
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @jessemiller, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="28 مايو 2026">
+  ## v1.14.6
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - تحسين StdioTransport لمنع تسرب متغيرات البيئة
+  - تعزيز تكوين التخطيط ومعالجة الملاحظات
+  - إعلان env_vars على DatabricksQueryTool
+  - إضافة وثائق خطة التحكم في الوكيل
+
+  ### إصلاحات الأخطاء
+  - إصلاح تسرب المخرجات المنظمة في حلقات استدعاء الأدوات
+  - حذف ردود الاستدعاء غير القابلة للعودة وحالة المحول في نقطة التحقق
+  - تسلسل الحقول من النوع [BaseModel] كـ JSON schema في نقطة التحقق
+  - تجنب مهمة orphan task_started عند استعادة نطاق الاستئناف
+  - السماح لـ AgentExecutor بالاستعادة من نقطة التحقق
+  - تصحيح خطأ الكتابة من mongodb إلى pymongo في package_dependencies
+
+  ### الوثائق
+  - إضافة كتلة تنقل وثائق ACP (بيتا) إلى صفحات خطة التحكم في الوكيل
+  - إزالة المراجع إلى العمليات التوافقية من صفحة العمليات
+  - إعادة هيكلة صفحة نقاط التحقق
+  - توثيق خطوة تثبيت حزمة الإدارة لمرة واحدة
+  - نقل Secrets Manager / Workload Identity من replicated-config
+  - إزالة تعبيرات `{" "}` JSX التي تكسر عرض `<Steps>`
+
+  ### إعادة الهيكلة
+  - نقل مستودع المهارات إلى experimental + CREWAI_EXPERIMENTAL gate
+
+  ## المساهمون
+
+  @akaKuruma, @alex-clawd, @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="27 مايو 2026">
   ## v1.14.6a2
 

docs/ar/concepts/agents.mdx

@@ -70,13 +70,39 @@ mode: "wide"
 
 ## إنشاء الوكلاء
 
-هناك طريقتان لإنشاء الوكلاء في CrewAI: باستخدام **تهيئة YAML (موصى بها)** أو تعريفهم **مباشرة في الكود**.
+هناك طريقتان شائعتان لإنشاء الوكلاء في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفهم **مباشرة في الكود**.
 
-### تهيئة YAML (موصى بها)
+### تهيئة JSONC (موصى بها)
 
-توفر تهيئة YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف الوكلاء. نوصي بشدة باستخدام هذا النهج في مشاريع CrewAI.
+المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` تستخدم تهيئة JSON-first. يُعرّف كل Agent في `agents/<agent_name>.jsonc`، ويحدد `crew.jsonc` أي Agents تدخل في الـ crew.
 
-بعد إنشاء مشروع CrewAI كما هو موضح في قسم [التثبيت](/ar/installation)، انتقل إلى ملف `src/latest_ai_development/config/agents.yaml` وعدّل القالب ليتوافق مع متطلباتك.
+```jsonc agents/researcher.jsonc
+{
+  "role": "{topic} Senior Data Researcher",
+  "goal": "Uncover cutting-edge developments in {topic}",
+  "backstory": "You find the most relevant information and present it clearly.",
+  "llm": "openai/gpt-4o",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
+```
+
+استخدم `{placeholder}` داخل `role` أو `goal` أو `backstory`. ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`؛ وسيطلب `crewai run` أي قيم ناقصة. يمكن وضع حقول السلوك مثل `verbose` و `allow_delegation` و `max_iter` و `memory` و `cache` و `planning_config` في المستوى الأعلى أو داخل `settings`.
+
+<Note>
+يدعم JSONC التعليقات والفواصل النهائية. إذا وُجد `agents/<name>.jsonc` و `agents/<name>.json` معًا، يستخدم CrewAI ملف JSONC.
+</Note>
+
+### تهيئة YAML الكلاسيكية
+
+المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew <name> --classic` تستخدم `config/agents.yaml` وفئة `@CrewBase` في `crew.py`.
+
+تظل تهيئة YAML مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف الوكلاء من خلال فئة `@CrewBase`.
+
+بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف `src/<project_name>/config/agents.yaml` وعدّل القالب ليتوافق مع متطلباتك.
 
 <Note>
 ستُستبدل المتغيرات في ملفات YAML (مثل `{topic}`) بقيم من مدخلاتك عند تشغيل الطاقم:
@@ -88,7 +114,7 @@ crew.kickoff(inputs={'topic': 'AI Agents'})
 إليك مثالًا على كيفية تهيئة الوكلاء باستخدام YAML:
 
 ```yaml agents.yaml
-# src/latest_ai_development/config/agents.yaml
+# src/<project_name>/config/agents.yaml
 researcher:
   role: >
     {topic} Senior Data Researcher
@@ -113,7 +139,7 @@ reporting_analyst:
 لاستخدام تهيئة YAML في الكود، أنشئ فئة طاقم ترث من `CrewBase`:
 
 ```python Code
-# src/latest_ai_development/crew.py
+# src/<project_name>/crew.py
 from crewai import Agent, Crew, Process
 from crewai.project import CrewBase, agent, crew
 from crewai_tools import SerperDevTool

docs/ar/concepts/cli.mdx

@@ -52,6 +52,8 @@ crewai create crew my_new_crew
 crewai create flow my_new_flow
 ```
 
+افتراضيًا، ينشئ `crewai create crew` مشروعًا JSON-first يحتوي على `crew.jsonc` و `agents/*.jsonc`. استخدم `crewai create crew my_new_crew --classic` فقط إذا أردت البنية القديمة Python/YAML مع `crew.py` و `config/agents.yaml` و `config/tasks.yaml`.
+
 ### 2. الإصدار
 
 عرض الإصدار المثبت من CrewAI.
@@ -142,7 +144,20 @@ crewai chat
 ```
 
 <Note>
-مهم: عيّن خاصية `chat_llm` في ملف `crew.py` لتفعيل هذا الأمر.
+مهم: عيّن خاصية `chat_llm` في تعريف الـ crew لتفعيل هذا الأمر.
+
+للـ crews بنمط JSON-first، أضفها إلى `crew.jsonc`:
+
+```jsonc
+{
+  "name": "My Crew",
+  "agents": ["researcher"],
+  "tasks": [],
+  "chat_llm": "openai/gpt-4o"
+}
+```
+
+للـ crews الكلاسيكية Python/YAML، عيّنها في `crew.py`:
 
 ```python
 @crew

docs/ar/concepts/crews.mdx

@@ -40,11 +40,52 @@ mode: "wide"
 
 ## إنشاء الأطقم
 
-هناك طريقتان لإنشاء الأطقم في CrewAI: باستخدام **تهيئة YAML (موصى بها)** أو تعريفها **مباشرة في الكود**.
+هناك طريقتان رئيسيتان لإنشاء الأطقم في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفها **مباشرة في الكود** للمشاريع الكلاسيكية والحالات المتقدمة.
 
-### تهيئة YAML (موصى بها)
+### تهيئة JSONC (موصى بها)
 
-توفر تهيئة YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف الأطقم وتتسق مع كيفية تعريف الوكلاء والمهام في مشاريع CrewAI.
+المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` تستخدم `crew.jsonc` لإعدادات الـ crew والمهام، وملفًا منفصلًا لكل Agent داخل `agents/`. يكتشف `crewai run` ملف `crew.jsonc` أو `crew.json`، ويحمّل الـ Agents المشار إليها، ويطلب قيم placeholders الناقصة، ثم يبدأ الـ crew.
+
+```jsonc crew.jsonc
+{
+  "name": "Market Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research",
+      "description": "Research {topic} and collect the most relevant facts.",
+      "expected_output": "Structured research notes about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis",
+      "description": "Analyze the research and write a concise report.",
+      "expected_output": "A markdown report with findings and recommendations.",
+      "agent": "analyst",
+      "context": ["research"],
+      "output_file": "output/report.md"
+    }
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
+```
+
+كل عنصر في `agents` يُحل أولًا إلى `agents/<name>.jsonc` ثم إلى `agents/<name>.json`. للـ crews الهرمية، استخدم `"process": "hierarchical"` مع `manager_llm` أو `manager_agent`.
+
+<Warning>
+شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:<name>` ومراجع `{"python": "module.attribute"}` تنفذ كود Python محليًا عند تحميل الـ crew.
+</Warning>
+
+### تهيئة YAML الكلاسيكية
+
+المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew <name> --classic` تستخدم `crew.py` و `config/agents.yaml` و `config/tasks.yaml` والمزيّنات `@CrewBase` و `@agent` و `@task` و `@crew`.
+
+تظل هذه الطريقة مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تحتاج تحكمًا صريحًا عبر decorators.
 
 ```python code
 from crewai import Agent, Crew, Task, Process

docs/ar/concepts/flows.mdx

@@ -226,6 +226,48 @@ counter=2 message='Hello from first_method - updated by second_method'
 من خلال ضمان إعادة مخرجات الدالة الأخيرة وتوفير الوصول إلى الحالة، تجعل تدفقات CrewAI من السهل دمج نتائج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر،
 مع الحفاظ على الوصول إلى الحالة طوال تنفيذ التدفق.
 
+## مقاييس استخدام التدفق
+
+بعد اكتمال تنفيذ التدفق، يمكنك الوصول إلى الخاصية `usage_metrics` لعرض إجمالي استخدام التوكنات عبر **كل استدعاء لنموذج اللغة** يتم خلال التشغيل — بما في ذلك الاستدعاءات من كل فريق (Crew) ينظمه التدفق، والاستدعاءات داخل أدوات الـ Agents، والاستدعاءات المباشرة لـ `LLM.call(...)` من دوال التدفق. هذا هو المكافئ على جانب الـ SDK للإجماليات المعروضة في واجهة CrewAI Enterprise.
+
+```python Code
+from crewai import LLM
+from crewai.flow.flow import Flow, listen, start
+
+class UsageMetricsFlow(Flow):
+    @start()
+    def run_first_crew(self):
+        self.state.first_result = FirstCrew().crew().kickoff()
+
+    @listen(run_first_crew)
+    def call_llm_directly(self):
+        # استدعاء مباشر لنموذج اللغة — يُحسب أيضًا ضمن flow.usage_metrics
+        llm = LLM(model="openai/gpt-4o-mini")
+        self.state.summary = llm.call("لخّص النقاط الرئيسية.")
+
+    @listen(call_llm_directly)
+    def run_second_crew(self):
+        self.state.second_result = SecondCrew().crew().kickoff()
+
+flow = UsageMetricsFlow()
+flow.kickoff()
+
+print(flow.usage_metrics)
+# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
+#              cached_prompt_tokens=0, reasoning_tokens=0,
+#              cache_creation_tokens=0, successful_requests=5)
+```
+
+<Note>
+  `flow.usage_metrics` **ليست** نفس `flow.kickoff().token_usage`. هذه الأخيرة
+  ترجع فقط `CrewOutput.token_usage` لـ **آخر** دالة `@listen` أعادت
+  `CrewOutput`، مما يعني أنها تعكس فقط الفريق الأخير وتتجاهل الفرق السابقة
+  وكذلك أي استدعاءات مباشرة لـ `LLM.call(...)`. استخدم `flow.usage_metrics`
+  كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق.
+</Note>
+
+كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة.
+
 ## إدارة حالة التدفق
 
 إدارة الحالة بفعالية أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي موثوق وقابل للصيانة. توفر تدفقات CrewAI آليات قوية لإدارة الحالة غير المهيكلة والمهيكلة،
@@ -788,7 +830,7 @@ if __name__ == "__main__":
 crewai create flow name_of_flow
 ```
 
-سيولّد هذا الأمر مشروع CrewAI جديد مع هيكل المجلدات اللازم. يتضمن المشروع المولّد فريق Crew مُعد مسبقًا يُسمى `poem_crew` ويعمل بالفعل. يمكنك استخدام هذا الفريق كقالب بنسخه ولصقه وتعديله لإنشاء فرق أخرى.
+سيولّد هذا الأمر مشروع CrewAI جديد مع هيكل المجلدات اللازم. يتضمن المشروع المولّد فريق Crew مُعد مسبقًا يُسمى `poem_crew` ويعمل بالفعل. يستخدم الـ embedded crew الابتدائي بنية Python/YAML الكلاسيكية؛ أما crews المستقلة الجديدة التي تُنشأ عبر `crewai create crew` فتستخدم بنية JSON-first.
 
 ### هيكل المجلدات
 
@@ -818,7 +860,29 @@ crewai create flow name_of_flow
 - `config/tasks.yaml`: يحدد المهام للفريق.
 - `poem_crew.py`: يحتوي على تعريف الفريق، بما في ذلك الـ Agents والمهام والفريق نفسه.
 
-يمكنك نسخ ولصق وتعديل `poem_crew` لإنشاء فرق أخرى.
+يمكنك نسخ ولصق وتعديل `poem_crew` لإنشاء crews كلاسيكية مضمّنة أخرى.
+
+للـ crews المضمّنة بنمط JSON-first، استخدم مجلدًا يحتوي على `crew.jsonc` و `agents/*.jsonc`:
+
+```text
+crews/
+└── research_crew/
+    ├── agents/
+    │   └── researcher.jsonc
+    └── crew.jsonc
+```
+
+ثم حمّلها من خطوة في Flow:
+
+```python
+from pathlib import Path
+from crewai.project import load_crew
+
+crew, default_inputs = load_crew(
+    Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc"
+)
+result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"})
+```
 
 ### ربط فرق Crew في `main.py`
 

docs/ar/concepts/llms.mdx

@@ -107,7 +107,7 @@ mode: "wide"
 </Tabs>
 
 <Info>
-  يوفر CrewAI تكاملات SDK أصلية لـ OpenAI و Anthropic و Google (Gemini API) و Azure و AWS Bedrock -- لا حاجة لتثبيت إضافي بخلاف الملحقات الخاصة بالمزود (مثل `uv add "crewai[openai]"`).
+  يوفر CrewAI تكاملات SDK أصلية لـ OpenAI و Anthropic و Google (Gemini API) و Azure و AWS Bedrock و Snowflake Cortex -- لا حاجة لتثبيت إضافي بخلاف الملحقات الخاصة بالمزود (مثل `uv add "crewai[openai]"`).
 
   جميع المزودين الآخرين مدعومون بواسطة **LiteLLM**. إذا كنت تخطط لاستخدام أي منهم، أضفه كتبعية لمشروعك:
   ```bash
@@ -291,6 +291,55 @@ mode: "wide"
     ```
   </Accordion>
 
+  <Accordion title="Snowflake Cortex">
+    يوفر CrewAI تكاملًا أصليًا مع Snowflake Cortex REST API عبر endpoint Chat Completions المتوافق مع OpenAI. تستخدم نماذج `snowflake/...` هذا المسار بدون fallback إلى LiteLLM. يدعم Snowflake Cortex في CrewAI حاليًا Chat Completions فقط، لذلك استخدم وضع `api` الافتراضي ولا تضبط `api="responses"`.
+
+    ```toml Code
+    # Required
+    SNOWFLAKE_PAT=<your-programmatic-access-token>
+    SNOWFLAKE_ACCOUNT_URL=https://<account-identifier>.snowflakecomputing.com
+
+    # Alternative account configuration
+    SNOWFLAKE_ACCOUNT=<account-identifier>
+    ```
+
+    **الاستخدام الأساسي:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/openai-gpt-4.1",
+        temperature=0.7,
+        max_completion_tokens=1024,
+    )
+    ```
+
+    **نماذج Claude على Cortex:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/claude-sonnet-4-5",
+        max_completion_tokens=1024,
+        stream=True,
+    )
+    ```
+
+    **متغيرات البيئة المدعومة:**
+    - `SNOWFLAKE_PAT` أو `SNOWFLAKE_TOKEN` أو `SNOWFLAKE_JWT`: الرمز المستخدم كاعتماد Bearer
+    - `SNOWFLAKE_ACCOUNT_URL`: عنوان URL الكامل لحساب Snowflake
+    - `SNOWFLAKE_ACCOUNT` أو `SNOWFLAKE_ACCOUNT_ID` أو `SNOWFLAKE_ACCOUNT_IDENTIFIER`: معرف الحساب المستخدم لبناء URL
+
+    تستخدم طلبات Snowflake REST الدور الافتراضي للمستخدم. تأكد من أن هذا الدور لديه `SNOWFLAKE.CORTEX_USER` أو `SNOWFLAKE.CORTEX_REST_API_USER`. لا يتطلب endpoint Cortex REST Chat Completions معاملات database أو schema أو warehouse أو role صريح.
+
+    **الميزات:**
+    - اختيار provider أصلي باستخدام `model="snowflake/<model-name>"`
+    - Chat Completions مع streaming وبدونه فقط؛ `api="responses"` غير مدعوم
+    - تتبع استخدام الرموز
+    - استدعاء الدوال لنماذج OpenAI و Claude المستضافة في Snowflake
+    - إزالة assistant prefill النهائي غير الصالح تلقائيًا لنماذج Claude في Snowflake
+  </Accordion>
+
   <Accordion title="Anthropic">
     يوفر CrewAI تكاملًا أصليًا مع Anthropic من خلال Anthropic Python SDK.
 

docs/ar/concepts/processes.mdx

@@ -16,7 +16,6 @@ mode: "wide"
 
 - **تسلسلي**: ينفذ المهام بالتتابع، مما يضمن إكمال المهام بتقدم منظم.
 - **هرمي**: ينظم المهام في تسلسل إداري هرمي، حيث يتم تفويض المهام وتنفيذها بناءً على سلسلة أوامر منظمة. يجب تحديد نموذج لغة المدير (`manager_llm`) أو وكيل مدير مخصص (`manager_agent`) في الطاقم لتفعيل العملية الهرمية، مما يسهّل إنشاء وإدارة المهام من قبل المدير.
-- **العملية التوافقية (مخطط لها)**: تهدف إلى اتخاذ القرارات بشكل تعاوني بين الوكلاء حول تنفيذ المهام، وتقدم هذه العملية نهجًا ديمقراطيًا لإدارة المهام داخل CrewAI. وهي مخطط لها للتطوير المستقبلي وغير مطبقة حاليًا في قاعدة الكود.
 
 ## دور العمليات في العمل الجماعي
 تُمكّن العمليات الوكلاء الأفراد من العمل كوحدة متماسكة، مما يبسّط جهودهم لتحقيق أهداف مشتركة بكفاءة وتناسق.
@@ -59,9 +58,9 @@ crew = Crew(
 
 ## فئة Process: نظرة عامة مفصلة
 
-تم تنفيذ فئة `Process` كتعداد (`Enum`)، مما يضمن أمان الأنواع ويقيّد قيم العملية على الأنواع المحددة (`sequential`، `hierarchical`). العملية التوافقية مخطط لإدراجها مستقبلاً، مما يؤكد التزامنا بالتطوير والابتكار المستمر.
+تم تنفيذ فئة `Process` كتعداد (`Enum`)، مما يضمن أمان الأنواع ويقيّد قيم العملية على الأنواع المحددة (`sequential`، `hierarchical`).
 
 ## الخلاصة
 
 التعاون المنظم الذي تسهّله العمليات داخل CrewAI ضروري لتمكين العمل الجماعي المنهجي بين الوكلاء.
-تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات والتكامل المخطط للعملية التوافقية، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً.
+تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً.

docs/ar/concepts/tasks.mdx

@@ -73,13 +73,48 @@ crew = Crew(
 
 ## إنشاء المهام
 
-هناك طريقتان لإنشاء المهام في CrewAI: باستخدام **إعداد YAML (موصى به)** أو تعريفها **مباشرة في الكود**.
+هناك طريقتان شائعتان لإنشاء المهام في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفها **مباشرة في الكود**.
 
-### إعداد YAML (موصى به)
+### تهيئة JSONC (موصى بها)
 
-يوفر استخدام إعداد YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف المهام. نوصي بشدة باستخدام هذا النهج لتعريف المهام في مشاريع CrewAI.
+المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` تعرّف المهام في `crew.jsonc`.
 
-بعد إنشاء مشروع CrewAI كما هو موضح في قسم [التثبيت](/ar/installation)، انتقل إلى ملف `src/latest_ai_development/config/tasks.yaml` وعدّل القالب ليتوافق مع متطلبات مهامك المحددة.
+````jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "reporting_analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research about {topic}.",
+      "expected_output": "A list of the most relevant information about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "reporting_task",
+      "description": "Review the research and expand it into a detailed report.",
+      "expected_output": "A polished markdown report.",
+      "agent": "reporting_analyst",
+      "context": ["research_task"],
+      "markdown": true,
+      "output_file": "report.md"
+    }
+  ],
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
+````
+
+كل مهمة تحتاج إلى `description` و `expected_output`. يجب أن يطابق `agent` اسم Agent مذكورًا في `agents`. يشير `context` إلى أسماء مهام سابقة فقط؛ وترفض الإشارات إلى مهام لاحقة.
+
+### إعداد YAML الكلاسيكي
+
+المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew <name> --classic` تستخدم `config/tasks.yaml` وفئة `@CrewBase` في `crew.py`.
+
+يظل إعداد YAML مدعومًا للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف المهام من خلال فئة `@CrewBase`.
+
+بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف `src/<project_name>/config/tasks.yaml` وعدّل القالب ليتوافق مع متطلبات مهامك المحددة.
 
 <Note>
 المتغيرات في ملفات YAML (مثل `{topic}`) سيتم استبدالها بالقيم من مدخلاتك عند تشغيل الفريق:
@@ -115,7 +150,7 @@ reporting_task:
 لاستخدام إعداد YAML هذا في كودك، أنشئ فئة فريق ترث من `CrewBase`:
 
 ```python crew.py
-# src/latest_ai_development/crew.py
+# src/<project_name>/crew.py
 
 from crewai import Agent, Crew, Process, Task
 from crewai.project import CrewBase, agent, crew, task

docs/ar/enterprise/features/agent-control-plane/monitoring.mdx

@@ -6,6 +6,14 @@ icon: "gauge"
 mode: "wide"
 ---
 
+<Info>
+  **تنقل وثائق ACP (إصدار تجريبي)**
+
+  - [نظرة عامة](/ar/enterprise/features/agent-control-plane/overview)
+  - **المراقبة** *(أنت هنا)*
+  - [القواعد](/ar/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## نظرة عامة
 
 تبويب **Automations** هو عرض العمليات للقراءة فقط في [Agent Control Plane](/ar/enterprise/features/agent-control-plane/overview). يجمع بين بطاقتَي مقاييس و sankey تفاعلي وجدولين فرعيين — **Automations** و **Consumption** — يمكنك البحث والتصفية والفرز فيهما.

docs/ar/enterprise/features/agent-control-plane/overview.mdx

@@ -5,6 +5,14 @@ sidebarTitle: نظرة عامة
 icon: "book-open"
 ---
 
+<Info>
+  **تنقل وثائق ACP (إصدار تجريبي)**
+
+  - **نظرة عامة** *(أنت هنا)*
+  - [المراقبة](/ar/enterprise/features/agent-control-plane/monitoring)
+  - [القواعد](/ar/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## نظرة عامة
 
 **Agent Control Plane** (ACP) هو مركز العمليات لكل ما يعمل لديك على CrewAI AMP. إنها شاشة واحدة — مقسّمة إلى تبويبَي **Automations** و **Rules** — تمنح فريقك القدرة على:

docs/ar/enterprise/features/agent-control-plane/rules.mdx

@@ -6,6 +6,14 @@ icon: "shield-check"
 mode: "wide"
 ---
 
+<Info>
+  **تنقل وثائق ACP (إصدار تجريبي)**
+
+  - [نظرة عامة](/ar/enterprise/features/agent-control-plane/overview)
+  - [المراقبة](/ar/enterprise/features/agent-control-plane/monitoring)
+  - **القواعد** *(أنت هنا)*
+</Info>
+
 ## نظرة عامة
 
 تتيح لك القواعد تطبيق سياسات — اليوم: **PII Redaction** — عبر العديد من الأتمتات دفعة واحدة، بدلاً من ضبط كل deployment على حدة. افتح تبويب **Rules** في [Agent Control Plane](/ar/enterprise/features/agent-control-plane/overview) لإدارتها.

docs/ar/enterprise/features/secrets-manager/verify-rotation.mdx

@@ -26,10 +26,10 @@ icon: "arrows-rotate"
 
 ## الخطوة 1 — هيكلة طاقم التحقق
 
-أنشئ مشروع طاقم جديد. يُهيكل CrewAI CLI البنية:
+أنشئ مشروع crew كلاسيكيًا لأن هذا المثال يربط أداة Python عبر `crew.py`:
 
 ```bash
-crewai create crew rotation_verifier --skip_provider
+crewai create crew rotation_verifier --classic --skip_provider
 cd rotation_verifier
 ```
 

docs/ar/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ mode: "wide"
 
 1. في CrewAI AMP، انتقل إلى **Settings** > **OpenTelemetry Collectors**.
 2. انقر على **Add Collector**.
-3. اختر نوع التكامل — **OpenTelemetry Traces** أو **OpenTelemetry Logs**.
-4. هيّئ الاتصال:
-   - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`).
-   - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة.
-   - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة.
-   - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها.
-5. انقر على **Save**.
+3. اختر تكاملاً:
+   - **OpenTelemetry Traces** و**OpenTelemetry Logs** — صدّر إلى أي مجمّع أو واجهة خلفية متوافقة مع OTLP.
+   - **Datadog** — أرسل التتبعات مباشرة إلى استقبال OTLP الخاص بـ Datadog، دون الحاجة إلى مجمّع منفصل أو Datadog Agent.
+4. هيّئ الاتصال. تعتمد الحقول على التكامل الذي اخترته:
 
-<Frame>![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    إن **OpenTelemetry Traces** و**OpenTelemetry Logs** تكاملان منفصلان يتشاركان نفس الحقول — اختر التكامل المطابق للإشارة التي تريد تصديرها.
+
+    - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`).
+    - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة.
+    - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة.
+    - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها.
+
+    <Frame>![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — مضيف OTLP لموقع Datadog الخاص بك فقط، دون بروتوكول أو مسار. يقوم CrewAI ببناء نقطة نهاية HTTPS OTLP الكاملة نيابةً عنك. استخدم المضيف المطابق لـ [موقع Datadog](https://docs.datadoghq.com/getting_started/site/) الخاص بك:
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — مفتاح واجهة برمجة تطبيقات Datadog الخاص بك. راجع [كيفية إنشاء واحد](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+
+    يصدّر تكامل Datadog **التتبعات**.
+
+    <Frame>![تهيئة مجمّع Datadog](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(اختياري)* انقر على **Test Connection** للتحقق من قدرة CrewAI على الوصول إلى نقطة النهاية باستخدام بيانات الاعتماد التي قدمتها.
+6. انقر على **Save**.
 
 <Tip>
   يمكنك إضافة مجمّعات متعددة — على سبيل المثال، واحد للتتبعات وآخر للسجلات، أو الإرسال إلى واجهات خلفية مختلفة لأغراض مختلفة.

docs/ar/enterprise/guides/deploy-to-amp.mdx

@@ -164,6 +164,12 @@ crewai deploy remove <deployment_id>
       ![اختيار المستودع](/images/enterprise/select-repo.png)
     </Frame>
 
+    <Tip>
+      إذا كان Crew أو Flow داخل مجلد فرعي في monorepo، فوسّع **Advanced**
+      وعيّن دليل عمل قبل النشر. راجع
+      [النشر من Monorepo](/ar/enterprise/guides/monorepo-deployments).
+    </Tip>
+
   </Step>
 
   <Step title="تعيين متغيرات البيئة">
@@ -368,17 +374,17 @@ git push
 
 **الحل**: تحقق من أن مشروعك يتطابق مع البنية المتوقعة:
 
-- **كل من الطواقم والتدفقات**: يجب أن تكون نقطة الدخول في `src/project_name/main.py`
-- **الطواقم**: تستخدم دالة `run()` كنقطة دخول
-- **التدفقات**: تستخدم دالة `kickoff()` كنقطة دخول
+- **JSON-first Crews**: أبقِ `crew.jsonc` أو `crew.json` و `agents/` في جذر المشروع
+- **Crews كلاسيكية**: استخدم `src/project_name/main.py` مع دالة دخول `run()`
+- **Flows**: استخدم `src/project_name/main.py` مع دالة دخول `kickoff()`
 
 راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment) لمخططات البنية المفصلة.
 
-#### مُزخرف CrewBase مفقود
+#### مُزخرف CrewBase مفقود في crew كلاسيكية
 
 **العرض**: أخطاء "Crew not found" أو "Config not found" أو أخطاء تهيئة الوكيل/المهمة
 
-**الحل**: تأكد من أن **جميع** فئات الطاقم تستخدم مُزخرف `@CrewBase`:
+**الحل**: في crews الكلاسيكية Python/YAML، تأكد من أن جميع فئات الـ crew تستخدم مُزخرف `@CrewBase`. لا تحتاج crews بنمط JSON-first إلى هذا المزخرف.
 
 ```python
 from crewai.project import CrewBase, agent, crew, task
@@ -398,8 +404,8 @@ class YourCrew():
 ```
 
 <Info>
-  ينطبق هذا على الطواقم المستقلة والطواقم المضمنة داخل مشاريع التدفق.
-  كل فئة طاقم تحتاج المُزخرف.
+  ينطبق هذا على فئات crew الكلاسيكية المكتوبة في Python، بما في ذلك crews الكلاسيكية المضمنة داخل مشاريع Flow.
+  يتم التحقق من crews بنمط JSON-first من `crew.jsonc` و `agents/` بدلاً من ذلك.
 </Info>
 
 #### نوع pyproject.toml غير صحيح
@@ -436,8 +442,8 @@ type = "flow"
 **الحل**:
 1. تحقق من سجلات التنفيذ في لوحة تحكم AMP (علامة تبويب Traces)
 2. تحقق من أن جميع الأدوات لديها مفاتيح API المطلوبة مُهيأة
-3. تأكد من صحة تهيئات الوكلاء في `agents.yaml`
-4. تحقق من تهيئات المهام في `tasks.yaml` بحثاً عن أخطاء الصياغة
+3. في crews بنمط JSON-first، تحقق من `crew.jsonc` والملفات المشار إليها داخل `agents/`
+4. في crews الكلاسيكية، تأكد من صحة `agents.yaml` و `tasks.yaml`
 
 <Card title="تحتاج مساعدة؟" icon="headset" href="mailto:support@crewai.com">
   تواصل مع فريق الدعم للمساعدة في مشاكل النشر أو أسئلة حول

docs/ar/enterprise/guides/monorepo-deployments.mdx

@@ -0,0 +1,224 @@
+---
+title: "النشر من Monorepo"
+description: "انشر Crew أو Flow من مجلد فرعي داخل مستودع أكبر"
+icon: "folder-tree"
+mode: "wide"
+---
+
+<Note>
+  استخدم دليل عمل عندما يكون Crew أو Flow داخل مستودع أكبر. يتحقق CrewAI AMP
+  من الأتمتة ويبنيها ويشغلها من ذلك المجلد الفرعي بدلاً من جذر المستودع.
+</Note>
+
+## متى تستخدم ذلك
+
+يكون النشر من monorepo مفيداً عندما يحتوي مستودع واحد على عدة أتمتات أو حزم
+مشتركة أو كود تطبيقات آخر:
+
+```text
+company-ai/
+|-- uv.lock
+|-- packages/
+|   `-- shared_tools/
+`-- crews/
+    |-- support_agent/
+    |   |-- pyproject.toml
+    |   |-- crew.jsonc
+    |   `-- agents/
+    |       `-- support_agent.jsonc
+    `-- research_flow/
+        |-- pyproject.toml
+        `-- src/
+            `-- research_flow/
+                `-- main.py
+```
+
+لنشر `support_agent`، اضبط دليل العمل على:
+
+```text
+crews/support_agent
+```
+
+لا يزال AMP يجلب المستودع كاملاً أو يرفعه، لكنه يتعامل مع المجلد المحدد كجذر
+مشروع الأتمتة.
+
+## ما الذي يتحكم به دليل العمل
+
+عند تعيين دليل عمل، يستخدم AMP ذلك المجلد من أجل:
+
+- التحقق من المشروع، بما في ذلك `pyproject.toml` وملفات crew JSON وأي نقطة دخول كلاسيكية لـ Crew أو Flow
+- تثبيت الاعتماديات باستخدام `uv`
+- دليل العمل للعملية قيد التشغيل
+- متغير البيئة `CREW_ROOT_DIR`
+
+ترك الحقل فارغاً يحافظ على السلوك الحالي ويستخدم جذر المستودع.
+
+## المصادر المدعومة
+
+يمكنك تعيين دليل عمل عند إنشاء نشر من:
+
+- مستودع GitHub متصل
+- مستودع Git مكوّن في AMP
+- رفع ملف ZIP
+
+<Info>
+  اضبط أدلة العمل من واجهة AMP على الويب. لا يطلب تدفق CLI
+  `crewai deploy create` هذا الحقل.
+</Info>
+
+يمكنك أيضاً إضافة دليل العمل أو تغييره في نشر موجود من صفحة **Settings** الخاصة
+بالنشر. يسري التغيير في النشر التالي.
+
+<Warning>
+  لا يمكن استخدام أدلة العمل وauto-deploy معاً. إذا كان للنشر دليل عمل، يتم
+  تعطيل auto-deploy لذلك النشر. أوقف auto-deploy قبل تعيين دليل عمل.
+</Warning>
+
+## إعداد نشر جديد
+
+<Steps>
+  <Step title="افتح Deploy from Code">
+    في CrewAI AMP، أنشئ نشراً جديداً واختر المصدر: GitHub أو Git Repository أو
+    رفع ZIP.
+  </Step>
+
+  <Step title="اختر المستودع أو الفرع أو ملف ZIP">
+    اختر المستودع والفرع اللذين يحتويان على monorepo، أو ارفع ملف ZIP يحتوي
+    جذره على محتويات monorepo.
+  </Step>
+
+  <Step title="افتح الإعدادات المتقدمة">
+    وسّع قسم **Advanced** في نموذج النشر.
+  </Step>
+
+  <Step title="أدخل دليل العمل">
+    أدخل المسار من جذر المستودع إلى مشروع Crew أو Flow:
+
+    ```text
+    crews/support_agent
+    ```
+
+    لا تضف شرطة مائلة في البداية.
+  </Step>
+
+  <Step title="انشر">
+    أضف أي متغيرات بيئة مطلوبة، ثم ابدأ النشر.
+  </Step>
+</Steps>
+
+## إعداد نشر موجود
+
+<Steps>
+  <Step title="افتح إعدادات النشر">
+    انتقل إلى الأتمتة في AMP وافتح **Settings**.
+  </Step>
+
+  <Step title="أوقف auto-deploy إذا لزم الأمر">
+    إذا كان auto-deploy مفعلاً، أوقفه أولاً. لا يكون حقل دليل العمل متاحاً
+    أثناء تشغيل auto-deploy.
+  </Step>
+
+  <Step title="عيّن دليل العمل">
+    في **Basic settings**، أدخل مسار المجلد الفرعي، مثل:
+
+    ```text
+    crews/support_agent
+    ```
+  </Step>
+
+  <Step title="أعد النشر">
+    احفظ الإعداد وأعد نشر الأتمتة. سيتم استخدام دليل العمل الجديد في النشر
+    التالي.
+  </Step>
+</Steps>
+
+## قواعد المسار
+
+يجب أن يكون دليل العمل مساراً نسبياً داخل جذر المستودع أو ZIP.
+
+| القاعدة | المثال |
+|---------|--------|
+| استخدم مساراً نسبياً | `crews/support_agent` |
+| لا تبدأ بـ `/` | `/crews/support_agent` غير صالح |
+| لا تستخدم مقاطع المسار `.` أو `..` | `crews/../support_agent` غير صالح |
+| استخدم الأحرف والأرقام والشرطات والشرطات السفلية والنقاط والشرطات المائلة فقط | `crews/support agent` غير صالح |
+| اجعل المسار 255 حرفاً أو أقل | يتم رفض المسارات الأطول |
+
+يزيل AMP المسافات البيضاء في البداية والنهاية، ويضغط الشرطات المائلة المتكررة،
+ويزيل الشرطة المائلة النهائية. تستخدم القيمة الفارغة جذر المستودع.
+
+## ملفات القفل وUV Workspaces
+
+يجب أن يحتوي المجلد المحدد على `pyproject.toml` وملفات المشروع المناسبة لنوع
+الأتمتة:
+
+- crew بنمط JSON-first: ملف `crew.jsonc` أو `crew.json` مع مجلد `agents/`
+- Crew كلاسيكي أو Flow: مجلد `src/` مع نقطة دخول Python المتوقعة
+
+يمكن أن يوجد ملف `uv.lock` أو `poetry.lock` إما في المجلد المحدد أو في جذر
+المستودع.
+
+يدعم هذا تخطيطي ملفات القفل الشائعين:
+
+<Tabs>
+  <Tab title="ملف قفل المشروع">
+    ```text
+    company-ai/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- uv.lock
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+
+  <Tab title="ملف قفل workspace">
+    ```text
+    company-ai/
+    |-- uv.lock
+    |-- packages/
+    |   `-- shared_tools/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+</Tabs>
+
+<Tip>
+  إذا كانت الأتمتة تستورد حزماً مشتركة من مكان آخر في monorepo، فصرّح بهذه
+  الحزم في `pyproject.toml` باستخدام إعدادات UV workspace أو path أو source.
+  يشغل AMP الأتمتة من المجلد المحدد، لذلك يجب تثبيت الكود المشترك كاعتمادية
+  بدلاً من الاعتماد على وجود جذر المستودع في Python path.
+</Tip>
+
+## استكشاف الأخطاء وإصلاحها
+
+### لم يتم العثور على دليل العمل
+
+تحقق من أن المسار نسبي إلى جذر المستودع أو ZIP. بالنسبة لرفع ZIP، يجب أن
+تتضمن محتويات ZIP مسار دليل العمل تماماً كما أدخلته.
+
+### pyproject.toml مفقود
+
+يجب أن يشير دليل العمل إلى مجلد مشروع Crew أو Flow، وليس فقط إلى مجلد أب
+يحتوي على عدة مشاريع.
+
+### uv.lock أو poetry.lock مفقود
+
+اعمل commit لملف قفل إما في مجلد المشروع المحدد أو في جذر المستودع. بالنسبة
+إلى UV workspaces، يتم دعم إبقاء `uv.lock` في جذر workspace.
+
+### Auto-Deploy غير متاح
+
+يتم تعطيل auto-deploy أثناء تعيين دليل عمل. استخدم إعادة النشر اليدوية أو شغّل
+إعادة النشر من CI/CD باستخدام AMP API.
+
+<Card title="النشر على AMP" icon="rocket" href="/ar/enterprise/guides/deploy-to-amp">
+  تابع دليل النشر بعد اختيار دليل عمل monorepo.
+</Card>

docs/ar/enterprise/guides/prepare-for-deployment.mdx

@@ -24,7 +24,7 @@ mode: "wide"
 
 <CardGroup cols={2}>
   <Card title="مشاريع الطاقم" icon="users">
-    فرق وكلاء ذكاء اصطناعي مستقلة مع `crew.py` يحدد الوكلاء والمهام. الأفضل للمهام المركزة والتعاونية.
+    فرق وكلاء ذكاء اصطناعي مستقلة. الـ crews الجديدة تستخدم بنية JSON-first مع `crew.jsonc` و `agents/`؛ ويمكن للـ crews الكلاسيكية الاستمرار في استخدام `crew.py`.
   </Card>
   <Card title="مشاريع التدفق" icon="diagram-project">
     سير عمل مُنسّق مع طواقم مضمنة في مجلد `crews/`. الأفضل للعمليات المعقدة متعددة المراحل.
@@ -33,19 +33,19 @@ mode: "wide"
 
 | الجانب | الطاقم | التدفق |
 |--------|--------|--------|
-| **بنية المشروع** | `src/project_name/` مع `crew.py` | `src/project_name/` مع مجلد `crews/` |
-| **موقع المنطق الرئيسي** | `src/project_name/crew.py` | `src/project_name/main.py` (فئة Flow) |
-| **دالة نقطة الدخول** | `run()` في `main.py` | `kickoff()` في `main.py` |
+| **بنية المشروع** | جذر المشروع مع `crew.jsonc` و `agents/` | `src/project_name/` مع مجلد `crews/` |
+| **موقع المنطق الرئيسي** | `crew.jsonc` (كلاسيكي: `src/project_name/crew.py`) | `src/project_name/main.py` (فئة Flow) |
+| **دالة نقطة الدخول** | تُحمّل من `crew.jsonc` (كلاسيكي: `run()` في `main.py`) | `kickoff()` في `main.py` |
 | **نوع pyproject.toml** | `type = "crew"` | `type = "flow"` |
 | **أمر CLI للإنشاء** | `crewai create crew name` | `crewai create flow name` |
-| **موقع التهيئة** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` |
+| **موقع التهيئة** | `crew.jsonc` و `agents/` و `tools/` اختياريًا | `src/project_name/crews/crew_name/config/` أو مجلدات crew JSON مضمنة |
 | **يمكن أن يحتوي طواقم أخرى** | لا | نعم (في مجلد `crews/`) |
 
 ## مرجع بنية المشروع
 
 ### بنية مشروع الطاقم
 
-عند تشغيل `crewai create crew my_crew`، تحصل على هذه البنية:
+عند تشغيل `crewai create crew my_crew`، تحصل على بنية JSON-first:
 
 ```
 my_crew/
@@ -54,24 +54,25 @@ my_crew/
 ├── README.md
 ├── .env
 ├── uv.lock                  # REQUIRED for deployment
-└── src/
-    └── my_crew/
-        ├── __init__.py
-        ├── main.py          # Entry point with run() function
-        ├── crew.py          # Crew class with @CrewBase decorator
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml  # Agent definitions
-            └── tasks.yaml   # Task definitions
+├── crew.jsonc               # إعدادات الـ crew والمهام والعملية والمدخلات
+├── agents/
+│   └── researcher.jsonc     # تعريفات الـ Agents
+├── tools/                   # أدوات custom:<name> اختيارية
+├── knowledge/
+└── skills/
 ```
 
 <Warning>
-  بنية `src/project_name/` المتداخلة ضرورية للطواقم.
-  وضع الملفات في المستوى الخاطئ سيسبب فشل النشر.
+  في crews بنمط JSON-first، أبقِ `crew.jsonc` و `agents/` و `tools/` و `knowledge/` و `skills/`
+  في جذر المشروع. وضعها داخل `src/` يمنع `crewai run` والتحقق قبل النشر من العثور على تعريف الـ crew.
 </Warning>
 
+<Info>
+  المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew my_crew --classic` تستخدم البنية القديمة
+  `src/project_name/crew.py` و `src/project_name/config/agents.yaml` و
+  `src/project_name/config/tasks.yaml`. تظل هذه البنية مدعومة للـ crews المكتوبة في Python مع decorators.
+</Info>
+
 ### بنية مشروع التدفق
 
 عند تشغيل `crewai create flow my_flow`، تحصل على هذه البنية:
@@ -100,9 +101,9 @@ my_flow/
 ```
 
 <Info>
-  كلا الطواقم والتدفقات تستخدم بنية `src/project_name/`.
-  الفرق الرئيسي أن التدفقات لها مجلد `crews/` للطواقم المضمنة،
-  بينما الطواقم لها `crew.py` مباشرة في مجلد المشروع.
+  الـ crews المستقلة بنمط JSON-first تستخدم ملفات JSON في جذر المشروع. أما Flows فتظل تستخدم
+  `src/project_name/` ويمكن أن تحتوي crews مضمنة كلاسيكية أو مجلدات crew JSON يتم تحميلها عبر
+  `crewai.project.load_crew`.
 </Info>
 
 ## قائمة فحص ما قبل النشر
@@ -154,60 +155,89 @@ git commit -m "Add uv.lock for deployment"
 git push
 ```
 
-### 3. التحقق من استخدام مُزخرف CrewBase
+### 3. التحقق من تعريف الـ Crew
 
-**يجب أن تستخدم كل فئة طاقم مُزخرف `@CrewBase`.** ينطبق هذا على:
+<Tabs>
+  <Tab title="JSON-first Crews">
+    يجب أن تحتوي crews بنمط JSON-first على `crew.jsonc` أو `crew.json` في جذر المشروع.
+    يجب أن يشير مصفوفة `agents` إلى ملفات داخل `agents/`، ويجب أن تشير كل task إلى اسم Agent صحيح.
 
-- مشاريع الطاقم المستقلة
-- الطواقم المضمنة داخل مشاريع التدفق
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "Research {topic}.",
+          "expected_output": "A concise report.",
+          "agent": "researcher"
+        }
+      ],
+      "inputs": {
+        "topic": "AI Agents"
+      }
+    }
+    ```
 
-```python
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+    تُشار الأدوات المخصصة بصيغة `"custom:<name>"` ويجب تنفيذها في
+    `tools/<name>.py` كصنف يرث من `BaseTool`.
+  </Tab>
+  <Tab title="Crews كلاسيكية Python/YAML">
+    يجب أن تستخدم الـ crews الكلاسيكية وPython crews المضمنة داخل Flows مزخرف `@CrewBase`.
 
-@CrewBase  # This decorator is REQUIRED
-class MyCrew():
-    """My crew description"""
+    ```python
+    from crewai import Agent, Crew, Process, Task
+    from crewai.project import CrewBase, agent, crew, task
+    from crewai.agents.agent_builder.base_agent import BaseAgent
+    from typing import List
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
+    @CrewBase
+    class MyCrew():
+        """My crew description"""
 
-    @agent
-    def my_agent(self) -> Agent:
-        return Agent(
-            config=self.agents_config['my_agent'],  # type: ignore[index]
-            verbose=True
-        )
+        agents: List[BaseAgent]
+        tasks: List[Task]
 
-    @task
-    def my_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['my_task']  # type: ignore[index]
-        )
+        @agent
+        def my_agent(self) -> Agent:
+            return Agent(
+                config=self.agents_config['my_agent'],  # type: ignore[index]
+                verbose=True
+            )
 
-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
+        @task
+        def my_task(self) -> Task:
+            return Task(
+                config=self.tasks_config['my_task']  # type: ignore[index]
+            )
 
-<Warning>
-  إذا نسيت مُزخرف `@CrewBase`، سيفشل النشر بأخطاء حول
-  تهيئات الوكلاء أو المهام المفقودة.
-</Warning>
+        @crew
+        def crew(self) -> Crew:
+            return Crew(
+                agents=self.agents,
+                tasks=self.tasks,
+                process=Process.sequential,
+                verbose=True,
+            )
+    ```
+  </Tab>
+</Tabs>
 
 ### 4. التحقق من نقاط دخول المشروع
 
-كل من الطواقم والتدفقات لها نقطة دخول في `src/project_name/main.py`:
+لا تحتاج crews المستقلة بنمط JSON-first إلى ملف `src/project_name/main.py` مكتوب يدويًا؛
+يقوم `crewai run` وتغليف النشر بتحميل `crew.jsonc` مباشرة. تستخدم crews الكلاسيكية وFlows نقاط دخول Python:
 
 <Tabs>
-  <Tab title="للطواقم">
+  <Tab title="JSON-first Crews">
+    شغّل محليًا من جذر المشروع:
+
+    ```bash
+    crewai run
+    ```
+  </Tab>
+  <Tab title="Crews كلاسيكية">
     تستخدم نقطة الدخول دالة `run()`:
 
     ```python
@@ -278,16 +308,17 @@ grep -A2 "\[tool.crewai\]" pyproject.toml
 # 2. Verify uv.lock exists
 ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'"
 
-# 3. Verify src/ structure exists
-ls -la src/*/main.py 2>/dev/null || echo "No main.py found in src/"
+# 3. For JSON-first crews, verify crew.jsonc and agents/
+([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found"
+test -d agents || echo "No agents/ directory found"
 
-# 4. For Crews - verify crew.py exists
+# 4. For classic Crews - verify crew.py exists
 ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)"
 
 # 5. For Flows - verify crews/ folder exists
 ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)"
 
-# 6. Check for CrewBase usage
+# 6. For classic Python crews - check for CrewBase usage
 grep -r "@CrewBase" . --include="*.py"
 ```
 
@@ -297,8 +328,9 @@ grep -r "@CrewBase" . --include="*.py"
 |-------|-------|---------|
 | `uv.lock` مفقود | فشل البناء أثناء حل الاعتماديات | شغّل `uv lock` وارفعه |
 | `type` خاطئ في pyproject.toml | نجاح البناء لكن فشل وقت التشغيل | غيّر إلى النوع الصحيح |
-| مُزخرف `@CrewBase` مفقود | أخطاء "Config not found" | أضف المُزخرف لجميع فئات الطاقم |
-| ملفات في الجذر بدل `src/` | نقطة الدخول غير موجودة | انقلها إلى `src/project_name/` |
+| `crew.jsonc` أو `agents/` مفقود في crew بنمط JSON-first | لا يمكن العثور على تعريف الـ crew | أبقِ `crew.jsonc` و `agents/` في جذر المشروع |
+| مُزخرف `@CrewBase` مفقود في crew كلاسيكية | أخطاء "Config not found" | أضف المُزخرف لجميع فئات الـ crew الكلاسيكية |
+| ملفات كلاسيكية في الجذر بدل `src/` | نقطة الدخول غير موجودة | انقل ملفات Python الكلاسيكية إلى `src/project_name/` |
 | `run()` أو `kickoff()` مفقودة | لا يمكن بدء الأتمتة | أضف دالة الدخول الصحيحة |
 
 ## الخطوات التالية

docs/ar/enterprise/integrations/databricks.mdx

@@ -0,0 +1,123 @@
+---
+title: تكامل Databricks
+description: "اربط وكلاء CrewAI بـ Databricks Genie وSQL وUnity Catalog Functions وVector Search عبر خوادم MCP المُدارة من Databricks."
+icon: "layer-group"
+mode: "wide"
+---
+
+## نظرة عامة
+
+اربط وكلاء CrewAI مباشرةً بمساحة عمل Databricks الخاصة بك عبر [خوادم MCP المُدارة من Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). يتيح تكامل Databricks لوكلائك طرح أسئلة بلغة طبيعية باستخدام **Genie**، وتنفيذ **SQL** خاضع للحوكمة، واستدعاء **Unity Catalog Functions**، واسترجاع المستندات باستخدام **Vector Search** — كل ذلك دون كتابة أو استضافة أي كود موصِّل، مع تطبيق أذونات Unity Catalog في كل استدعاء.
+
+في الخلفية، يُعدّ تكامل Databricks غلافًا مُدارًا حول دعم [خوادم MCP المخصصة](/ar/enterprise/guides/custom-mcp-server) في CrewAI. تكشف Databricks عن كل قدرة كنقطة نهاية [Model Context Protocol](https://modelcontextprotocol.io/) خاصة بها، ويتصل بها CrewAI بأمان نيابةً عنك. ولأن كل خادم يُضاف بشكل منفصل، يمكنك تفعيل القدرات التي تحتاجها فرقك (crews) بالضبط.
+
+## القدرات الرئيسية
+
+<CardGroup cols={2}>
+  <Card title="Genie" icon="comments">
+    اطرح أسئلة بلغة طبيعية واحصل على إجابات مستندة إلى بياناتك باستخدام [Genie](https://docs.databricks.com/aws/en/genie/)، الذي يستعلم من Genie Spaces وUnity Catalog ويوفّر روابط تعود إلى واجهة Databricks.
+  </Card>
+  <Card title="Databricks SQL" icon="database">
+    نفّذ SQL خاضعًا للحوكمة على مستودعات Databricks لديك للاستعلام عن البيانات وتحويلها وإنشاء خطوط أنابيب البيانات مباشرةً من وكلائك.
+  </Card>
+  <Card title="Unity Catalog Functions" icon="function">
+    استدعِ [دوال Unity Catalog](https://docs.databricks.com/aws/en/udf/unity-catalog) لتنفيذ SQL مُعرّف مسبقًا ومنطق أعمال مخصّص كأدوات قابلة لإعادة الاستخدام وخاضعة للحوكمة.
+  </Card>
+  <Card title="Vector Search" icon="magnifying-glass">
+    استرجع المستندات ذات الصلة لسير عمل RAG والمعرفة من فهارس [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) باستخدام التشابه الدلالي.
+  </Card>
+</CardGroup>
+
+تعمل جميع الخوادم خلف Unity AI Gateway وتطبّق ضوابط الوصول في Unity Catalog، بحيث لا يرى وكلاؤك سوى البيانات والأدوات المصرَّح لهم باستخدامها.
+
+## المتطلبات المسبقة
+
+قبل استخدام تكامل Databricks، تأكّد من توفّر ما يلي:
+
+- حساب [CrewAI AMP](https://app.crewai.com) باشتراك نشط
+- مساحة عمل Databricks تحتوي على القدرات التي تريد كشفها (Genie Spaces، مستودعات SQL، دوال Unity Catalog، أو فهارس Vector Search)
+- [امتيازات Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog) المناسبة على الكائنات الأساسية
+- اسم مضيف مساحة عمل Databricks الخاص بك (مثال: `your-workspace.cloud.databricks.com`)
+
+## خوادم MCP المُدارة من Databricks
+
+تنشر Databricks خادم MCP مُدارًا منفصلًا لكل قدرة. يكشف CrewAI عنها كاتصالات فردية، يُهيَّأ كل منها باستخدام مضيف مساحة العمل ومعرّفات Unity Catalog ذات الصلة. تتبع نقاط النهاية الأنماط التالية:
+
+| الخادم | الوظيفة | نمط عنوان MCP |
+|--------|---------|---------------|
+| **Genie** | أسئلة وأجوبة بلغة طبيعية على Genie Space | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
+| **Databricks SQL** | تنفيذ SQL على مستودعاتك | `https://<workspace-hostname>/api/2.0/mcp/sql` |
+| **Unity Catalog Functions** | تشغيل دوال UC المسجّلة | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
+| **Vector Search** | الاستعلام من فهرس Vector Search | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
+
+<Note>
+لا حاجة لإنشاء عناوين URL هذه يدويًا — يُنشئ CrewAI كل نقطة نهاية من مضيف مساحة العمل والمعرّفات (Genie Space ID، أو catalog/schema) التي تقدّمها عند تهيئة الاتصال. للاطّلاع على المواصفات الكاملة وأحدث تفاصيل نقاط النهاية، راجع [وثائق MCP المُدارة من Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp).
+</Note>
+
+## ربط Databricks في CrewAI AMP
+
+<Frame>
+    <img src="/images/enterprise/databricks-configure.png" alt="تهيئة خادم MCP مُدار من Databricks في CrewAI AMP" />
+</Frame>
+
+تظهر كل قدرة من قدرات Databricks — **Databricks Genie** و**Databricks SQL** و**Databricks Unity Catalog Functions** و**Databricks Vector Search** — كخادم MCP خاص بها ضمن مجموعة Databricks في صفحة **Tools & Integrations**. هيّئ ما تحتاجه:
+
+<Steps>
+    <Step title="افتح Tools & Integrations">
+        انتقل إلى **Tools & Integrations** في الشريط الجانبي الأيسر في CrewAI AMP وحدِّد مجموعة **Databricks** في قائمة Connections. سترى خوادم Genie وSQL وUnity Catalog Functions وVector Search مُدرجة أسفلها.
+    </Step>
+
+    <Step title="هيّئ خادمًا">
+        انقر على **Configure** بجوار القدرة التي تريد تفعيلها وقدّم تفاصيل الاتصال الخاصة بها:
+
+        - **Workspace Host** — اسم مضيف مساحة عمل Databricks الخاص بك (مثال: `my-workspace.cloud.databricks.com`).
+        - **Genie** — **Genie Space ID** المراد الاستعلام عنه.
+        - **Unity Catalog Functions** — الـ **catalog** والـ **schema** اللذان يحتويان على دوالك.
+        - **Vector Search** — الـ **catalog** والـ **schema** اللذان يحتويان على الفهرس.
+        - **Databricks SQL** — لا توجد معرّفات إضافية؛ تُنفَّذ الاستعلامات على مستودعات SQL في مساحة عملك.
+    </Step>
+
+    <Step title="اختر طريقة المصادقة">
+        اختر كيف يصادق CrewAI على Databricks. يُوصى باستخدام **OAuth**.
+
+        - **Use OAuth** — اتصل بأمان باستخدام OAuth 2.0. يصادق كل مستخدم على حدة، وتُصدر Databricks رموزًا (tokens) محدّدة النطاق للقدرة (`genie` أو `sql` أو `unity-catalog` أو `vector-search`). يتولّى CrewAI تدفّق التفويض ويُجدّد الرموز تلقائيًا.
+        - **Use personal access token** — صادِق باستخدام [رمز وصول شخصي من Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/pat). استخدم هوية بأقل الامتيازات للحدّ من التعرّض.
+    </Step>
+
+    <Step title="صادِق">
+        أكمل المصادقة. بمجرد الاتصال، تصبح أدوات الخادم متاحة لفرقك. كرّر العملية لأي قدرات Databricks أخرى تريد تفعيلها.
+    </Step>
+</Steps>
+
+<Tip>
+لأن كل قدرة هي اتصال منفصل، يمكنك المزج والمطابقة — على سبيل المثال، فعّل Genie وVector Search لفريق بحث، مع حجز SQL وUnity Catalog Functions لفريق هندسة البيانات. تتيح لك إعدادات الرؤية (Visibility) التحكّم في أعضاء الفريق الذين يمكنهم استخدام كل منها.
+</Tip>
+
+## استخدام أدوات Databricks في فرقك
+
+بمجرد الاتصال، تظهر الأدوات التي يكشفها كل خادم MCP جنبًا إلى جنب مع الاتصالات المدمجة في صفحة **Tools & Integrations**. يمكنك:
+
+- **إسناد الأدوات إلى الوكلاء** في فرقك تمامًا مثل أي أداة أخرى في CrewAI.
+- **إدارة الرؤية** للتحكّم في أعضاء الفريق الذين يمكنهم استخدام كل اتصال.
+- **تعديل أو إزالة** أي اتصال في أي وقت من قائمة Connections.
+
+يمكن لوكلائك الآن طلب إجابات مستندة من Genie، وتنفيذ SQL على مستودعاتك، واستدعاء دوال Unity Catalog، والبحث في فهارس Vector Search — مع تدفّق النتائج تلقائيًا إلى استدلالهم.
+
+<Warning>
+تطبّق Databricks الحوكمة عبر Unity Catalog وUnity AI Gateway: لا يمكن للمستخدم اكتشاف الأدوات واستدعاؤها إلا تلك المصرَّح بها لهوية مساحة عمله. إذا فشل استدعاء أداة، فتأكّد من أن المستخدم المتصل (أو هوية الرمز) يمتلك امتيازات Unity Catalog المطلوبة على Genie Space أو المستودع أو الدالة أو الفهرس. تُنفَّذ بعض استعلامات Genie وSQL بشكل غير متزامن وقد تستغرق لحظة لإرجاع النتائج.
+</Warning>
+
+## مزيد من المعلومات
+
+<CardGroup cols={2}>
+  <Card title="خوادم MCP المُدارة من Databricks" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
+    وثائق Databricks الرسمية لخوادم MCP المُدارة Genie وSQL وUnity Catalog Functions وVector Search.
+  </Card>
+  <Card title="خوادم MCP المخصصة في CrewAI" icon="plug" href="/ar/enterprise/guides/custom-mcp-server">
+    تعرّف على كيفية اتصال CrewAI بأي خادم MCP، وهو الأساس الذي يُبنى عليه تكامل Databricks.
+  </Card>
+</CardGroup>
+
+<Card title="بحاجة إلى مساعدة؟" icon="headset" href="mailto:support@crewai.com">
+  تواصل مع فريق الدعم للحصول على المساعدة في تهيئة تكامل Databricks أو في حل المشكلات.
+</Card>

docs/ar/enterprise/integrations/snowflake.mdx

@@ -0,0 +1,134 @@
+---
+title: تكامل Snowflake
+description: "ربط وكلاء CrewAI بـ Snowflake Cortex Analyst و Cortex Search وتنفيذ SQL من خلال خادم MCP المُدار من Snowflake."
+icon: "snowflake"
+mode: "wide"
+---
+
+## نظرة عامة
+
+اربط وكلاء CrewAI مباشرة ببيانات Snowflake الخاصة بك من خلال [خادم MCP المُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). يتيح تكامل Snowflake لوكلائك الاستعلام عن البيانات المنظمة باستخدام **Cortex Analyst**، والبحث في البيانات غير المنظمة باستخدام **Cortex Search**، وتنفيذ SQL مُدار على مستودعات البيانات الخاصة بك — كل ذلك دون كتابة أو استضافة أي كود للموصّل.
+
+داخلياً، تكامل Snowflake هو غلاف مُدار حول دعم [Custom MCP Server](/ar/enterprise/guides/custom-mcp-server) في CrewAI. يكشف Snowflake عن قدرات Cortex AI الخاصة به من خلال نقطة نهاية [Model Context Protocol](https://modelcontextprotocol.io/)، ويتصل CrewAI بها بشكل آمن نيابةً عنك. أي أداة تكشفها على جانب Snowflake — Cortex Analyst أو Cortex Search أو تنفيذ SQL أو Cortex Agents أو أدواتك المخصصة — تصبح متاحة لطواقمك.
+
+## القدرات الرئيسية
+
+<CardGroup cols={3}>
+  <Card title="Cortex Analyst" icon="chart-bar">
+    اطرح أسئلة بلغة طبيعية ودع [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) يولّد وينفذ SQL على بياناتك **المنظمة** باستخدام نماذج دلالية غنية.
+  </Card>
+  <Card title="Cortex Search" icon="magnifying-glass">
+    استرجع البيانات **غير المنظمة** ذات الصلة لسير عمل RAG والمعرفة باستخدام [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview)، خدمة البحث المُدارة بالكامل من Snowflake.
+  </Card>
+  <Card title="تنفيذ SQL" icon="database">
+    نفّذ استعلامات SQL مُدارة مباشرة على مستودعات Snowflake الخاصة بك، مع وضع القراءة فقط القابل للتكوين، والمهلات الزمنية، واختيار المستودع.
+  </Card>
+</CardGroup>
+
+نظراً لأن التكامل يكشف عن أي أدوات ينشرها خادم MCP الخاص بك، يمكنك أيضاً كشف **Cortex Agents** و**الأدوات المخصصة** (الدوال المعرّفة من المستخدم والإجراءات المخزّنة) لوكلاء CrewAI.
+
+## المتطلبات الأساسية
+
+قبل استخدام تكامل Snowflake، تأكد من توفر ما يلي:
+
+- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال
+- حساب Snowflake مع إمكانية الوصول إلى ميزات Cortex AI
+- [خادم MCP مُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) مُكوّن بالأدوات التي تريد كشفها
+- صلاحيات Snowflake المناسبة (USAGE/SELECT) على خادم MCP والكائنات الأساسية
+
+## إعداد خادم Snowflake MCP
+
+يعمل خادم MCP المُدار من Snowflake داخل حساب Snowflake الخاص بك ويحدد الأدوات المتاحة للعملاء الخارجيين مثل CrewAI. أنشئ واحداً باستخدام أمر [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server)، مع سرد خدمات Cortex Search وعروض Cortex Analyst الدلالية وأدوات SQL التي تريد كشفها.
+
+```sql
+CREATE MCP SERVER my_mcp_server
+  FROM SPECIFICATION $$
+    tools:
+      - name: "sales_analyst"
+        type: "CORTEX_ANALYST"
+        identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view"
+        description: "Answer questions about sales metrics"
+      - name: "docs_search"
+        type: "CORTEX_SEARCH_SERVICE_QUERY"
+        identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search"
+        description: "Search internal support documentation"
+      - name: "run_sql"
+        type: "SQL_EXECUTION"
+        description: "Execute read-only SQL queries"
+  $$;
+```
+
+<Note>
+تتبع نقطة نهاية MCP التنسيق `https://<account_URL>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. يبني CrewAI هذا العنوان تلقائياً من **عنوان URL للحساب** و**قاعدة البيانات** و**المخطط** و**اسم خادم MCP** الذي تقدمه عند تكوين التكامل.
+</Note>
+
+للمواصفات الكاملة — بما في ذلك Cortex Agents والأدوات المخصصة وحدود حجم الاستجابة وخيارات الحوكمة — راجع [وثائق خادم MCP المُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp).
+
+## ربط Snowflake في CrewAI AMP
+
+<Frame>
+    <img src="/images/enterprise/snowflake-configure.png" alt="تكوين تكامل Snowflake في CrewAI AMP" />
+</Frame>
+
+<Steps>
+    <Step title="فتح الأدوات والتكاملات">
+        انتقل إلى **الأدوات والتكاملات** في الشريط الجانبي الأيسر لـ CrewAI AMP، وابحث عن **Snowflake** في قائمة التطبيقات، وافتح لوحة التكوين الخاصة به.
+    </Step>
+
+    <Step title="تقديم تفاصيل الاتصال">
+        املأ حقول الاتصال التي يستخدمها CrewAI للوصول إلى خادم Snowflake MCP الخاص بك:
+
+        | الحقل | مطلوب | الوصف |
+        |-------|-------|-------|
+        | **الاسم** | نعم | اسم وصفي لهذا الاتصال (القيمة الافتراضية `Snowflake`). |
+        | **الوصف** | لا | ملخص اختياري لما يوفره هذا الاتصال. |
+        | **عنوان URL للحساب** | نعم | عنوان URL لحساب Snowflake الخاص بك، مثل `xy12345.us-east-1.snowflakecomputing.com`. |
+        | **قاعدة البيانات** | نعم | قاعدة البيانات التي تحتوي على خادم MCP الخاص بك (مثل `MY_DATABASE`). |
+        | **المخطط** | نعم | المخطط الذي يحتوي على خادم MCP الخاص بك (مثل `MY_SCHEMA`). |
+        | **اسم خادم MCP** | نعم | اسم كائن خادم MCP الذي أنشأته في Snowflake (مثل `MY_MCP_SERVER`). |
+    </Step>
+
+    <Step title="اختيار طريقة المصادقة">
+        اختر كيفية مصادقة CrewAI مع Snowflake. يُوصى باستخدام **OAuth**.
+
+        - **استخدام OAuth** — اتصل بشكل آمن باستخدام OAuth 2.0 للمصادقة القائمة على الرموز دون مشاركة بيانات الاعتماد الخاصة بك. يتعامل CrewAI مع تدفق التفويض الكامل ويجدد الرموز تلقائياً. انسخ **عنوان URI لإعادة التوجيه** المعروض في النموذج (`https://oauth.crewai.com/oauth/add`) وسجّله كعنوان URI لإعادة التوجيه المعتمد في [تكامل أمان OAuth](https://docs.snowflake.com/en/user-guide/oauth-custom) في Snowflake.
+        - **استخدام رمز وصول شخصي** — المصادقة باستخدام [رمز وصول برمجي](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) مُنشأ من إعدادات حساب Snowflake الخاص بك. قم بتعيين دور بأقل صلاحيات للرمز للحد من التعرض.
+    </Step>
+
+    <Step title="المصادقة">
+        انقر على **المصادقة**. بالنسبة لـ OAuth، ستتم إعادة توجيهك إلى Snowflake لتفويض الوصول. بمجرد المصادقة، يظهر خادم Snowflake في قائمة الاتصالات وتصبح أدواته متاحة لطواقمك.
+    </Step>
+</Steps>
+
+<Tip>
+مع OAuth، يتم مصادقة كل مستخدم بشكل فردي وتُنفّذ الاستعلامات بدور `DEFAULT_ROLE` الخاص به في Snowflake. تأكد من أن المستخدمين المتصلين لديهم دور ومستودع افتراضي محدد (`ALTER USER <username> SET DEFAULT_ROLE = '<role>' DEFAULT_WAREHOUSE = '<warehouse>'`) حتى تتوفر موارد الحوسبة لأدوات Cortex Analyst و SQL.
+</Tip>
+
+## استخدام أدوات Snowflake في طواقمك
+
+بمجرد الاتصال، تظهر الأدوات التي يكشفها خادم MCP الخاص بك إلى جانب الاتصالات المدمجة في صفحة **الأدوات والتكاملات**. يمكنك:
+
+- **تعيين الأدوات للوكلاء** في طواقمك تماماً مثل أي أداة CrewAI أخرى.
+- **إدارة الرؤية** للتحكم في أعضاء الفريق الذين يمكنهم استخدام الاتصال.
+- **تعديل أو إزالة** الاتصال في أي وقت من قائمة الاتصالات.
+
+يمكن لوكلائك الآن سؤال Cortex Analyst عن المقاييس، وتشغيل Cortex Search على مستنداتك، وتنفيذ SQL — مع تدفق النتائج تلقائياً إلى استدلالهم.
+
+<Warning>
+يفرض Snowflake الحوكمة على خادم MCP: يحدد التحكم في الوصول القائم على الأدوار الأدوات التي يمكن للمستخدم اكتشافها واستدعاؤها، وتنطبق حدود على حجم الاستجابة وعدد الأدوات (بحد أقصى 50 لكل خادم) وعمق التكرار. إذا فشل استدعاء أداة، تأكد من أن دور المستخدم المتصل لديه الصلاحيات المطلوبة على خادم MCP والكائنات الأساسية.
+</Warning>
+
+## معرفة المزيد
+
+<CardGroup cols={2}>
+  <Card title="خادم MCP المُدار من Snowflake" icon="snowflake" href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp">
+    الوثائق الرسمية من Snowflake لإنشاء وإدارة خادم MCP.
+  </Card>
+  <Card title="خوادم Custom MCP في CrewAI" icon="plug" href="/ar/enterprise/guides/custom-mcp-server">
+    تعرّف على كيفية اتصال CrewAI بأي خادم MCP، الأساس الذي يبني عليه تكامل Snowflake.
+  </Card>
+</CardGroup>
+
+<Card title="تحتاج مساعدة؟" icon="headset" href="mailto:support@crewai.com">
+  تواصل مع فريق الدعم للحصول على المساعدة في تكامل Snowflake أو استكشاف الأخطاء وإصلاحها.
+</Card>

docs/ar/guides/advanced/customizing-prompts.mdx

@@ -161,6 +161,18 @@ crew = Crew(
 )
 ```
 
+<Note>
+يُحتفظ بـ `agent.i18n` للتوافق مع الإصدارات السابقة فقط، وقد تم إهماله. لتخصيص المطالبات أثناء التشغيل، مرّر `prompt_file` إلى `Crew`. وللوصول البرمجي المباشر إلى شرائح المطالبات، استخدم أداة i18n مباشرة:
+</Note>
+
+```python
+from crewai.utilities.i18n import get_i18n
+
+i18n = get_i18n("custom_prompts.json")
+format_slice = i18n.slice("format")
+tool_prompt = i18n.tools("ask_question")
+```
+
 #### الخيار 3: تعطيل مطالبات النظام لنماذج o1
 ```python
 agent = Agent(
@@ -208,6 +220,8 @@ agent = Agent(
 
 يدمج CrewAI بعد ذلك تخصيصاتك مع الإعدادات الافتراضية، فلا تحتاج لإعادة تعريف كل مطالبة. إليك الطريقة:
 
+بالنسبة للكود الذي يحتاج إلى قراءة شرائح المطالبات مباشرة، استخدم `crewai.utilities.i18n.get_i18n()` مع ملف المطالبات نفسه بدلًا من قراءة `agent.i18n`.
+
 ### مثال: تخصيص أساسي للمطالبات
 
 أنشئ ملف `custom_prompts.json` بالمطالبات التي تريد تعديلها. تأكد من إدراج جميع المطالبات عالية المستوى التي يجب أن يحتويها، وليس فقط تغييراتك:

docs/ar/guides/coding-tools/build-with-ai.mdx

@@ -43,7 +43,7 @@ CrewAI مُصمَّم أصلاً للعمل مع الذكاء الاصطناعي
 
     | المهارة | متى تُستخدم |
     |---------|-------------|
-    | `getting-started` | مشاريع جديدة، الاختيار بين `LLM.call()` / `Agent` / `Crew` / `Flow`، ربط `crew.py` / `main.py` |
+    | `getting-started` | مشاريع جديدة، الاختيار بين `LLM.call()` / `Agent` / `Crew` / `Flow`، ربط `crew.jsonc` / `main.py` |
     | `design-agent` | ضبط الوكلاء — الدور، الهدف، الخلفية، الأدوات، نماذج اللغة، الذاكرة، الحدود الآمنة |
     | `design-task` | وصف المهام، التبعيات، المخرجات المنظمة (`output_pydantic`، `output_json`)، المراجعة البشرية |
     | `ask-docs` | الاستعلام من [خادم CrewAI docs MCP](https://docs.crewai.com/mcp) للحصول على تفاصيل واجهة البرمجة الحالية |
@@ -64,7 +64,7 @@ CrewAI مُصمَّم أصلاً للعمل مع الذكاء الاصطناعي
   <Step title="يحصل وكيلك فوراً على خبرة CrewAI">
     تعلّم الحزمة وكيلك:
     - **Flows** — تطبيقات ذات حالة، خطوات، وتشغيل crews
-    - **Crews والوكلاء** — أنماط YAML أولاً، الأدوار، المهام، التفويض
+    - **Crews والوكلاء** — أنماط JSON-first (`crew.jsonc` و `agents/*.jsonc`)، الأدوار، المهام، التفويض
     - **الأدوات والتكاملات** — البحث، واجهات API، خوادم MCP، وأدوات CrewAI الشائعة
     - **هيكل المشروع** — هياكل CLI واتفاقيات المستودع
     - **أنماط محدثة** — يتماشى مع وثائق CrewAI الحالية وأفضل الممارسات

docs/ar/guides/crews/first-crew.mdx

@@ -1,321 +1,140 @@
 ---
-title: ابنِ أول Crew لك
-description: دليل تفصيلي لإنشاء فريق AI تعاوني يعمل معًا لحل المشكلات المعقدة.
+title: ابنِ أول Crew
+description: دليل خطوة بخطوة لإنشاء فريق AI تعاوني باستخدام تهيئة JSON-first.
 icon: users-gear
 mode: "wide"
 ---
 
-## إطلاق قوة الذكاء الاصطناعي التعاوني
+## بناء Crew للبحث
 
-تخيل أن لديك فريقًا من Agents الذكاء الاصطناعي المتخصصة تعمل معًا بسلاسة لحل مشكلات معقدة، كل منها يساهم بمهاراته الفريدة لتحقيق هدف مشترك. هذه هي قوة CrewAI - إطار عمل يمكّنك من إنشاء أنظمة ذكاء اصطناعي تعاونية يمكنها إنجاز مهام تفوق بكثير ما يمكن لـ AI واحد تحقيقه بمفرده.
+في هذا الدليل ستنشئ crew من Agentين: واحد للبحث وآخر لكتابة تقرير markdown. مشاريع الـ crew الجديدة هي JSON-first: تُعرّف الـ Agents في `agents/*.jsonc`، وتُعرّف المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة.
 
-في هذا الدليل، سنمشي عبر إنشاء Crew بحث يساعدنا في البحث والتحليل حول موضوع ما، ثم إنشاء تقرير شامل. يوضح هذا المثال العملي كيف يمكن لـ Agents الذكاء الاصطناعي التعاون لإنجاز مهام معقدة، لكنه مجرد البداية لما هو ممكن مع CrewAI.
+### المتطلبات
 
-### ما ستبنيه وتتعلمه
+1. تثبيت CrewAI من [دليل التثبيت](/ar/installation)
+2. إعداد مفتاح LLM من [دليل LLMs](/ar/concepts/llms#setting-up-your-llm)
+3. مفتاح [Serper.dev](https://serper.dev/) إذا أردت استخدام البحث على الويب
 
-بنهاية هذا الدليل، ستكون قد:
-
-1. **أنشأت فريق بحث AI متخصص** بأدوار ومسؤوليات مميزة
-2. **نسّقت التعاون** بين عدة Agents ذكاء اصطناعي
-3. **أتممت سير عمل معقد** يتضمن جمع المعلومات والتحليل وإنشاء التقارير
-4. **بنيت مهارات أساسية** يمكنك تطبيقها على مشاريع أكثر طموحًا
-
-### المتطلبات المسبقة
-
-قبل البدء، تأكد من:
-
-1. تثبيت CrewAI باتباع [دليل التثبيت](/ar/installation)
-2. إعداد مفتاح API لنموذج LLM في بيئتك، باتباع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm)
-3. فهم أساسي لـ Python
-
-## الخطوة 1: إنشاء مشروع CrewAI جديد
-
-أولاً، لننشئ مشروع CrewAI جديد باستخدام CLI. سينشئ هذا الأمر هيكل مشروع كامل بجميع الملفات الضرورية.
+## الخطوة 1: إنشاء Crew جديدة
 
 ```bash
 crewai create crew research_crew
 cd research_crew
 ```
 
-سينتج هيكل مشروع بالبنية الأساسية المطلوبة لـ Crew. ينشئ CLI تلقائيًا:
+البنية الناتجة:
 
-- مجلد مشروع بالملفات اللازمة
-- ملفات تهيئة للـ Agents والمهام
-- تطبيق Crew أساسي
-- سكريبت رئيسي لتشغيل الـ Crew
-
-<Frame caption="نظرة عامة على إطار عمل CrewAI">
-  <img src="/images/crews.png" alt="نظرة عامة على إطار عمل CrewAI" />
-</Frame>
-
-## الخطوة 2: استكشاف هيكل المشروع
-
-لنخصص لحظة لفهم هيكل المشروع الذي أنشأه CLI.
-
-```
+```text
 research_crew/
 ├── .gitignore
+├── .env
+├── agents/
+│   └── researcher.jsonc
+├── crew.jsonc
+├── knowledge/
 ├── pyproject.toml
 ├── README.md
-├── .env
-└── src/
-    └── research_crew/
-        ├── __init__.py
-        ├── main.py
-        ├── crew.py
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml
-            └── tasks.yaml
+├── skills/
+└── tools/
 ```
 
-يتبع هذا الهيكل أفضل الممارسات لمشاريع Python ويسهّل تنظيم الكود. فصل ملفات التهيئة (YAML) عن كود التنفيذ (Python) يسهّل تعديل سلوك Crew دون تغيير الكود الأساسي.
+<Tip>
+إذا احتجت إلى البنية القديمة التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، استخدم `crewai create crew research_crew --classic`.
+</Tip>
 
-## الخطوة 3: تهيئة الـ Agents
+## الخطوة 2: تعريف الـ Agents
 
-الآن يأتي الجزء الممتع - تعريف Agents الذكاء الاصطناعي! في CrewAI، الـ Agents هي كيانات متخصصة بأدوار وأهداف وخلفيات محددة تشكّل سلوكها.
+عدّل ملف `agents/researcher.jsonc` الذي أنشأه القالب، ثم أضف `agents/analyst.jsonc`. يجب أن تطابق أسماء الملفات الأسماء المشار إليها في `crew.jsonc`.
 
-لـ Crew البحث لدينا، سننشئ Agent اثنين:
-1. **باحث** يتفوق في إيجاد وتنظيم المعلومات
-2. **محلل** يمكنه تفسير نتائج البحث وإنشاء تقارير ثاقبة
-
-لنعدّل ملف `agents.yaml`. تأكد من تعيين `llm` للمزود الذي تستخدمه.
-
-```yaml
-# src/research_crew/config/agents.yaml
-researcher:
-  role: >
-    Senior Research Specialist for {topic}
-  goal: >
-    Find comprehensive and accurate information about {topic}
-    with a focus on recent developments and key insights
-  backstory: >
-    You are an experienced research specialist with a talent for
-    finding relevant information from various sources. You excel at
-    organizing information in a clear and structured manner, making
-    complex topics accessible to others.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
-
-analyst:
-  role: >
-    Data Analyst and Report Writer for {topic}
-  goal: >
-    Analyze research findings and create a comprehensive, well-structured
-    report that presents insights in a clear and engaging way
-  backstory: >
-    You are a skilled analyst with a background in data interpretation
-    and technical writing. You have a talent for identifying patterns
-    and extracting meaningful insights from research data, then
-    communicating those insights effectively through well-crafted reports.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
+```jsonc agents/researcher.jsonc
+{
+  "role": "Senior Research Specialist for {topic}",
+  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
+  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
+  // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-لاحظ كيف أن لكل Agent دور وهدف وخلفية مميزة. هذه العناصر ليست وصفية فحسب - بل تشكّل بنشاط كيف يتعامل الـ Agent مع مهامه.
-
-## الخطوة 4: تعريف المهام
-
-مع تعريف الـ Agents، نحتاج الآن لمنحهم مهام محددة. لنعدّل ملف `tasks.yaml`:
-
-```yaml
-# src/research_crew/config/tasks.yaml
-research_task:
-  description: >
-    Conduct thorough research on {topic}. Focus on:
-    1. Key concepts and definitions
-    2. Historical development and recent trends
-    3. Major challenges and opportunities
-    4. Notable applications or case studies
-    5. Future outlook and potential developments
-
-    Make sure to organize your findings in a structured format with clear sections.
-  expected_output: >
-    A comprehensive research document with well-organized sections covering
-    all the requested aspects of {topic}. Include specific facts, figures,
-    and examples where relevant.
-  agent: researcher
-
-analysis_task:
-  description: >
-    Analyze the research findings and create a comprehensive report on {topic}.
-    Your report should:
-    1. Begin with an executive summary
-    2. Include all key information from the research
-    3. Provide insightful analysis of trends and patterns
-    4. Offer recommendations or future considerations
-    5. Be formatted in a professional, easy-to-read style with clear headings
-  expected_output: >
-    A polished, professional report on {topic} that presents the research
-    findings with added analysis and insights. The report should be well-structured
-    with an executive summary, main sections, and conclusion.
-  agent: analyst
-  context:
-    - research_task
-  output_file: output/report.md
+```jsonc agents/analyst.jsonc
+{
+  "role": "Report Analyst for {topic}",
+  "goal": "Turn research findings into a clear, well-structured report.",
+  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
+  // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-لاحظ حقل `context` في مهمة التحليل - هذه ميزة قوية تتيح للمحلل الوصول إلى مخرجات مهمة البحث.
+استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `anthropic/claude-sonnet-4-6` أو `gemini/gemini-2.0-flash-001`.
 
-## الخطوة 5: تهيئة الـ Crew
+## الخطوة 3: تعريف المهام وإعدادات الـ Crew
 
-الآن حان الوقت لجمع كل شيء معًا. لنعدّل ملف `crew.py`:
+استبدل `crew.jsonc` بما يلي:
 
-```python
-# src/research_crew/crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai_tools import SerperDevTool
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
-
-@CrewBase
-class ResearchCrew():
-    """Research crew for comprehensive topic analysis and reporting"""
-
-    agents: List[BaseAgent]
-    tasks: List[Task]
-
-    @agent
-    def researcher(self) -> Agent:
-        return Agent(
-            config=self.agents_config['researcher'], # type: ignore[index]
-            verbose=True,
-            tools=[SerperDevTool()]
-        )
-
-    @agent
-    def analyst(self) -> Agent:
-        return Agent(
-            config=self.agents_config['analyst'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def research_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['research_task'] # type: ignore[index]
-        )
-
-    @task
-    def analysis_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['analysis_task'], # type: ignore[index]
-            output_file='output/report.md'
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the research crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
-
-## الخطوة 6: إعداد السكريبت الرئيسي
-
-```python
-#!/usr/bin/env python
-# src/research_crew/main.py
-import os
-from research_crew.crew import ResearchCrew
-
-# Create output directory if it doesn't exist
-os.makedirs('output', exist_ok=True)
-
-def run():
-    """
-    Run the research crew.
-    """
-    inputs = {
-        'topic': 'Artificial Intelligence in Healthcare'
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
+      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis_task",
+      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
+      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
+      "agent": "analyst",
+      "context": ["research_task"],
+      "output_file": "output/report.md",
+      "markdown": true
     }
-
-    # Create and run the crew
-    result = ResearchCrew().crew().kickoff(inputs=inputs)
-
-    # Print the result
-    print("\n\n=== FINAL REPORT ===\n\n")
-    print(result.raw)
-
-    print("\n\nReport has been saved to output/report.md")
-
-if __name__ == "__main__":
-    run()
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "Artificial Intelligence in Healthcare"
+  }
+}
 ```
 
-## الخطوة 7: إعداد متغيرات البيئة
+يشير `context` إلى أسماء مهام سابقة، لذلك يحصل analyst على مخرجات مهمة البحث. يوفر `inputs` قيمة افتراضية لـ `{topic}`. إذا حذفت القيمة الافتراضية، سيطلبها `crewai run`.
 
-أنشئ ملف `.env` في جذر مشروعك بمفاتيح API:
+## الخطوة 4: متغيرات البيئة
+
+عدّل `.env`:
 
 ```sh
 SERPER_API_KEY=your_serper_api_key
-# Add your provider's API key here too.
+# أضف مفتاح مزود النموذج أيضًا.
 ```
 
-راجع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لتفاصيل تهيئة المزود المفضل لديك. يمكنك الحصول على مفتاح Serper API من [Serper.dev](https://serper.dev/).
-
-## الخطوة 8: تثبيت التبعيات
+## الخطوة 5: التثبيت والتشغيل
 
 ```bash
 crewai install
-```
-
-## الخطوة 9: تشغيل الـ Crew
-
-الآن اللحظة المثيرة - حان وقت تشغيل Crew ومشاهدة التعاون بين الـ AI!
-
-```bash
 crewai run
 ```
 
-عند تشغيل هذا الأمر، سترى Crew يعمل. سيجمع الباحث معلومات حول الموضوع المحدد، ثم سينشئ المحلل تقريرًا شاملاً بناءً على ذلك البحث.
+بعد انتهاء التشغيل، افتح `output/report.md`.
 
-## الخطوة 10: مراجعة المخرجات
-
-بمجرد إتمام Crew عمله، ستجد التقرير النهائي في ملف `output/report.md`. سيتضمن التقرير:
-
-1. ملخص تنفيذي
-2. معلومات مفصلة عن الموضوع
-3. تحليل ورؤى
-4. توصيات أو اعتبارات مستقبلية
-
-## استكشاف أوامر CLI الأخرى
-
-يوفر CrewAI عدة أوامر CLI مفيدة للعمل مع Crews:
-
-```bash
-# View all available commands
-crewai --help
-
-# Run the crew
-crewai run
-
-# Test the crew
-crewai test
-
-# Reset crew memories
-crewai reset-memories
-
-# Replay from a specific task
-crewai replay -t <task_id>
-```
-
-## ما بعد أول Crew: فن الممكن
-
-ما بنيته في هذا الدليل مجرد البداية. يمكنك توسيع Crew البحث الأساسي بإضافة Agents متخصصة أخرى وأدوات وقدرات إضافية وسير عمل أكثر تعقيدًا. يمكن تطبيق نفس الأنماط لإنشاء Crews لإنشاء المحتوى وخدمة العملاء وتطوير المنتجات وتحليل البيانات.
-
-## الخطوات التالية
-
-1. جرّب تهيئات وشخصيات Agent مختلفة
-2. جرب هياكل مهام وسير عمل أكثر تعقيدًا
-3. طبّق أدوات مخصصة لمنح الـ Agents قدرات جديدة
-4. طبّق Crew على مواضيع أو مجالات مشكلات مختلفة
-5. استكشف [CrewAI Flows](/ar/guides/flows/first-flow) لسير عمل أكثر تقدمًا مع البرمجة الإجرائية
+<Warning>
+شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:<name>` ومراجع `{"python": "module.attribute"}` تنفذ Python محليًا عند تحميل الـ crew.
+</Warning>
 
 <Check>
-تهانينا! لقد بنيت بنجاح أول CrewAI Crew يمكنه البحث والتحليل في أي موضوع تقدمه. هذه التجربة الأساسية أهّلتك بالمهارات لإنشاء أنظمة AI متطورة بشكل متزايد يمكنها معالجة مشكلات معقدة متعددة المراحل من خلال الذكاء التعاوني.
+أصبحت لديك crew تعمل بأسلوب JSON-first تبحث في موضوع وتكتب تقريرًا.
 </Check>

docs/ar/guides/flows/conversational-flows.mdx

@@ -0,0 +1,473 @@
+---
+title: تدفقات المحادثة
+description: أنشئ تطبيقات دردشة متعددة الجولات مع kickoff لكل جولة وسجل الرسائل وتوجيه النية والتتبع وجسور WebSocket.
+icon: comments
+mode: "wide"
+---
+
+## نظرة عامة
+
+تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل وتصنيف النية الاختياري وتأجيل التتبع وجسور الواجهة، إضافة إلى REPL محلي `flow.chat()` للتدفقات المحادثية.
+
+| المفهوم | التنفيذ |
+|---------|---------|
+| معرّف الجلسة | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
+| سطر المستخدم | `handle_turn(message)` يضيف الرسالة إلى `state.messages` قبل تشغيل الرسم |
+| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `handle_turn` التالي |
+| تتبع الجلسة | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+
+## واجهات الجولات
+
+استخدم **`flow.handle_turn(message, session_id=...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي.
+
+لا يقبل `Flow.kickoff()` الوسيطين `user_message=` أو `session_id=`. في التدفقات المحادثية، يخزن `handle_turn()` الرسالة المعلقة ويستدعي داخلياً `kickoff(inputs={"id": session_id})`.
+
+| API | الاستخدام |
+|-----|-----------|
+| `handle_turn(message, session_id=...)` | غلاف مريح لجولة واحدة في `Flow` محادثي |
+| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي |
+| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية |
+| `ask()` | مطالبة حاجزة **داخل** خطوة واحدة |
+| `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي |
+| `ChatSession.handle_turn(...)` | طبقة نقل فوق `handle_turn` |
+
+## بداية سريعة
+
+```python
+from uuid import uuid4
+
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context):
+        message = (self.state.current_user_message or "").lower()
+        if "طلب" in message or "order" in message:
+            return "order"
+        if "وداع" in message or "goodbye" in message:
+            return "goodbye"
+        return "help"
+
+    @listen("order")
+    def handle_order(self):
+        reply = "طلبك في الطريق."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("help")
+    def handle_help(self):
+        reply = "كيف يمكنني المساعدة؟"
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("goodbye")
+    def handle_goodbye(self):
+        reply = "وداعاً!"
+        self.append_assistant_message(reply)
+        return reply
+
+
+session_id = str(uuid4())
+flow = SupportFlow()
+
+try:
+    flow.handle_turn("أين طلبي؟", session_id=session_id)
+    flow.handle_turn("وماذا عن الإرجاع؟", session_id=session_id)
+finally:
+    flow.finalize_session_traces()
+```
+
+## دورة حياة الجولة
+
+كل `handle_turn` يشغّل:
+
+1. **`_configure_conversational_kickoff`** — دمج `session_id` / `user_message` في `inputs` وتطبيق `ConversationalConfig`.
+2. **استعادة الحالة** — عند وجود `inputs["id"]` و`@persist`.
+3. **`FlowStarted`** — في أول جولة للجلسة المؤجلة فقط.
+4. **`prepare_conversational_turn`** — إضافة رسالة المستخدم و`last_user_message` وتصنيف اختياري.
+5. **تنفيذ الرسم** — `@start` → `@router` → معالجات `@listen`.
+6. **نهاية التشغيل** — يُتخطى `flow_finished` والتتبع لكل جولة عند التأجيل؛ `Agent.kickoff()` / crews لا تغلق دفعة الأب.
+
+استدعِ **`append_assistant_message(reply)`** في المعالجات. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.
+
+## `ConversationalConfig` (افتراضيات على مستوى الصنف)
+
+عيّن على صنف `Flow` كـ `conversational_config: ClassVar[ConversationalConfig | None]`.
+
+| الحقل | الافتراضي | الغرض |
+|-------|-----------|--------|
+| `default_intents` | `None` | تسميات outcome للتصنيف التلقائي قبل kickoff |
+| `intent_llm` | `None` | نموذج التصنيف (مطلوب عند وجود intents) |
+| `interactive_prompt` | `"You: "` | مطالبة `kickoff(interactive=True)` |
+| `interactive_timeout` | `None` | مهلة لكل سطر في الوضع التفاعلي |
+| `exit_commands` | `exit`, `quit` | كلمات إنهاء الوضع التفاعلي |
+| `defer_trace_finalization` | `True` | إبقاء دفعة trace واحدة مفتوحة بين الجولات |
+
+يمكن التجاوز لكل kickoff عبر `intents=` و`intent_llm=`.
+
+## `ChatState` (شكل الحالة الموصى به للحفظ)
+
+```python
+from crewai.flow import ChatState
+
+
+class MyChatState(ChatState):
+    # موروث: id, messages, last_user_message, last_intent, session_ready
+    research_turn_count: int = 0
+    custom_flag: bool = False
+```
+
+| الحقل | الدور |
+|-------|------|
+| `id` | UUID الجلسة (مثل `session_id` / `inputs["id"]`) |
+| `messages` | قائمة `{role, content}` لسجل LLM |
+| `last_user_message` | آخر سطر مستخدم في هذه الجولة |
+| `last_intent` | تسمية المسار بعد التصنيف (إن وُجد) |
+| `session_ready` | علم bootstrap لمرة واحدة |
+
+`ConversationalInputs` هو `TypedDict` لـ `kickoff(inputs={...})`: `id`, `user_message`, `last_intent`.
+
+## API المحادثة على `Flow`
+
+### معاملات `kickoff` / `kickoff_async`
+
+| المعامل | الغرض |
+|---------|--------|
+| `user_message` | نص هذه الجولة (أو `{"role": "user", "content": "..."}`) |
+| `session_id` | UUID المحادثة → `inputs["id"]` / `state.id` |
+| `intents` | تسميات outcome لـ `classify_intent` قبل kickoff |
+| `intent_llm` | LLM للتصنيف (مطلوب مع `intents`) |
+| `interactive` | حلقة CLI عبر `ask()` (للعروض المحلية فقط) |
+| `interactive_prompt` | مطالبة الوضع التفاعلي |
+| `interactive_timeout` | مهلة `ask()` لكل سطر |
+| `exit_commands` | كلمات إنهاء الوضع التفاعلي |
+| `inputs` | حقول حالة إضافية |
+| `restore_from_state_id` | استنساخ من flow محفوظ آخر |
+
+### سمات المثيل
+
+| السمة | الغرض |
+|-------|--------|
+| `conversational_config` | افتراضيات `ConversationalConfig` على مستوى الصنف |
+| `defer_trace_finalization` | علم المثيل؛ يُضبط تلقائياً من config عند kickoff |
+| `suppress_flow_events` | يخفي لوحات console؛ **التتبع يُسجّل** |
+| `stream` | بث؛ مع `ChatSession.handle_turn(..., stream=True)` |
+
+### طرق وخصائص
+
+| الاسم | الوصف |
+|------|--------|
+| `append_message(role, content, **extra)` | إضافة إلى `state.messages` |
+| `conversation_messages` | سجل للقراءة فقط لاستدعاءات LLM |
+| `classify_intent(text, outcomes, *, llm, context=None)` | تعيين outcome |
+| `receive_user_message(text, *, outcomes=None, llm=None)` | إضافة رسالة مستخدم؛ `last_intent` اختياري |
+| `finalize_session_traces()` | إصدار `flow_finished` المؤجل وإنهاء دفعة trace |
+| `_should_defer_trace_finalization()` | هل يُؤجل إنهاء trace لكل جولة |
+| `input_history` | سجل تدقيق مطالبات وردود `ask()` |
+
+### مساعدات الوحدة (`crewai.flow.conversation`)
+
+| الدالة | الوصف |
+|--------|--------|
+| `normalize_kickoff_inputs(...)` | دمج kwargs المحادثة في `inputs` |
+| `get_conversation_messages(flow)` | قراءة الرسائل من الحالة أو المخزن |
+| `append_message(flow, ...)` | مثل طريقة المثيل |
+| `prepare_conversational_turn(flow, ...)` | تهيئة الجولة (عادةً kickoff يستدعيها) |
+| `receive_user_message(flow, ...)` | مثل طريقة المثيل |
+| `set_state_field(flow, name, value)` | تعيين حقل dict أو Pydantic |
+| `get_conversational_config(flow)` | قراءة `conversational_config` |
+| `input_history_to_messages(entries)` | تحويل `input_history` لصيغة رسائل LLM |
+
+## أنماط توجيه النية
+
+### أ. تصنيف مسبق عبر `ConversationalConfig` (الأبسط)
+
+عيّن `default_intents` و`intent_llm`. كل kickoff يصنّف قبل `@router`؛ اقرأ `self.state.last_intent` في `route()`.
+
+### ب. تصنيف داخل `@router` (مطالبات أغنى)
+
+عيّن `default_intents=None` ليضيف kickoff الرسالة فقط. في `route()` استدعِ `classify_intent`:
+
+```python
+@router(bootstrap)
+def route(self):
+    intent = self.classify_intent(
+        self._routing_prompt(self.state.last_user_message),
+        ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
+        llm=self.conversational_config.intent_llm or "gpt-4o-mini",
+    )
+    self.state.last_intent = intent
+    return intent
+```
+
+للبحث على الويب أو أدوات متعددة الخطوات استخدم **`@listen("RESEARCH")`** مع `Agent.kickoff()` وأدوات — وليس `LLM.call()` فقط.
+
+## عندما ينتهي الـ flow ويستمر المستخدم
+
+`FlowFinished` يعني أن **تنفيذ الرسم هذا** اكتمل. تستمر المحادثة بـ `kickoff` آخر ونفس `session_id`. `@persist` يستعيد `messages` والأعلام والسياق.
+
+**نمط الحفظ:** يُفضّل `@persist` على **خطوة نهائية واحدة** (مثل `finalize`) وليس على صنف `Flow` بالكامل. الحفظ على مستوى الصنف بعد كل method قد يفقد تحديثات المعالجات في نفس الجولة.
+
+لا تستخدم `@human_feedback` لأسطر المتابعة في الدردشة إلا عند الحاجة لموافقة بشرية على مخرجات خطوة محددة.
+
+## `Flow` المحادثاتي (تجريبي)
+
+<Warning>
+  **ميزة تجريبية.** سطح `Flow` المحادثاتي (`conversational = True`،
+  `handle_turn`، `ConversationConfig`، `RouterConfig`،
+  `ConversationState`، الرسم البياني المدمج والمساعدات) يقع تحت
+  `crewai.experimental` وقد يتغير شكله قبل التخرج. ثبّت إصدار CrewAI إذا
+  كنت تعتمد على سلوك محدد، وراقب changelog للتحديثات الكاسرة. الملاحظات
+  والمشاكل مرحب بها.
+</Warning>
+
+فعّل الرسم المحادثاتي بتعيين `conversational = True` على صنف فرعي من `Flow`. عندئذٍ يُظهر `Flow` الأساسي رسم `@start` / `@router` / `converse_turn` / `end_conversation` مدمجاً، ويدير `state.messages`، ويُشغّل LLM التوجيه، ويبقي دفعة trace مفتوحة عبر الجولات. أنت تكتب **المسارات المخصصة** فقط؛ والإطار يتولى الباقي.
+
+استخدمه عندما تريد دردشة متعددة الجولات مع موجّه قائم على LLM ومعالجات لكل مسار دون توصيل دورة الحياة يدوياً. استخدم `Flow[ChatState]` (النمط الأدنى مستوى في الأعلى) عندما تحتاج تحكماً كاملاً.
+
+### مثال سريع
+
+```python
+from crewai import LLM, Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+    RouterConfig,
+)
+
+
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+
+@ConversationConfig(
+    system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.",
+    llm=ROUTER_LLM,
+    router=RouterConfig(),  # المسارات + الأوصاف تُكتشف تلقائياً من معالجات @listen
+)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    @listen("INTERNET_SEARCH")
+    def handle_internet_search(self) -> str:
+        """Fresh web research, current news, real-time lookups."""
+        ...
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("CREWAI_DOCS")
+    def handle_crewai_docs(self) -> str:
+        """Look up the CrewAI documentation for framework/API questions."""
+        ...
+        self.append_assistant_message(reply)
+        return reply
+
+
+flow = SupportFlow()
+try:
+    flow.handle_turn("ماذا يمكنك أن تفعل؟")                   # يوجَّه إلى converse (مدمج)
+    flow.handle_turn("ابحث في الويب عن أخبار الذكاء الاصطناعي.")  # يوجَّه إلى INTERNET_SEARCH
+    flow.handle_turn("لخص النتيجة الأولى.")                    # يعود إلى converse
+finally:
+    flow.finalize_session_traces()
+```
+
+للدردشة المحلية في الطرفية، استخدم `chat()`:
+
+```python
+def kickoff() -> None:
+    SupportFlow().chat()
+```
+
+يلف `chat()` استدعاءات `handle_turn()` داخل REPL، ويخرج عند `exit` / `quit`، ويتجاهل الأسطر الفارغة افتراضياً، ويستدعي `finalize_session_traces()` عند انتهاء الجلسة.
+
+### `ConversationConfig`
+
+مزخرف صنف يُلحق افتراضيات الدردشة على مستوى الصنف.
+
+| الحقل | الافتراضي | الغرض |
+|-------|-----------|-------|
+| `system_prompt` | `slices.conversational_system_prompt` من i18n | رسالة system يستخدمها `converse_turn` المدمج. مرر `""` للتعطيل التام. |
+| `llm` | `None` | LLM المحادثة (يستخدمه `converse_turn` وكاحتياطي للموجّه). |
+| `router` | `None` | `RouterConfig` للتوجيه عبر LLM. بدونه، يسقط الـ flow دائماً إلى `converse`. |
+| `answer_from_history_prompt` | افتراضي الإطار | رسالة system للمسار الاختياري `answer_from_history`. |
+| `answer_from_history_llm` | `None` | يُفعّل الاختصار `answer_from_history` عند تعيينه. |
+| `intent_llm` | `None` | LLM لمسار التصنيف المسبق القديم `intents=`/`default_intents`. |
+| `default_intents` | `None` | تسميات النتائج للتصنيف المسبق القديم. |
+| `visible_agent_outputs` | `None` | `"all"` أو قائمة بأسماء الـ agents الذين تُرفع مخرجاتهم من `append_agent_result()` إلى رسائل عامة. |
+| `defer_trace_finalization` | `True` | يبقي دفعة trace واحدة مفتوحة عبر استدعاءات `handle_turn()`. |
+
+### `RouterConfig` وفهرس المسارات المُولَّد تلقائياً
+
+```python
+RouterConfig(
+    prompt="تأطير اختياري للنطاق (سياسة، صوت، شخصية).",
+    response_format=MyRoute,        # اختياري؛ يُولَّد تلقائياً عند الإغفال
+    llm=ROUTER_LLM,                  # يسقط إلى ConversationConfig.llm
+    routes=["INTERNET_SEARCH", "CREWAI_DOCS"],   # اختياري؛ يُستنتج من المستمعين
+    route_descriptions={
+        "INTERNET_SEARCH": "تجاوز الـ docstring لهذا المسار فقط.",
+    },
+    default_intent="converse",       # يُستخدم عند فشل LLM أو غيابه
+    fallback_intent="converse",      # يُستخدم عندما يعيد LLM مساراً غير صالح
+    intent_field="intent",
+)
+```
+
+تُبنى رسالة الموجّه إلى LLM تلقائياً. لكل مسار يختار الإطار وصفاً بهذا الترتيب من الأولوية:
+
+1. `RouterConfig.route_descriptions[label]` — تجاوز صريح.
+2. `Flow.builtin_route_descriptions[label]` — نص جاهز من الإطار لـ `converse` و`end` و`answer_from_history` (مصاغ لـ LLM التوجيه).
+3. أول سطر غير فارغ من docstring معالج `@listen(label)`.
+4. فارغ (المسار يظهر في الفهرس بلا وصف).
+
+عملياً، **إضافة مسار جديد = `@listen("X")` + docstring من سطر واحد**:
+
+```python
+@listen("INTERNET_SEARCH")
+def handle_internet_search(self) -> str:
+    """Fresh web research, current news, real-time lookups."""
+    ...
+```
+
+…وسيرى LLM التوجيه:
+
+```
+Routes:
+- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions.
+- INTERNET_SEARCH: Fresh web research, current news, real-time lookups.
+- converse: Ordinary chat, follow-ups, summaries, clarifications…
+- end: User signals the conversation is finished (goodbye, exit, done).
+```
+
+`RouterConfig.prompt` مخصص لـ **تأطير النطاق** (شخصية المساعد، قواعد العمل، النبرة). فهرس المسارات يُبنى تلقائياً — لا تُدرج المسارات في `prompt`؛ سيختل التزامن لحظة إضافة معالج جديد.
+
+### المسارات المدمجة
+
+| المسار | المعالج | الغرض |
+|--------|---------|-------|
+| `converse` | `converse_turn` | معالج الدردشة الافتراضي. يستدعي `ConversationConfig.llm` بـ system prompt + التاريخ القانوني للرسائل. |
+| `end` | `end_conversation` | يضبط `state.ended = True` ويُصدر رد إنهاء. |
+| `answer_from_history` | `answer_from_history_turn` | اختياري. يُوجَّه إليه عندما يكون `ConversationConfig.answer_from_history_llm` مُعيَّناً ويمكن الإجابة على الرسالة من التاريخ فقط. |
+
+يمكنك تجاوز أي من هذه بتعريف معالج بنفس الاسم في الصنف الفرعي.
+
+### دلالات `handle_turn()`
+
+`flow.handle_turn(message)` يُشغّل جولة واحدة:
+
+1. يعيد ضبط تعقّب التنفيذ لكل جولة (`_completed_methods`, `_method_outputs`) ليُعاد تشغيل الرسم — بدون ذلك، استدعاءات `kickoff` المتكررة على نفس النسخة ستُحدث دائرة قصر من الجولة الثانية لأن `Flow.kickoff_async` يعتبر `inputs={"id": ...}` استعادة من نقطة تفتيش.
+2. يُلحق رسالة المستخدم بـ `state.messages` ويضبط `current_user_message` / `last_user_message`. يُحافَظ على `last_intent` **من الجولة السابقة** كي يستخدمها LLM التوجيه كإشارة.
+3. يُشغّل `conversation_start` → `route_conversation` → معالج `@listen` المختار.
+4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).
+5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك.
+
+استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية.
+
+### `chat()` للـ REPL المحلي
+
+`flow.chat()` هو غلاف الطرفية الجاهز فوق `handle_turn()`:
+
+```python
+flow = SupportFlow()
+flow.chat()
+```
+
+يتولى الحلقة المحلية الشائعة:
+
+1. يطلب رسالة من المستخدم.
+2. يتوقف عند `exit` / `quit` أو `EOFError` أو `KeyboardInterrupt`.
+3. يستدعي `handle_turn(message, session_id=...)`.
+4. يطبع نتيجة المساعد.
+5. ينهي traces الجلسة المؤجلة داخل كتلة `finally`.
+
+خصص سلوك الطرفية عبر I/O قابل للحقن:
+
+```python
+flow.chat(
+    session_id="demo-session",
+    prompt="You: ",
+    assistant_prefix="Assistant: ",
+    exit_commands=("exit", "quit", "bye"),
+)
+```
+
+لتطبيقات الويب والـ workers الخلفية والاختبارات ووسائط النقل المخصصة، استمر في استخدام `handle_turn()` مباشرةً.
+
+### سلوك موجّه مخصص
+
+لتشغيل آثار جانبية (إعداد ناقل أحداث، قياس عن بُعد) في كل قرار توجيه، تجاوز `route_turn`:
+
+```python
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context: dict[str, Any]) -> str | None:
+        self.event_bus = MyBus(self)
+        return super().route_turn(context)
+```
+
+لتجاوز موجّه LLM واختيار مسار برمجياً، أعد سلسلة نصية من `route_turn`؛ إعادة `None` تسقط إلى `_route_with_config(...)`.
+
+### `append_assistant_message` و`append_agent_result`
+
+داخل معالج `@listen(label)`، اختر:
+
+- `self.append_assistant_message(text)` — يضيف جولة مساعد مرئية للمستخدم إلى `state.messages`. سيراها `converse_turn` في الجولة التالية.
+- `self.append_agent_result(agent_name, result, visibility="private")` — يسجّل حدثاً منظماً في `state.events` وموضوعاً في `state.agent_threads[agent_name]`. الرؤية العامة تستدعي `append_assistant_message` أيضاً. استخدم النتائج الخاصة للعمل الجانبي الذي يجب ألا يلوث التاريخ القانوني.
+
+يمكن لـ `ConversationConfig.visible_agent_outputs` رفع النتائج الخاصة لـ agents محددين إلى عامة عالمياً (`"all"` أو قائمة بالأسماء).
+
+## التتبع عبر الجولات
+
+مع `defer_trace_finalization=True` (افتراضي في `ConversationalConfig`):
+
+- **دفعة trace واحدة** لجلسة الدردشة.
+- **`flow_started`** في الجولة الأولى فقط؛ **`flow_finished`** مرة في `finalize_session_traces()`.
+- **`kickoff` لكل جولة** لا يطبع "Trace batch finalized".
+- **العمل المتداخل** (`Agent.kickoff()`, crews, Exa) يُلحق بدفعة **الأب**؛ flow داخلي من `AgentExecutor` لا يغلق دفعة الجلسة مبكراً.
+
+```python
+flow.chat(session_id=session_id)
+```
+
+`flow.chat()` يستدعي `finalize_session_traces()` نيابةً عنك. عندما تملك الحلقة عبر `handle_turn()` أو `kickoff(...)`، استدعِ `finalize_session_traces()` عند انتهاء الجلسة.
+
+`suppress_flow_events=True` يخفي لوحات Rich فقط؛ أحداث trace والـ methods تُصدر.
+
+### دورة حياة trace لـ `Flow` المحادثاتي
+
+يستخدم [`Flow` المحادثاتي](#flow-المحادثاتي-تجريبي) التجريبي نفس دورة حياة tracing: `defer_trace_finalization` افتراضياً `True`، فيبقي كل `handle_turn()` أثر الجلسة مفتوحاً. أنهِ دوماً عند نهاية الجلسة — لُف حلقتك بـ `try/finally` واستدعِ `flow.finalize_session_traces()` عند الخروج. بدون ذلك، تبقى الدفعة مفتوحة وقد لا تُصدَّر آخر محادثة أبداً.
+
+## البث
+
+اضبط `stream = True` على صنف `Flow`. عندئذٍ يُصدر `kickoff(...)` أحداث `assistant_delta` (وما يرتبط بها) عبر ناقل الأحداث القياسي.
+
+## الاستيراد
+
+```python
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+    Flow,
+    listen,
+    persist,
+    router,
+    start,
+)
+```
+
+## مراجع
+
+- [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state)
+- [أنشئ أول Flow](/ar/guides/flows/first-flow)
+- Demo: `lib/crewai/runner_conversational_flow_simple.py` — REPL بسيط مع `RESEARCH` ووكيل Exa

docs/ar/guides/flows/first-flow.mdx

@@ -42,21 +42,26 @@ cd guide_creator_flow
 
 ## الخطوة 2: فهم هيكل المشروع
 
+يستخدم الـ crew المبدئي المضمّن في مشروع Flow بنية Python/YAML الكلاسيكية. لاستخدام crew بنمط JSON-first داخل Flow، أنشئ `crew.jsonc` و `agents/*.jsonc` داخل مجلد الـ crew وحمّله عبر `crewai.project.load_crew` كما في [Flows](/ar/concepts/flows#building-your-crews).
+
 ```
 guide_creator_flow/
 ├── .gitignore
 ├── pyproject.toml
 ├── README.md
 ├── .env
-├── main.py
-├── crews/
-│   └── poem_crew/
-│       ├── config/
-│       │   ├── agents.yaml
-│       │   └── tasks.yaml
-│       └── poem_crew.py
-└── tools/
-    └── custom_tool.py
+└── src/
+    └── guide_creator_flow/
+        ├── __init__.py
+        ├── main.py
+        ├── crews/
+        │   └── poem_crew/
+        │       ├── config/
+        │       │   ├── agents.yaml
+        │       │   └── tasks.yaml
+        │       └── poem_crew.py
+        └── tools/
+            └── custom_tool.py
 ```
 
 يوفر هذا الهيكل فصلاً واضحًا بين مكونات Flow المختلفة. سنعدّل هذا الهيكل لإنشاء Flow منشئ الدليل.
@@ -69,139 +74,77 @@ crewai flow add-crew content-crew
 
 ## الخطوة 4: تهيئة Crew كتابة المحتوى
 
-1. حدّث ملف تهيئة الـ Agents. تذكر تعيين `llm` للمزود الذي تستخدمه.
+سنهيئ crew كتابة المحتوى باستخدام JSONC. سنعرّف Agent للكتابة وAgent للمراجعة، ثم نحمّل `crew.jsonc` من خطوة Flow.
 
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/agents.yaml
-content_writer:
-  role: >
-    Educational Content Writer
-  goal: >
-    Create engaging, informative content that thoroughly explains the assigned topic
-    and provides valuable insights to the reader
-  backstory: >
-    You are a talented educational writer with expertise in creating clear, engaging
-    content. You have a gift for explaining complex concepts in accessible language
-    and organizing information in a way that helps readers build their understanding.
-  llm: provider/model-id
+1. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`:
 
-content_reviewer:
-  role: >
-    Educational Content Reviewer and Editor
-  goal: >
-    Ensure content is accurate, comprehensive, well-structured, and maintains
-    consistency with previously written sections
-  backstory: >
-    You are a meticulous editor with years of experience reviewing educational
-    content. You have an eye for detail, clarity, and coherence.
-  llm: provider/model-id
+```jsonc
+{
+  "role": "Educational Content Writer",
+  "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.",
+  "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-2. حدّث ملف تهيئة المهام:
+2. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`:
 
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
-write_section_task:
-  description: >
-    Write a comprehensive section on the topic: "{section_title}"
-
-    Section description: {section_description}
-    Target audience: {audience_level} level learners
-
-    Your content should:
-    1. Begin with a brief introduction to the section topic
-    2. Explain all key concepts clearly with examples
-    3. Include practical applications or exercises where appropriate
-    4. End with a summary of key points
-    5. Be approximately 500-800 words in length
-
-    Format your content in Markdown with appropriate headings, lists, and emphasis.
-
-    Previously written sections:
-    {previous_sections}
-  expected_output: >
-    A well-structured, comprehensive section in Markdown format that thoroughly
-    explains the topic and is appropriate for the target audience.
-  agent: content_writer
-
-review_section_task:
-  description: >
-    Review and improve the following section on "{section_title}":
-
-    {draft_content}
-
-    Target audience: {audience_level} level learners
-
-    Previously written sections:
-    {previous_sections}
-
-    Your review should:
-    1. Fix any grammatical or spelling errors
-    2. Improve clarity and readability
-    3. Ensure content is comprehensive and accurate
-    4. Verify consistency with previously written sections
-    5. Enhance the structure and flow
-    6. Add any missing key information
-  expected_output: >
-    An improved, polished version of the section that maintains the original
-    structure but enhances clarity, accuracy, and consistency.
-  agent: content_reviewer
-  context:
-    - write_section_task
+```jsonc
+{
+  "role": "Educational Content Reviewer and Editor",
+  "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.",
+  "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-3. حدّث ملف تنفيذ Crew:
+استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `gemini/gemini-2.0-flash-001` أو `anthropic/claude-sonnet-4-6`.
+
+3. أنشئ `src/guide_creator_flow/crews/content_crew/crew.jsonc`:
+
+```jsonc
+{
+  "name": "Content Crew",
+  "agents": ["content_writer", "content_reviewer"],
+  "tasks": [
+    {
+      "name": "write_section_task",
+      "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}",
+      "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.",
+      "agent": "content_writer",
+      "markdown": true
+    },
+    {
+      "name": "review_section_task",
+      "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.",
+      "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.",
+      "agent": "content_reviewer",
+      "context": ["write_section_task"],
+      "markdown": true
+    }
+  ],
+  "process": "sequential",
+  "verbose": true
+}
+```
+
+4. استبدل `src/guide_creator_flow/crews/content_crew/content_crew.py` بمحمل صغير:
 
 ```python
-# src/guide_creator_flow/crews/content_crew/content_crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+from pathlib import Path
 
-@CrewBase
-class ContentCrew():
-    """Content writing crew"""
+from crewai.project import load_crew
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
 
-    @agent
-    def content_writer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_writer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @agent
-    def content_reviewer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_reviewer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def write_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['write_section_task'] # type: ignore[index]
-        )
-
-    @task
-    def review_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['review_section_task'], # type: ignore[index]
-            context=[self.write_section_task()]
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the content writing crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
+def kickoff_content_crew(inputs: dict):
+    crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+    return crew.kickoff(inputs={**default_inputs, **inputs})
 ```
 
 ## الخطوة 5: إنشاء Flow
@@ -272,6 +215,7 @@ crewai flow plot
 3. استكشف دوال `and_` و`or_` لتنفيذ متوازٍ أكثر تعقيدًا
 4. اربط Flow بواجهات API خارجية وقواعد بيانات وواجهات مستخدم
 5. ادمج عدة Crews متخصصة في Flow واحد
+6. أنشئ تطبيقات دردشة متعددة الجولات مع [تدفقات المحادثة](/ar/guides/flows/conversational-flows) (`kickoff` لكل رسالة، `ChatSession`، تأجيل التتبع)
 
 <Check>
 تهانينا! لقد بنيت بنجاح أول CrewAI Flow يجمع بين الكود العادي واستدعاءات LLM المباشرة ومعالجة Crew لإنشاء دليل شامل. هذه المهارات الأساسية تمكّنك من إنشاء تطبيقات AI متطورة بشكل متزايد.

docs/ar/guides/flows/mastering-flow-state.mdx

@@ -20,6 +20,8 @@ mode: "wide"
 5. **توسيع تطبيقاتك** - دعم سير العمل المعقدة بتنظيم بيانات مناسب
 6. **تمكين التطبيقات الحوارية** - تخزين والوصول إلى سجل المحادثات للتفاعلات الواعية بالسياق
 
+للدردشة متعددة الجولات (`kickoff` لكل سطر مستخدم، `ChatState`، توجيه النية، تأجيل التتبع، و`ChatSession`)، راجع [تدفقات المحادثة](/ar/guides/flows/conversational-flows).
+
 ## أساسيات إدارة الحالة
 
 ### نهجان لإدارة الحالة

docs/ar/installation.mdx

@@ -113,7 +113,7 @@ python3 --version
 
 # إنشاء مشروع CrewAI
 
-نوصي باستخدام قالب `YAML` لنهج منظم في تعريف الـ Agents والمهام. إليك كيفية البدء:
+يقوم `crewai create crew` الآن بإنشاء مشروع crew بأسلوب JSON-first. توضع الـ Agents في `agents/*.jsonc`، وتوضع المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة.
 
 <Steps>
   <Step title="إنشاء هيكل المشروع">
@@ -126,21 +126,20 @@ python3 --version
       ```
       my_project/
       ├── .gitignore
+      ├── .env
+      ├── agents/
+      │   └── researcher.jsonc
+      ├── crew.jsonc
       ├── knowledge/
       ├── pyproject.toml
       ├── README.md
-      ├── .env
-      └── src/
-          └── my_project/
-              ├── __init__.py
-              ├── main.py
-              ├── crew.py
-              ├── tools/
-              │   ├── custom_tool.py
-              │   └── __init__.py
-              └── config/
-                  ├── agents.yaml
-                  └── tasks.yaml
+      ├── skills/
+      └── tools/
+      ```
+
+    - إذا احتجت إلى البنية القديمة Python/YAML التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، شغّل:
+      ```shell
+      crewai create crew <your_project_name> --classic
       ```
 
   </Step>
@@ -149,15 +148,15 @@ python3 --version
     - سيحتوي مشروعك على هذه الملفات الأساسية:
       | الملف | الغرض |
       | --- | --- |
-      | `agents.yaml` | تعريف الـ Agents وأدوارهم |
-      | `tasks.yaml` | إعداد مهام الـ Agents وسير العمل |
+      | `crew.jsonc` | إعداد الـ crew وترتيب المهام والعملية وقيم الإدخال الافتراضية |
+      | `agents/*.jsonc` | تعريف دور كل Agent وهدفه و backstory والـ LLM والأدوات والسلوك |
       | `.env` | تخزين مفاتيح API ومتغيرات البيئة |
-      | `main.py` | نقطة دخول المشروع وتدفق التنفيذ |
-      | `crew.py` | تنسيق وإدارة الـ Crew |
-      | `tools/` | مجلد الأدوات المخصصة |
-      | `knowledge/` | مجلد قاعدة المعرفة |
+      | `tools/` | ملفات Python اختيارية لأدوات `custom:<name>` |
+      | `knowledge/` | ملفات معرفة اختيارية للـ Agents |
+      | `skills/` | ملفات skills اختيارية تطبق على الـ crew |
 
-    - ابدأ بتحرير `agents.yaml` و`tasks.yaml` لتعريف سلوك الـ Crew.
+    - ابدأ بتحرير `crew.jsonc` والملفات داخل `agents/` لتعريف سلوك الـ crew.
+    - استخدم قيم `{placeholder}` في نصوص الـ Agents والمهام، ثم ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`. عند تشغيل `crewai run` ستطلب CLI أي قيم ناقصة.
     - احتفظ بالمعلومات الحساسة مثل مفاتيح API في `.env`.
 
   </Step>

docs/ar/learn/using-annotations.mdx

@@ -5,11 +5,15 @@ icon: "at"
 mode: "wide"
 ---
 
-يشرح هذا الدليل كيفية استخدام التعليقات التوضيحية للإشارة بشكل صحيح إلى **الوكلاء** و**المهام** والمكونات الأخرى في ملف `crew.py`.
+يشرح هذا الدليل كيفية استخدام التعليقات التوضيحية للإشارة بشكل صحيح إلى **الوكلاء** و**المهام** والمكونات الأخرى في ملف `crew.py` كلاسيكي.
+
+<Note>
+المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` هي JSON-first وتستخدم `crew.jsonc` مع `agents/*.jsonc`. استخدم هذا الدليل عند العمل في مشروع كلاسيكي أُنشئ عبر `crewai create crew <name> --classic`، أو عند ترحيل مشروع Python/YAML موجود، أو عندما تحتاج تحكمًا عبر decorators في Python.
+</Note>
 
 ## مقدمة
 
-تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. تساعد هذه التعليقات التوضيحية في تنظيم وهيكلة الكود الخاص بك، مما يجعله أكثر قابلية للقراءة والصيانة.
+تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. في مشاريع Python/YAML الكلاسيكية، تنظم الكود الذي يحمّل `config/agents.yaml` و `config/tasks.yaml` ويعيد كائن `Crew`.
 
 ## التعليقات التوضيحية المتاحة
 
@@ -113,9 +117,9 @@ def crew(self) -> Crew:
 
 تُستخدم التعليقة التوضيحية `@crew` لتزيين الطريقة التي تنشئ وتُرجع كائن `Crew`. تجمع هذه الطريقة جميع المكونات (الوكلاء والمهام) في طاقم وظيفي.
 
-## إعداد YAML
+## إعداد YAML الكلاسيكي
 
-تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف `agents.yaml` لوكيل الباحث:
+في المشاريع الكلاسيكية، تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف `agents.yaml` لوكيل الباحث:
 
 ```yaml
 researcher:
@@ -146,6 +150,6 @@ researcher:
 - **تسمية متسقة**: استخدم اصطلاحات تسمية واضحة ومتسقة لطرقك. على سبيل المثال، يمكن تسمية طرق الوكلاء بأسماء أدوارهم (مثل researcher، reporting_analyst).
 - **متغيرات البيئة**: استخدم متغيرات البيئة للمعلومات الحساسة مثل مفاتيح API.
 - **المرونة**: صمم طاقمك ليكون مرناً بالسماح بإضافة أو إزالة الوكلاء والمهام بسهولة.
-- **توافق YAML-الكود**: تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك.
+- **توافق YAML-الكود**: في المشاريع الكلاسيكية، تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك.
 
-باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك إنشاء أطقم منظمة جيداً وسهلة الصيانة باستخدام إطار عمل CrewAI.
+باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك الحفاظ على أطقم كلاسيكية منظمة وسهلة الصيانة. للـ crews الجديدة، استخدم بنية JSON-first في [Crews](/ar/concepts/crews).

docs/ar/quickstart.mdx

@@ -39,84 +39,60 @@ mode: "wide"
   يُنشئ ذلك تطبيق Flow ضمن `src/latest_ai_flow/`، بما في ذلك طاقمًا أوليًا في `crews/content_crew/` ستستبدله بطاقم بحث **بوكيل واحد** في الخطوات التالية.
   </Step>
 
-  <Step title="اضبط وكيلًا واحدًا في `agents.yaml`">
-  استبدل محتوى `src/latest_ai_flow/crews/content_crew/config/agents.yaml` بباحث واحد. تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`.
+  <Step title="اضبط وكيلًا واحدًا في JSONC">
+  أنشئ `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (أنشئ مجلد `agents/` إذا لزم). تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`.
 
-    ```yaml agents.yaml
-    # src/latest_ai_flow/crews/content_crew/config/agents.yaml
-    researcher:
-      role: >
-        باحث بيانات أول في {topic}
-      goal: >
-        اكتشاف أحدث التطورات في {topic}
-      backstory: >
-        أنت باحث مخضرم تكشف أحدث المستجدات في {topic}.
-        تجد المعلومات الأكثر صلة وتعرضها بوضوح.
+    ```jsonc agents/researcher.jsonc
+    {
+      "role": "باحث بيانات أول في {topic}",
+      "goal": "اكتشاف أحدث التطورات في {topic}",
+      "backstory": "أنت باحث يجد المعلومات الأكثر صلة ويعرضها بوضوح.",
+      "tools": ["SerperDevTool"],
+      "settings": {
+        "verbose": true
+      }
+    }
     ```
 
   </Step>
 
-  <Step title="اضبط مهمة واحدة في `tasks.yaml`">
-    ```yaml tasks.yaml
-    # src/latest_ai_flow/crews/content_crew/config/tasks.yaml
-    research_task:
-      description: >
-        أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات
-        حديثة وموثوقة. السنة الحالية 2026.
-      expected_output: >
-        تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة،
-        والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود.
-      agent: researcher
-      output_file: output/report.md
+  <Step title="اضبط الـ crew في `crew.jsonc`">
+  أنشئ `src/latest_ai_flow/crews/content_crew/crew.jsonc`:
+
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات حديثة وموثوقة.",
+          "expected_output": "تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة، والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود.",
+          "agent": "researcher",
+          "output_file": "output/report.md",
+          "markdown": true
+        }
+      ],
+      "process": "sequential",
+      "verbose": true
+    }
     ```
 
   </Step>
 
-  <Step title="اربط صف الطاقم (`content_crew.py`)">
-  اجعل الطاقم المُولَّد يشير إلى YAML وأرفق `SerperDevTool` بالباحث.
+  <Step title="حمّل crew JSON (`content_crew.py`)">
+  استبدل `content_crew.py` المُولّد بمحمل صغير يحول `crew.jsonc` إلى `Crew`.
 
     ```python content_crew.py
     # src/latest_ai_flow/crews/content_crew/content_crew.py
-    from typing import List
+    from pathlib import Path
 
-    from crewai import Agent, Crew, Process, Task
-    from crewai.agents.agent_builder.base_agent import BaseAgent
-    from crewai.project import CrewBase, agent, crew, task
-    from crewai_tools import SerperDevTool
+    from crewai.project import load_crew
 
 
-    @CrewBase
-    class ResearchCrew:
-      """طاقم بحث بوكيل واحد داخل Flow."""
-
-      agents: List[BaseAgent]
-      tasks: List[Task]
-
-      agents_config = "config/agents.yaml"
-      tasks_config = "config/tasks.yaml"
-
-      @agent
-      def researcher(self) -> Agent:
-        return Agent(
-          config=self.agents_config["researcher"],  # type: ignore[index]
-          verbose=True,
-          tools=[SerperDevTool()],
-        )
-
-      @task
-      def research_task(self) -> Task:
-        return Task(
-          config=self.tasks_config["research_task"],  # type: ignore[index]
-        )
-
-      @crew
-      def crew(self) -> Crew:
-        return Crew(
-          agents=self.agents,
-          tasks=self.tasks,
-          process=Process.sequential,
-          verbose=True,
-        )
+    def kickoff_content_crew(inputs: dict):
+      crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+      return crew.kickoff(inputs={**default_inputs, **inputs})
     ```
 
   </Step>
@@ -130,7 +106,7 @@ mode: "wide"
 
     from crewai.flow import Flow, listen, start
 
-    from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew
+    from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew
 
 
     class ResearchFlowState(BaseModel):
@@ -149,7 +125,7 @@ mode: "wide"
 
       @listen(prepare_topic)
       def run_research(self):
-        result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic})
+        result = kickoff_content_crew(inputs={"topic": self.state.topic})
         self.state.report = result.raw
         print("اكتمل طاقم البحث.")
 
@@ -171,7 +147,7 @@ mode: "wide"
     ```
 
   <Tip>
-  إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `ResearchCrew` ليطابق مسار الوحدة في مشروعك.
+  إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `kickoff_content_crew` ليطابق مسار الوحدة في مشروعك.
   </Tip>
   </Step>
 
@@ -198,7 +174,7 @@ mode: "wide"
 
   <CodeGroup>
     ```markdown output/report.md
-    # وكلاء الذكاء الاصطناعي في 2026: المشهد والاتجاهات
+    # وكلاء الذكاء الاصطناعي: المشهد والاتجاهات الحديثة
 
     ## ملخص تنفيذي
     …
@@ -219,7 +195,7 @@ mode: "wide"
 ## كيف يترابط هذا
 
 1. **Flow** — يشغّل `LatestAiFlow` أولًا `prepare_topic` ثم `run_research` ثم `summarize`. الحالة (`topic`، `report`) على Flow.
-2. **الطاقم** — يشغّل `ResearchCrew` مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير.
+2. **الطاقم** — يحمّل `kickoff_content_crew` ملف `crew.jsonc` ويشغّل مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير.
 3. **المُخرَج** — يكتب `output_file` للمهمة التقرير في `output/report.md`.
 
 للتعمق في أنماط Flow (التوجيه، الاستمرارية، الإنسان في الحلقة)، راجع [ابنِ أول Flow](/ar/guides/flows/first-flow) و[Flows](/ar/concepts/flows). للطواقم دون Flow، راجع [Crews](/ar/concepts/crews). لوكيل `Agent` واحد و`kickoff()` بلا مهام، راجع [Agents](/ar/concepts/agents#direct-agent-interaction-with-kickoff).
@@ -230,7 +206,10 @@ mode: "wide"
 
 ### اتساق التسمية
 
-يجب أن تطابق مفاتيح YAML (`researcher`، `research_task`) أسماء الدوال في صف `@CrewBase`. راجع [Crews](/ar/concepts/crews) لنمط الديكورات الكامل.
+يجب أن تطابق الأسماء في `crew.jsonc` الملفات والمراجع:
+
+- `agents: ["researcher"]` يحمّل `agents/researcher.jsonc`
+- `tasks[].agent: "researcher"` يربط المهمة بذلك الـ agent
 
 ## النشر
 

docs/ar/skills.mdx

@@ -20,7 +20,7 @@ npx skills add crewaiinc/skills
 ## ما يحصل عليه الوكيل
 
 - **Flows** — تطبيقات ذات حالة وخطوات وkickoffs للـ crew على نمط CrewAI
-- **Crews والوكلاء** — أنماط YAML أولاً، أدوار، مهام، وتفويض
+- **Crews والوكلاء** — أنماط JSON-first (`crew.jsonc` و `agents/*.jsonc`)، أدوار، مهام، وتفويض
 - **الأدوات والتكاملات** — ربط الوكلاء بالبحث وواجهات API وأدوات CrewAI الشائعة
 - **هيكل المشروع** — مواءمة مع قوالب CLI واتفاقيات المستودع
 - **أنماط محدثة** — تتبع المهارات وثائق CrewAI والممارسات الموصى بها

docs/en/changelog.mdx

@@ -4,6 +4,248 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Jun 11, 2026">
+  ## v1.14.7
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
+
+  ## What's Changed
+
+  ### Features
+  - Add pluggable default backends for memory, knowledge, rag, and flow.
+  - Surface real finish_reason, sampling params, and response.id on LLM events.
+  - Type DSL triggers as route-aware decorators.
+  - Add chat API for conversational flows.
+  - Make locking backend overridable.
+  - Build FlowDefinition from Flow DSL metadata.
+  - Add native Snowflake Cortex LLM provider.
+  - Add crew trained agents file support.
+
+  ### Bug Fixes
+  - Fix checkpoint to rebuild custom BaseLLM as concrete LLM on restore.
+  - Gate restore on a flag to prevent live snapshots from replaying as resume.
+  - Scope runtime state per run to bound growth and isolate concurrent runs.
+  - Fix telemetry setup on crewai-login.
+  - Respect suppress_flow_events for method-execution events.
+  - Restore [project.scripts] in crewai package for uv tool install.
+  - Resolve pip-audit CVEs for aiohttp, docling, and docling-core.
+  - Fix file input not working reliably.
+  - Fix Snowflake Claude incomplete tool result histories.
+
+  ### Documentation
+  - Update changelog and version for v1.14.7.
+  - Update OpenTelemetry collector documentation.
+  - Update NVIDIA Nemotron LLM guide.
+  - Add Databricks integration guide.
+  - Add Snowflake integration guide.
+
+  ### Performance
+  - Improve crewai import speed by lazy-loading docling imports.
+
+  ### Refactoring
+  - Simplify flow condition evaluation to be stateless per event.
+  - Decouple convo logic from runtime and add a conversational_definition.
+  - Split `flow.py` into DSL, definition, and runtime.
+
+  ## Contributors
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="Jun 10, 2026">
+  ## v1.14.7rc2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Gate restore on a flag to prevent live snapshots from replaying as resume
+
+  ### Documentation
+  - Update changelog and version for v1.14.7rc1
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Jun 10, 2026">
+  ## v1.14.7rc1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
+
+  ## What's Changed
+
+  ### Features
+  - Add `reset_runtime_state` to release accumulated bus state
+  - Handle supporting both custom prompts
+  - Decouple conversation logic from runtime and add a `conversational_definition`
+
+  ### Bug Fixes
+  - Fix scope of runtime state per run to bound growth and isolate concurrent runs
+  - Fix telemetry setup on `crewai-login`
+  - Fix respect for `suppress_flow_events` for method-execution events
+
+  ### Documentation
+  - Update OpenTelemetry images
+  - Update documentation to reflect new state of OpenTelemetry collector
+  - Update changelog and version for v1.14.7a4
+
+  ### Refactoring
+  - Simplify flow condition evaluation to be stateless per event
+  - Improve conversation routing cycle with one less route
+
+  ## Contributors
+
+  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
+
+</Update>
+
+<Update label="Jun 09, 2026">
+  ## v1.14.7a4
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
+
+  ## What's Changed
+
+  ### Features
+  - Migrate @listen/@router runtime to read from FlowDefinition
+  - Add pluggable default backends for memory, knowledge, rag, and flow
+
+  ### Documentation
+  - Update changelog and version for v1.14.7a3
+
+  ## Contributors
+
+  @greysonlalonde, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="Jun 08, 2026">
+  ## v1.14.7a3
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix exposure of `ask_for_human_input` on experimental `AgentExecutor`
+  - Resolve pip-audit CVEs for `aiohttp`, `docling`, `docling-core`, and `pip`
+
+  ### Refactoring
+  - Migrate `@start` to read from `FlowDefinition`
+
+  ### Documentation
+  - Update changelog and version for v1.14.7a2
+
+  ## Contributors
+
+  @greysonlalonde, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="Jun 05, 2026">
+  ## v1.14.7a2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
+
+  ## What's Changed
+
+  ### Features
+  - Add conversational flow traces support.
+  - Update conversational flow documentation to utilize `handle_turn`.
+  - Surface real `finish_reason`, sampling parameters, and `response.id` in LLM events.
+  - Type DSL triggers as route-aware decorators.
+  - Implement chat API for conversational flows.
+  - Make locking backend overridable in lock store.
+  - Split flow DSL monolith into focused decorator modules.
+  - Flatten LiteLLM cache/reasoning usage sub-counts in `_usage_to_dict`.
+  - Build `FlowDefinition` from Flow DSL metadata.
+
+  ### Documentation
+  - Add NVIDIA Nemotron LLM guide.
+  - Document monorepo deployments.
+  - Update changelog and version for v1.14.7a1.
+
+  ## Contributors
+
+  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="Jun 03, 2026">
+  ## v1.14.7a1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a1)
+
+  ## What's Changed
+
+  ### Features
+  - Add crew trained agents file support
+  - Add native Snowflake Cortex LLM provider
+  - Add Databricks integration guide
+  - Add Snowflake integration guide
+
+  ### Bug Fixes
+  - Fix CLI by restoring `[project.scripts]` in crewai package for UV tool install
+  - Resolve file input reliability issues
+  - Fix incomplete tool result histories in Snowflake Claude
+  - Handle stringified tool calls for Snowflake Claude
+  - Re-arm multi-source `or_` listeners across router-driven cycles
+
+  ### Performance
+  - Improve crewai import speed by lazy-loading docling imports
+
+  ### Refactoring
+  - Split `flow.py` into DSL, definition, and runtime
+
+  ## Contributors
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @jessemiller, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="May 28, 2026">
+  ## v1.14.6
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance StdioTransport to prevent environment variable leakage
+  - Enhance planning configuration and observation handling
+  - Declare env_vars on DatabricksQueryTool
+  - Add Agent Control Plane docs
+
+  ### Bug Fixes
+  - Fix structured output leaks in tool-calling loops
+  - Drop unroundtrippable callbacks and adapter state in checkpoint
+  - Serialize type[BaseModel] fields as JSON schema in checkpoint
+  - Avoid orphan task_started on resume scope restore
+  - Allow AgentExecutor to restore from checkpoint
+  - Correct mongodb typo to pymongo in package_dependencies
+
+  ### Documentation
+  - Add ACP (Beta) docs navigation block to Agent Control Plane pages
+  - Remove consensual process references from processes page
+  - Restructure checkpointing page
+  - Document one-time admin package install step
+  - Migrate Secrets Manager / Workload Identity from replicated-config
+  - Remove `{" "}` JSX expressions breaking `<Steps>` render
+
+  ### Refactoring
+  - Move Skills Repository to experimental + CREWAI_EXPERIMENTAL gate
+
+  ## Contributors
+
+  @akaKuruma, @alex-clawd, @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="May 27, 2026">
   ## v1.14.6a2
 

docs/en/concepts/agents.mdx

@@ -71,81 +71,65 @@ The Visual Agent Builder enables:
 
 ## Creating Agents
 
-There are two ways to create agents in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
+There are two common ways to create agents in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**.
 
-### YAML Configuration (Recommended)
+### JSONC Configuration (Recommended)
 
-Using YAML configuration provides a cleaner, more maintainable way to define agents. We strongly recommend using this approach in your CrewAI projects.
+New projects created with `crewai create crew <name>` use JSON-first configuration. Each agent is defined in `agents/<agent_name>.jsonc`, and `crew.jsonc` lists which agents are part of the crew.
 
-After creating your CrewAI project as outlined in the [Installation](/en/installation) section, navigate to the `src/latest_ai_development/config/agents.yaml` file and modify the template to match your requirements.
+After creating your CrewAI project as outlined in the [Installation](/en/installation) section, edit the generated files in `agents/`.
 
 <Note>
-Variables in your YAML files (like `{topic}`) will be replaced with values from your inputs when running the crew:
-```python Code
-crew.kickoff(inputs={'topic': 'AI Agents'})
-```
+Use `{placeholder}` values in `role`, `goal`, or `backstory`. Put defaults in `crew.jsonc` under `inputs`; `crewai run` prompts for any missing values.
 </Note>
 
-Here's an example of how to configure agents using YAML:
+Here's an example `agents/researcher.jsonc` file:
 
-```yaml agents.yaml
-# src/latest_ai_development/config/agents.yaml
-researcher:
-  role: >
-    {topic} Senior Data Researcher
-  goal: >
-    Uncover cutting-edge developments in {topic}
-  backstory: >
-    You're a seasoned researcher with a knack for uncovering the latest
-    developments in {topic}. Known for your ability to find the most relevant
-    information and present it in a clear and concise manner.
-
-reporting_analyst:
-  role: >
-    {topic} Reporting Analyst
-  goal: >
-    Create detailed reports based on {topic} data analysis and research findings
-  backstory: >
-    You're a meticulous analyst with a keen eye for detail. You're known for
-    your ability to turn complex data into clear and concise reports, making
-    it easy for others to understand and act on the information you provide.
+```jsonc agents/researcher.jsonc
+{
+  "role": "{topic} Senior Data Researcher",
+  "goal": "Uncover cutting-edge developments in {topic}",
+  "backstory": "You find the most relevant information and present it clearly.",
+  "llm": "openai/gpt-4o",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false,
+    "max_iter": 20
+  }
+}
 ```
 
-To use this YAML configuration in your code, create a crew class that inherits from `CrewBase`:
+Then include that agent from `crew.jsonc`:
 
-```python Code
-# src/latest_ai_development/crew.py
-from crewai import Agent, Crew, Process
-from crewai.project import CrewBase, agent, crew
-from crewai_tools import SerperDevTool
-
-@CrewBase
-class LatestAiDevelopmentCrew():
-  """LatestAiDevelopment crew"""
-
-  agents_config = "config/agents.yaml"
-
-  @agent
-  def researcher(self) -> Agent:
-    return Agent(
-      config=self.agents_config['researcher'], # type: ignore[index]
-      verbose=True,
-      tools=[SerperDevTool()]
-    )
-
-  @agent
-  def reporting_analyst(self) -> Agent:
-    return Agent(
-      config=self.agents_config['reporting_analyst'], # type: ignore[index]
-      verbose=True
-    )
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Research {topic}",
+      "expected_output": "A concise briefing about {topic}",
+      "agent": "researcher"
+    }
+  ],
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
 ```
 
+Agent files support any public `Agent` field. Common fields include `role`, `goal`, `backstory`, `llm`, `tools`, `function_calling_llm`, `guardrail`, `step_callback`, and `settings`. Behavior options such as `verbose`, `allow_delegation`, `max_iter`, `max_rpm`, `memory`, `cache`, `planning_config`, and `use_system_prompt` can be placed at the top level or under `settings`; values in `settings` take precedence.
+
 <Note>
-  The names you use in your YAML files (`agents.yaml`) should match the method
-  names in your Python code.
+  JSONC supports comments and trailing commas. If both `agents/<name>.jsonc` and `agents/<name>.json` exist, CrewAI uses the JSONC file.
 </Note>
 
+### Classic YAML Configuration
+
+Classic projects created with `crewai create crew <name> --classic` use `config/agents.yaml` and a `@CrewBase` class in `crew.py`. This remains supported for teams that want Python decorators or existing YAML projects.
+
 ### Direct Code Definition
 
 You can create agents directly in code by instantiating the `Agent` class. Here's a comprehensive example showing all available parameters:

docs/en/concepts/cli.mdx

@@ -52,6 +52,8 @@ crewai create crew my_new_crew
 crewai create flow my_new_flow
 ```
 
+By default, `crewai create crew` creates a JSON-first crew project with `crew.jsonc` and `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` only when you want the older Python/YAML scaffold with `crew.py`, `config/agents.yaml`, and `config/tasks.yaml`.
+
 ### 2. Version
 
 Show the installed version of CrewAI.
@@ -185,7 +187,20 @@ crewai chat
 Ensure you execute these commands from your CrewAI project's root directory.
 </Note>
 <Note>
-IMPORTANT: Set the `chat_llm` property in your `crew.py` file to enable this command.
+IMPORTANT: Set the `chat_llm` property in your crew definition to enable this command.
+
+For JSON-first crews, add it to `crew.jsonc`:
+
+```jsonc
+{
+  "name": "My Crew",
+  "agents": ["researcher"],
+  "tasks": [],
+  "chat_llm": "openai/gpt-4o"
+}
+```
+
+For classic Python/YAML crews, set it in `crew.py`:
 
 ```python
 @crew
@@ -336,7 +351,7 @@ Notes:
 
 ### 12. API Keys
 
-When running `crewai create crew` command, the CLI will show you a list of available LLM providers to choose from, followed by model selection for your chosen provider.
+When running the `crewai create crew` command, the CLI shows a list of available LLM providers, followed by model selection for your chosen provider. The selected model is saved in the generated `.env` file and each generated agent JSONC file can set its own `llm`.
 
 Once you've selected an LLM provider and model, you will be prompted for API keys.
 

docs/en/concepts/crews.mdx

@@ -48,108 +48,74 @@ A crew in crewAI represents a collaborative group of agents working together to
 
 ## Creating Crews
 
-There are two ways to create crews in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
+There are two common ways to create crews in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**.
 
-### YAML Configuration (Recommended)
+### JSONC Configuration (Recommended)
 
-Using YAML configuration provides a cleaner, more maintainable way to define crews and is consistent with how agents and tasks are defined in CrewAI projects.
+New projects created with `crewai create crew <name>` use `crew.jsonc` for crew-level settings and tasks, plus one file per agent in `agents/`.
 
-After creating your CrewAI project as outlined in the [Installation](/en/installation) section, you can define your crew in a class that inherits from `CrewBase` and uses decorators to define agents, tasks, and the crew itself.
+`crewai run` automatically detects `crew.jsonc` or `crew.json`, loads the referenced agents, prompts for missing placeholders, and kicks off the crew.
 
-#### Example Crew Class with Decorators
+#### Example `crew.jsonc`
 
-```python code
-from crewai import Agent, Crew, Task, Process
-from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
-
-@CrewBase
-class YourCrewName:
-    """Description of your crew"""
-
-    agents: List[BaseAgent]
-    tasks: List[Task]
-
-    # Paths to your YAML configuration files
-    # To see an example agent and task defined in YAML, checkout the following:
-    # - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
-    # - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
-    agents_config = 'config/agents.yaml'
-    tasks_config = 'config/tasks.yaml'
-
-    @before_kickoff
-    def prepare_inputs(self, inputs):
-        # Modify inputs before the crew starts
-        inputs['additional_data'] = "Some extra information"
-        return inputs
-
-    @after_kickoff
-    def process_output(self, output):
-        # Modify output after the crew finishes
-        output.raw += "\nProcessed after kickoff."
-        return output
-
-    @agent
-    def agent_one(self) -> Agent:
-        return Agent(
-            config=self.agents_config['agent_one'], # type: ignore[index]
-            verbose=True
-        )
-
-    @agent
-    def agent_two(self) -> Agent:
-        return Agent(
-            config=self.agents_config['agent_two'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def task_one(self) -> Task:
-        return Task(
-            config=self.tasks_config['task_one'] # type: ignore[index]
-        )
-
-    @task
-    def task_two(self) -> Task:
-        return Task(
-            config=self.tasks_config['task_two'] # type: ignore[index]
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,  # Automatically collected by the @agent decorator
-            tasks=self.tasks,    # Automatically collected by the @task decorator.
-            process=Process.sequential,
-            verbose=True,
-        )
+```jsonc crew.jsonc
+{
+  "name": "Market Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research",
+      "description": "Research {topic} and collect the most relevant facts.",
+      "expected_output": "Structured research notes about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis",
+      "description": "Analyze the research and write a concise report.",
+      "expected_output": "A markdown report with findings and recommendations.",
+      "agent": "analyst",
+      "context": ["research"],
+      "output_file": "output/report.md"
+    }
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
 ```
 
-How to run the above code:
+Each string in `agents` resolves to `agents/<name>.jsonc` first, then `agents/<name>.json`.
 
-```python code
-YourCrewName().crew().kickoff(inputs={"any": "input here"})
+```jsonc agents/researcher.jsonc
+{
+  "role": "{topic} Senior Researcher",
+  "goal": "Find accurate and current information about {topic}.",
+  "backstory": "You are a careful researcher who cites clear evidence.",
+  "llm": "openai/gpt-4o",
+  "tools": ["SerperDevTool"]
+}
 ```
 
 <Note>
-Tasks will be executed in the order they are defined.
+Tasks run in the order they appear in `tasks` when `process` is `"sequential"`.
 </Note>
 
-The `CrewBase` class, along with these decorators, automates the collection of agents and tasks, reducing the need for manual management.
+For hierarchical crews, set `"process": "hierarchical"` and provide either `manager_llm` or `manager_agent`. A `manager_agent` can reference an `agents/<name>.jsonc` file that is not included in the top-level `agents` list.
 
-#### Decorators overview from `annotations.py`
+JSON crew definitions support crew-level fields such as `process`, `verbose`, `memory`, `cache`, `max_rpm`, `planning`, `planning_llm`, `manager_llm`, `manager_agent`, `function_calling_llm`, `output_log_file`, `stream`, `tracing`, `before_kickoff_callbacks`, and `after_kickoff_callbacks`.
 
-CrewAI provides several decorators in the `annotations.py` file that are used to mark methods within your crew class for special handling:
+Python callbacks and custom classes use `{"python": "module.attribute"}`. Custom tools use `"custom:<name>"` and load `tools/<name>.py` at runtime.
 
-- `@CrewBase`: Marks the class as a crew base class.
-- `@agent`: Denotes a method that returns an `Agent` object.
-- `@task`: Denotes a method that returns a `Task` object.
-- `@crew`: Denotes the method that returns the `Crew` object.
-- `@before_kickoff`: (Optional) Marks a method to be executed before the crew starts.
-- `@after_kickoff`: (Optional) Marks a method to be executed after the crew finishes.
+<Warning>
+Only run JSON crew projects from sources you trust. `custom:<name>` tools and `{"python": "module.attribute"}` references execute local Python code when the crew loads.
+</Warning>
 
-These decorators help in organizing your crew's structure and automatically collecting agents and tasks without manually listing them.
+### Classic Python/YAML Configuration
+
+Classic projects created with `crewai create crew <name> --classic` use `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, and the `@CrewBase`, `@agent`, `@task`, and `@crew` decorators. That pattern remains supported and is documented in [Using Annotations](/en/learn/using-annotations).
 
 ### Direct Code Definition (Alternative)
 

docs/en/concepts/flows.mdx

@@ -226,6 +226,49 @@ After the Flow has run, you can access the final state to see the updates made b
 By ensuring that the final method's output is returned and providing access to the state, CrewAI Flows make it easy to integrate the results of your AI workflows into larger applications or systems,
 while also maintaining and accessing the state throughout the Flow's execution.
 
+## Flow Usage Metrics
+
+After a Flow execution completes, you can access the `usage_metrics` property to view aggregated token usage across **every LLM call** made during the run — including calls from every Crew the Flow orchestrated, calls inside Agent tools, and bare `LLM.call(...)` invocations from Flow methods. This is the SDK-side equivalent of the totals shown in the CrewAI Enterprise UI.
+
+```python Code
+from crewai import LLM
+from crewai.flow.flow import Flow, listen, start
+
+class UsageMetricsFlow(Flow):
+    @start()
+    def run_first_crew(self):
+        self.state.first_result = FirstCrew().crew().kickoff()
+
+    @listen(run_first_crew)
+    def call_llm_directly(self):
+        # Bare LLM call — still counted by flow.usage_metrics
+        llm = LLM(model="openai/gpt-4o-mini")
+        self.state.summary = llm.call("Summarize the key takeaways.")
+
+    @listen(call_llm_directly)
+    def run_second_crew(self):
+        self.state.second_result = SecondCrew().crew().kickoff()
+
+flow = UsageMetricsFlow()
+flow.kickoff()
+
+print(flow.usage_metrics)
+# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
+#              cached_prompt_tokens=0, reasoning_tokens=0,
+#              cache_creation_tokens=0, successful_requests=5)
+```
+
+<Note>
+  `flow.usage_metrics` is **not** the same as `flow.kickoff().token_usage`. The
+  latter returns the `CrewOutput.token_usage` of the **last** `@listen` method
+  that returned a `CrewOutput`, which means it only reflects the final Crew and
+  ignores prior Crews and bare `LLM.call(...)` invocations entirely. Use
+  `flow.usage_metrics` whenever you need the **full** token rollup for the Flow
+  execution.
+</Note>
+
+Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
+
 ## Flow State Management
 
 Managing state effectively is crucial for building reliable and maintainable AI workflows. CrewAI Flows provides robust mechanisms for both unstructured and structured state management,
@@ -788,7 +831,7 @@ You can generate a new CrewAI project that includes all the scaffolding needed t
 crewai create flow name_of_flow
 ```
 
-This command will generate a new CrewAI project with the necessary folder structure. The generated project includes a prebuilt crew called `poem_crew` that is already working. You can use this crew as a template by copying, pasting, and editing it to create other crews.
+This command will generate a new CrewAI project with the necessary folder structure. The generated project includes a prebuilt crew called `poem_crew` that is already working. The starter embedded crew uses the classic Python/YAML layout; new standalone crews created with `crewai create crew` use the JSON-first layout.
 
 ### Folder Structure
 
@@ -812,13 +855,35 @@ After running the `crewai create flow name_of_flow` command, you will see a fold
 
 ### Building Your Crews
 
-In the `crews` folder, you can define multiple crews. Each crew will have its own folder containing configuration files and the crew definition file. For example, the `poem_crew` folder contains:
+In the `crews` folder, you can define multiple crews. The generated `poem_crew` uses the classic embedded-crew structure:
 
 - `config/agents.yaml`: Defines the agents for the crew.
 - `config/tasks.yaml`: Defines the tasks for the crew.
 - `poem_crew.py`: Contains the crew definition, including agents, tasks, and the crew itself.
 
-You can copy, paste, and edit the `poem_crew` to create other crews.
+You can copy, paste, and edit the `poem_crew` to create other classic embedded crews.
+
+For JSON-first embedded crews, use a folder with `crew.jsonc` and `agents/*.jsonc` instead:
+
+```text
+crews/
+└── research_crew/
+    ├── agents/
+    │   └── researcher.jsonc
+    └── crew.jsonc
+```
+
+Then load it from a Flow step:
+
+```python
+from pathlib import Path
+from crewai.project import load_crew
+
+crew, default_inputs = load_crew(
+    Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc"
+)
+result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"})
+```
 
 ### Connecting Crews in `main.py`
 

docs/en/concepts/llms.mdx

@@ -107,7 +107,7 @@ There are different places in CrewAI code where you can specify the model to use
 </Tabs>
 
 <Info>
-  CrewAI provides native SDK integrations for OpenAI, Anthropic, Google (Gemini API), Azure, and AWS Bedrock — no extra install needed beyond the provider-specific extras (e.g. `uv add "crewai[openai]"`).
+  CrewAI provides native SDK integrations for OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock, and Snowflake Cortex — no extra install needed beyond the provider-specific extras (e.g. `uv add "crewai[openai]"`).
 
   All other providers are powered by **LiteLLM**. If you plan to use any of them, add it as a dependency to your project:
   ```bash
@@ -291,6 +291,55 @@ In this section, you'll find detailed examples that help you select, configure,
     ```
   </Accordion>
 
+  <Accordion title="Snowflake Cortex">
+    CrewAI provides native integration with the Snowflake Cortex REST API through its OpenAI-compatible Chat Completions endpoint. This avoids LiteLLM fallback for `snowflake/...` models. Snowflake Cortex currently supports Chat Completions only in CrewAI, so use the default `api` mode and do not set `api="responses"`.
+
+    ```toml Code
+    # Required
+    SNOWFLAKE_PAT=<your-programmatic-access-token>
+    SNOWFLAKE_ACCOUNT_URL=https://<account-identifier>.snowflakecomputing.com
+
+    # Alternative account configuration
+    SNOWFLAKE_ACCOUNT=<account-identifier>
+    ```
+
+    **Basic Usage:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/openai-gpt-4.1",
+        temperature=0.7,
+        max_completion_tokens=1024,
+    )
+    ```
+
+    **Claude Models on Cortex:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/claude-sonnet-4-5",
+        max_completion_tokens=1024,
+        stream=True,
+    )
+    ```
+
+    **Supported Environment Variables:**
+    - `SNOWFLAKE_PAT`, `SNOWFLAKE_TOKEN`, or `SNOWFLAKE_JWT`: token used as the Bearer credential
+    - `SNOWFLAKE_ACCOUNT_URL`: full Snowflake account URL
+    - `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_ACCOUNT_ID`, or `SNOWFLAKE_ACCOUNT_IDENTIFIER`: account identifier used to build the account URL
+
+    Snowflake REST requests use the user's default Snowflake role. Make sure that role has `SNOWFLAKE.CORTEX_USER` or `SNOWFLAKE.CORTEX_REST_API_USER`. Database, schema, warehouse, and explicit role parameters are not required by the Cortex REST Chat Completions endpoint.
+
+    **Features:**
+    - Native provider selection with `model="snowflake/<model-name>"`
+    - Streaming and non-streaming Chat Completions only; `api="responses"` is not supported
+    - Token usage tracking
+    - Function calling for Snowflake-hosted OpenAI and Claude models
+    - Automatic removal of invalid trailing assistant prefill for Snowflake Claude models
+  </Accordion>
+
   <Accordion title="Anthropic">
     CrewAI provides native integration with Anthropic through the Anthropic Python SDK.
 
@@ -903,6 +952,61 @@ In this section, you'll find detailed examples that help you select, configure,
     ```
   </Accordion>
 
+  <Accordion title="NVIDIA Nemotron">
+    NVIDIA Nemotron models are designed for demanding agentic workloads, including complex reasoning, long-context analysis, tool use, multilingual tasks, and high-stakes RAG.
+
+    The `NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` model is a frontier-scale open-weight model from NVIDIA with 550B total parameters and 55B active parameters. It uses a LatentMoE architecture that combines Mamba-2, MoE, Attention, and Multi-Token Prediction (MTP), and supports context lengths up to 1M tokens.
+
+    <Info>
+      `NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` is a very large model. NVIDIA lists minimum serving requirements of 4x GB200, 4x B200, 4x GB300, 4x B300, or 8x H100 GPUs. For most CrewAI users, the recommended path is to use NVIDIA NIM or another OpenAI-compatible hosted endpoint rather than running it locally.
+    </Info>
+
+    **Hosted NVIDIA NIM usage:**
+    ```toml Code
+    NVIDIA_API_KEY=<your-api-key>
+    ```
+
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="nvidia_nim/nvidia/nvidia-nemotron-3-ultra-550b-a55b",
+        temperature=0.2,
+        max_tokens=4096,
+    )
+    ```
+
+    **Self-hosted OpenAI-compatible endpoint:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="openai/nvidia-nemotron-3-ultra-550b-a55b-nvfp4",
+        base_url="https://your-nemotron-endpoint.example.com/v1",
+        api_key="your-api-key",
+        temperature=0.2,
+        max_tokens=4096,
+    )
+    ```
+
+    **Model details:**
+
+    | Model | Context Window | Best For |
+    |-------|----------------|----------|
+    | `nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` | Up to 1M tokens | Frontier reasoning, complex agentic workflows, long-context analysis, tool use, multilingual reasoning, and high-stakes RAG |
+
+    **Supported languages:** English, French, Spanish, Italian, German, Japanese, Korean, Hindi, Brazilian Portuguese, and Chinese.
+
+    **Reasoning mode:** Nemotron 3 Ultra supports configurable reasoning via its chat template using `enable_thinking=True` or `enable_thinking=False`. If you are using a hosted endpoint, check your provider's documentation for how that flag is exposed.
+
+    For model details, license, and deployment guidance, see the [NVIDIA Nemotron 3 Ultra model card](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4).
+
+    **Note:** Hosted NVIDIA NIM usage uses LiteLLM. Add it as a dependency to your project:
+    ```bash
+    uv add 'crewai[litellm]'
+    ```
+  </Accordion>
+
   <Accordion title="Local NVIDIA NIM Deployed using WSL2">
 
     NVIDIA NIM enables you to run powerful LLMs locally on your Windows machine using WSL2 (Windows Subsystem for Linux).

docs/en/concepts/memory.mdx

@@ -101,7 +101,7 @@ crew = Crew(
 )
 ```
 
-When `memory=True`, the crew creates a default `Memory()` and passes the crew's `embedder` configuration through automatically. All agents in the crew share the crew's memory unless an agent has its own.
+When `memory=True`, the crew creates a default `Memory()` and passes the crew's `embedder` configuration through automatically. All agents in the crew share the crew's memory unless an agent has its own. Without a custom `embedder`, memory uses OpenAI `text-embedding-3-large` embeddings.
 
 After each task, the crew automatically extracts discrete facts from the task output and stores them. Before each task, the agent recalls relevant context from memory and injects it into the task prompt.
 
@@ -515,7 +515,11 @@ memory = Memory(
 
 ## Embedder Configuration
 
-Memory needs an embedding model to convert text into vectors for semantic search. You can configure this in three ways.
+Memory needs an embedding model to convert text into vectors for semantic search. By default, `Memory()` uses OpenAI `text-embedding-3-large` embeddings, which produce 3072-dimensional vectors. Set `OPENAI_API_KEY` for the default path, or configure a custom embedder in one of three ways.
+
+<Warning>
+Existing local memory stores created with 1536-dimensional embeddings, such as `text-embedding-3-small` or `text-embedding-ada-002`, may not be compatible with the `text-embedding-3-large` default. This applies to both the OpenAI and Azure OpenAI providers — Azure's default embedding model also changed from `text-embedding-ada-002` to `text-embedding-3-large`. If local testing fails with an embedding dimension mismatch, reset memory with `crewai reset-memories -m`, delete the local memory storage directory, or explicitly configure the older embedder model until you migrate.
+</Warning>
 
 ### Passing to Memory Directly
 
@@ -523,7 +527,7 @@ Memory needs an embedding model to convert text into vectors for semantic search
 from crewai import Memory
 
 # As a config dict
-memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}})
+memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}})
 
 # As a pre-built callable
 from crewai.rag.embeddings.factory import build_embedder
@@ -542,7 +546,7 @@ crew = Crew(
     agents=[...],
     tasks=[...],
     memory=True,
-    embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}},
+    embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}},
 )
 ```
 
@@ -554,7 +558,7 @@ crew = Crew(
 memory = Memory(embedder={
     "provider": "openai",
     "config": {
-        "model_name": "text-embedding-3-small",
+        "model_name": "text-embedding-3-large",
         # "api_key": "sk-...",  # or set OPENAI_API_KEY env var
     },
 })
@@ -701,9 +705,9 @@ memory = Memory(embedder=my_embedder)
 
 | Provider | Key | Typical Model | Notes |
 | :--- | :--- | :--- | :--- |
-| OpenAI | `openai` | `text-embedding-3-small` | Default. Set `OPENAI_API_KEY`. |
+| OpenAI | `openai` | `text-embedding-3-large` | Default. Set `OPENAI_API_KEY`. |
 | Ollama | `ollama` | `mxbai-embed-large` | Local, no API key needed. |
-| Azure OpenAI | `azure` | `text-embedding-ada-002` | Requires `deployment_id`. |
+| Azure OpenAI | `azure` | `text-embedding-3-large` | Default model. Requires `deployment_id`. |
 | Google AI | `google-generativeai` | `gemini-embedding-001` | Set `GOOGLE_API_KEY`. |
 | Google Vertex | `google-vertex` | `gemini-embedding-001` | Requires `project_id`. |
 | Cohere | `cohere` | `embed-english-v3.0` | Strong multilingual support. |
@@ -836,6 +840,9 @@ class MemoryMonitor(BaseEventListener):
 **Background save errors in logs?**
 - Memory saves run in a background thread. Errors are emitted as `MemorySaveFailedEvent` but don't crash the agent. Check logs for the root cause (usually LLM or embedder connection issues).
 
+**Embedding dimension mismatch?**
+- Existing local memory stores may have been created with a different embedding model. The default OpenAI memory embedder is now `text-embedding-3-large` (3072 dimensions), while older stores commonly used 1536-dimensional embeddings. For local testing, run `crewai reset-memories -m`, delete the local memory storage directory, or configure the previous embedder model explicitly.
+
 **Concurrent write conflicts?**
 - LanceDB operations are serialized with a shared lock and retried automatically on conflict. This handles multiple `Memory` instances pointing at the same database (e.g. agent memory + crew memory). No action needed.
 
@@ -862,7 +869,7 @@ All configuration is passed as keyword arguments to `Memory(...)`. Every paramet
 | :--- | :--- | :--- |
 | `llm` | `"gpt-4o-mini"` | LLM for analysis (model name or `BaseLLM` instance). |
 | `storage` | `"lancedb"` | Storage backend (`"lancedb"`, a path string, or a `StorageBackend` instance). |
-| `embedder` | `None` (OpenAI default) | Embedder (config dict, callable, or `None` for default OpenAI). |
+| `embedder` | `None` (OpenAI `text-embedding-3-large`) | Embedder (config dict, callable, or `None` for default OpenAI). |
 | `recency_weight` | `0.3` | Weight for recency in composite score. |
 | `semantic_weight` | `0.5` | Weight for semantic similarity in composite score. |
 | `importance_weight` | `0.2` | Weight for importance in composite score. |

docs/en/concepts/processes.mdx

@@ -16,7 +16,6 @@ mode: "wide"
 
 - **Sequential**: Executes tasks sequentially, ensuring tasks are completed in an orderly progression.
 - **Hierarchical**: Organizes tasks in a managerial hierarchy, where tasks are delegated and executed based on a structured chain of command. A manager language model (`manager_llm`) or a custom manager agent (`manager_agent`) must be specified in the crew to enable the hierarchical process, facilitating the creation and management of tasks by the manager.
-- **Consensual Process (Planned)**: Aiming for collaborative decision-making among agents on task execution, this process type introduces a democratic approach to task management within CrewAI. It is planned for future development and is not currently implemented in the codebase.
 
 ## The Role of Processes in Teamwork
 Processes enable individual agents to operate as a cohesive unit, streamlining their efforts to achieve common objectives with efficiency and coherence.
@@ -59,9 +58,9 @@ Emulates a corporate hierarchy, CrewAI allows specifying a custom manager agent
 
 ## Process Class: Detailed Overview
 
-The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`). The consensual process is planned for future inclusion, emphasizing our commitment to continuous development and innovation.
+The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`).
 
 ## Conclusion
 
 The structured collaboration facilitated by processes within CrewAI is crucial for enabling systematic teamwork among agents. 
-This documentation has been updated to reflect the latest features, enhancements, and the planned integration of the Consensual Process, ensuring users have access to the most current and comprehensive information.
+This documentation has been updated to reflect the latest features and enhancements, ensuring users have access to the most current and comprehensive information.

docs/en/concepts/tasks.mdx

@@ -74,104 +74,54 @@ crew = Crew(
 
 ## Creating Tasks
 
-There are two ways to create tasks in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
+There are two common ways to create tasks in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**.
 
-### YAML Configuration (Recommended)
+### JSONC Configuration (Recommended)
 
-Using YAML configuration provides a cleaner, more maintainable way to define tasks. We strongly recommend using this approach to define tasks in your CrewAI projects.
+New projects created with `crewai create crew <name>` define tasks in `crew.jsonc`. The `agents` array points to files in `agents/`, and the `tasks` array defines the ordered work the crew should run.
 
-After creating your CrewAI project as outlined in the [Installation](/en/installation) section, navigate to the `src/latest_ai_development/config/tasks.yaml` file and modify the template to match your specific task requirements.
+After creating your CrewAI project as outlined in the [Installation](/en/installation) section, edit the generated `crew.jsonc`.
 
 <Note>
-Variables in your YAML files (like `{topic}`) will be replaced with values from your inputs when running the crew:
-```python Code
-crew.kickoff(inputs={'topic': 'AI Agents'})
-```
+Use `{placeholder}` values in task `description`, `expected_output`, and `output_file`. Put defaults in the top-level `inputs` object; `crewai run` prompts for any missing values.
 </Note>
 
-Here's an example of how to configure tasks using YAML:
+Here's an example `crew.jsonc` with two ordered tasks:
 
-````yaml tasks.yaml
-research_task:
-  description: >
-    Conduct a thorough research about {topic}
-    Make sure you find any interesting and relevant information given
-    the current year is 2025.
-  expected_output: >
-    A list with 10 bullet points of the most relevant information about {topic}
-  agent: researcher
-
-reporting_task:
-  description: >
-    Review the context you got and expand each topic into a full section for a report.
-    Make sure the report is detailed and contains any and all relevant information.
-  expected_output: >
-    A fully fledge reports with the mains topics, each with a full section of information.
-    Formatted as markdown without '```'
-  agent: reporting_analyst
-  markdown: true
-  output_file: report.md
+````jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "reporting_analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research about {topic}. Include current and relevant information.",
+      "expected_output": "A list of the most relevant information about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "reporting_task",
+      "description": "Review the research and expand it into a detailed report.",
+      "expected_output": "A polished markdown report without fenced code blocks.",
+      "agent": "reporting_analyst",
+      "context": ["research_task"],
+      "markdown": true,
+      "output_file": "report.md"
+    }
+  ],
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
 ````
 
-To use this YAML configuration in your code, create a crew class that inherits from `CrewBase`:
+Each task must include `description` and `expected_output`. The `agent` value should match an agent name listed in `agents`. `context` is a list of prior task names; forward references are rejected so sequential context stays explicit.
 
-```python crew.py
-# src/latest_ai_development/crew.py
+Task entries support any public `Task` field. Common fields include `name`, `agent`, `context`, `output_file`, `tools`, `human_input`, `async_execution`, `guardrail`, `guardrails`, `guardrail_max_retries`, `markdown`, `input_files`, `output_json`, `output_pydantic`, `response_model`, and `converter_cls`. Use `"type": "ConditionalTask"` with a `condition` field for conditional tasks.
 
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai_tools import SerperDevTool
+### Classic YAML Configuration
 
-@CrewBase
-class LatestAiDevelopmentCrew():
-  """LatestAiDevelopment crew"""
-
-  @agent
-  def researcher(self) -> Agent:
-    return Agent(
-      config=self.agents_config['researcher'], # type: ignore[index]
-      verbose=True,
-      tools=[SerperDevTool()]
-    )
-
-  @agent
-  def reporting_analyst(self) -> Agent:
-    return Agent(
-      config=self.agents_config['reporting_analyst'], # type: ignore[index]
-      verbose=True
-    )
-
-  @task
-  def research_task(self) -> Task:
-    return Task(
-      config=self.tasks_config['research_task'] # type: ignore[index]
-    )
-
-  @task
-  def reporting_task(self) -> Task:
-    return Task(
-      config=self.tasks_config['reporting_task'] # type: ignore[index]
-    )
-
-  @crew
-  def crew(self) -> Crew:
-    return Crew(
-      agents=[
-        self.researcher(),
-        self.reporting_analyst()
-      ],
-      tasks=[
-        self.research_task(),
-        self.reporting_task()
-      ],
-      process=Process.sequential
-    )
-```
-
-<Note>
-  The names you use in your YAML files (`agents.yaml` and `tasks.yaml`) should
-  match the method names in your Python code.
-</Note>
+Classic projects created with `crewai create crew <name> --classic` use `config/tasks.yaml` and a `@CrewBase` class in `crew.py`. This remains supported for existing YAML projects or teams that prefer decorator-based Python wiring.
 
 ### Direct Code Definition (Alternative)
 

docs/en/concepts/training.mdx

@@ -187,7 +187,7 @@ flowchart TD
 - **Filename Requirement:** Ensure that the filename ends with `.pkl`. The code will raise a `ValueError` if this condition is not met.
 - **Error Handling:** The code handles subprocess errors and unexpected exceptions, providing error messages to the user.
 - Trained guidance is applied at prompt time; it does not modify your Python/YAML agent configuration.
-- Agents automatically load trained suggestions from a file named `trained_agents_data.pkl` located in the current working directory. If you trained to a different filename, either rename it to `trained_agents_data.pkl` before running, or adjust the loader in code.
+- Agents automatically load trained suggestions from a file named `trained_agents_data.pkl` located in the current working directory. If you trained to a different filename, pass that path with `Crew(trained_agents_file="my_custom_trained.pkl")`, set `CREWAI_TRAINED_AGENTS_FILE`, or use `crewai run -f my_custom_trained.pkl`.
 - You can change the output filename when calling `crewai train` with `-f/--filename`. Absolute paths are supported if you want to save outside the CWD.
 
 It is important to note that the training process may take some time, depending on the complexity of your agents and will also require your feedback on each iteration.

docs/en/enterprise/features/agent-control-plane/monitoring.mdx

@@ -6,6 +6,14 @@ icon: "gauge"
 mode: "wide"
 ---
 
+<Info>
+  **ACP (Beta) Docs Navigation**
+
+  - [Overview](/en/enterprise/features/agent-control-plane/overview)
+  - **Monitoring** *(you are here)*
+  - [Rules](/en/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## Overview
 
 The **Automations** tab is the read-only operations view of the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview). It combines two metric cards, an interactive sankey, and two sub-tables — **Automations** and **Consumption** — that you can search, filter, and sort.

docs/en/enterprise/features/agent-control-plane/overview.mdx

@@ -5,6 +5,14 @@ sidebarTitle: Overview
 icon: "book-open"
 ---
 
+<Info>
+  **ACP (Beta) Docs Navigation**
+
+  - **Overview** *(you are here)*
+  - [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
+  - [Rules](/en/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## Overview
 
 The **Agent Control Plane** (ACP) is the operations hub for everything you have running on CrewAI AMP. It is a single screen — split into **Automations** and **Rules** tabs — that lets your team:

docs/en/enterprise/features/agent-control-plane/rules.mdx

@@ -6,6 +6,14 @@ icon: "shield-check"
 mode: "wide"
 ---
 
+<Info>
+  **ACP (Beta) Docs Navigation**
+
+  - [Overview](/en/enterprise/features/agent-control-plane/overview)
+  - [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
+  - **Rules** *(you are here)*
+</Info>
+
 ## Overview
 
 Rules let you apply policies — today: **PII Redaction** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them.

docs/en/enterprise/features/secrets-manager/verify-rotation.mdx

@@ -26,10 +26,10 @@ Before running this verification:
 
 ## Step 1 — Scaffold a Verification Crew
 
-Create a new crew project. The CrewAI CLI scaffolds the structure:
+Create a classic crew project because this example wires a Python tool through `crew.py`:
 
 ```bash
-crewai create crew rotation_verifier --skip_provider
+crewai create crew rotation_verifier --classic --skip_provider
 cd rotation_verifier
 ```
 

docs/en/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ Telemetry data follows the [OpenTelemetry GenAI semantic conventions](https://op
 
 1. In CrewAI AMP, go to **Settings** > **OpenTelemetry Collectors**.
 2. Click **Add Collector**.
-3. Select an integration type — **OpenTelemetry Traces** or **OpenTelemetry Logs**.
-4. Configure the connection:
-   - **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`).
-   - **Service Name** — A name to identify this service in your observability platform.
-   - **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs.
-   - **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one.
-5. Click **Save**.
+3. Select an integration:
+   - **OpenTelemetry Traces** and **OpenTelemetry Logs** — export to any OTLP-compatible collector or backend.
+   - **Datadog** — send traces straight to Datadog's OTLP intake, no separate collector or Datadog Agent required.
+4. Configure the connection. The fields depend on the integration you selected:
 
-<Frame>![OpenTelemetry Collector Configuration](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    **OpenTelemetry Traces** and **OpenTelemetry Logs** are separate integrations that share the same fields — pick the one matching the signal you want to export.
+
+    - **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`).
+    - **Service Name** — A name to identify this service in your observability platform.
+    - **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs.
+    - **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one.
+
+    <Frame>![OpenTelemetry collector configuration](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — Your Datadog site's OTLP host only, with no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — Your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+
+    The Datadog integration exports **traces**.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided.
+6. Click **Save**.
 
 <Tip>
   You can add multiple collectors — for example, one for traces and another for logs, or send to different backends for different purposes.

docs/en/enterprise/guides/deploy-to-amp.mdx

@@ -164,6 +164,12 @@ You need to push your crew to a GitHub repository. If you haven't created a crew
       ![Select Repository](/images/enterprise/select-repo.png)
     </Frame>
 
+    <Tip>
+      If your Crew or Flow is inside a monorepo subfolder, expand **Advanced**
+      and set a working directory before deploying. See
+      [Monorepo Deployments](/en/enterprise/guides/monorepo-deployments).
+    </Tip>
+
   </Step>
 
   <Step title="Set Environment Variables">
@@ -368,17 +374,17 @@ git push
 
 **Solution**: Verify your project matches the expected structure:
 
-- **Both Crews and Flows**: Must have entry point at `src/project_name/main.py`
-- **Crews**: Use a `run()` function as entry point
-- **Flows**: Use a `kickoff()` function as entry point
+- **JSON-first Crews**: Keep `crew.jsonc` or `crew.json` and `agents/` at the project root
+- **Classic Crews**: Use `src/project_name/main.py` with a `run()` entry point
+- **Flows**: Use `src/project_name/main.py` with a `kickoff()` entry point
 
 See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams.
 
-#### Missing CrewBase Decorator
+#### Missing CrewBase Decorator in a Classic Crew
 
 **Symptom**: "Crew not found", "Config not found", or agent/task configuration errors
 
-**Solution**: Ensure **all** crew classes use the `@CrewBase` decorator:
+**Solution**: For classic Python/YAML crews, ensure all crew classes use the `@CrewBase` decorator. JSON-first crews do not need this decorator.
 
 ```python
 from crewai.project import CrewBase, agent, crew, task
@@ -398,8 +404,8 @@ class YourCrew():
 ```
 
 <Info>
-  This applies to standalone Crews AND crews embedded inside Flow projects.
-  Every crew class needs the decorator.
+  This applies to classic Python crew classes, including classic crews embedded inside Flow projects.
+  JSON-first crews are validated from `crew.jsonc` and `agents/` instead.
 </Info>
 
 #### Incorrect pyproject.toml Type
@@ -436,8 +442,8 @@ type = "flow"
 **Solution**:
 1. Check the execution logs in the AMP dashboard (Traces tab)
 2. Verify all tools have required API keys configured
-3. Ensure agent configurations in `agents.yaml` are valid
-4. Check task configurations in `tasks.yaml` for syntax errors
+3. For JSON-first crews, validate `crew.jsonc` and the referenced files in `agents/`
+4. For classic crews, ensure `agents.yaml` and `tasks.yaml` are valid
 
 <Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
   Contact our support team for assistance with deployment issues or questions

docs/en/enterprise/guides/monorepo-deployments.mdx

@@ -0,0 +1,229 @@
+---
+title: "Monorepo Deployments"
+description: "Deploy a Crew or Flow from a subfolder in a larger repository"
+icon: "folder-tree"
+mode: "wide"
+---
+
+<Note>
+  Use a working directory when your Crew or Flow lives inside a larger
+  repository. CrewAI AMP validates, builds, tests, and runs the automation from
+  that subfolder instead of the repository root.
+</Note>
+
+## When to Use This
+
+Monorepo deployments are useful when one repository contains multiple
+automations, shared packages, or other application code:
+
+```text
+company-ai/
+|-- uv.lock
+|-- packages/
+|   `-- shared_tools/
+`-- crews/
+    |-- support_agent/
+    |   |-- pyproject.toml
+    |   |-- crew.jsonc
+    |   `-- agents/
+    |       `-- support_agent.jsonc
+    `-- research_flow/
+        |-- pyproject.toml
+        `-- src/
+            `-- research_flow/
+                `-- main.py
+```
+
+To deploy `support_agent`, set the working directory to:
+
+```text
+crews/support_agent
+```
+
+AMP still pulls or uploads the whole repository, but it treats the selected
+folder as the automation project root.
+
+## What the Working Directory Controls
+
+When a working directory is set, AMP uses that folder for:
+
+- Project validation, including `pyproject.toml`, JSON crew files, and any classic Crew or Flow entry point
+- Dependency installation with `uv`
+- The running process working directory
+- The `CREW_ROOT_DIR` environment variable
+
+Leaving the field empty keeps the existing behavior and uses the repository
+root.
+
+## Supported Sources
+
+You can set a working directory when creating a deployment from:
+
+- A connected GitHub repository
+- A Git repository configured in AMP
+- A ZIP upload
+
+<Info>
+  Configure working directories in the AMP web interface. The
+  `crewai deploy create` CLI flow does not prompt for this field.
+</Info>
+
+You can also add or change the working directory on an existing deployment from
+the deployment's **Settings** page. The change takes effect on the next deploy.
+
+<Warning>
+  Working directories and auto-deploy cannot be used together. If a deployment
+  has a working directory, auto-deploy is disabled for that deployment. Turn
+  auto-deploy off before setting a working directory.
+</Warning>
+
+## Configure a New Deployment
+
+<Steps>
+  <Step title="Open Deploy from Code">
+    In CrewAI AMP, create a new deployment and choose your source: GitHub, Git
+    Repository, or ZIP upload.
+  </Step>
+
+  <Step title="Select the repository, branch, or ZIP file">
+    Choose the repository and branch that contain your monorepo, or upload a ZIP
+    file whose root contains the monorepo contents.
+  </Step>
+
+  <Step title="Open Advanced settings">
+    Expand the **Advanced** section in the deploy form.
+  </Step>
+
+  <Step title="Enter the working directory">
+    Enter the path from the repository root to the Crew or Flow project:
+
+    ```text
+    crews/support_agent
+    ```
+
+    Do not include a leading slash.
+  </Step>
+
+  <Step title="Deploy">
+    Add any required environment variables, then start the deployment.
+  </Step>
+</Steps>
+
+## Configure an Existing Deployment
+
+<Steps>
+  <Step title="Open the deployment settings">
+    Go to your automation in AMP and open **Settings**.
+  </Step>
+
+  <Step title="Turn off auto-deploy if needed">
+    If auto-deploy is enabled, disable it first. The working directory field is
+    unavailable while auto-deploy is on.
+  </Step>
+
+  <Step title="Set the working directory">
+    In **Basic settings**, enter the subfolder path, such as:
+
+    ```text
+    crews/support_agent
+    ```
+  </Step>
+
+  <Step title="Redeploy">
+    Save the setting and redeploy the automation. The new working directory is
+    used on the next deploy.
+  </Step>
+</Steps>
+
+## Path Rules
+
+The working directory must be a relative path inside the repository or ZIP root.
+
+| Rule | Example |
+|------|---------|
+| Use a relative path | `crews/support_agent` |
+| Do not start with `/` | `/crews/support_agent` is invalid |
+| Do not use `.` or `..` path segments | `crews/../support_agent` is invalid |
+| Use only letters, numbers, dashes, underscores, dots, and forward slashes | `crews/support agent` is invalid |
+| Keep the path at 255 characters or fewer | Longer paths are rejected |
+
+AMP trims leading and trailing whitespace, collapses repeated slashes, and
+removes trailing slashes. A blank value uses the repository root.
+
+## Lock Files and UV Workspaces
+
+The selected folder must contain the automation's `pyproject.toml` and the
+project files for its type:
+
+- JSON-first crew: `crew.jsonc` or `crew.json`, plus `agents/`
+- Classic crew or Flow: `src/` with the expected Python entry point
+
+A `uv.lock` or `poetry.lock` file can live either in the selected folder or at
+the repository root.
+
+This supports both common lock-file layouts:
+
+<Tabs>
+  <Tab title="Project lock file">
+    ```text
+    company-ai/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- uv.lock
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+
+  <Tab title="Workspace lock file">
+    ```text
+    company-ai/
+    |-- uv.lock
+    |-- packages/
+    |   `-- shared_tools/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+</Tabs>
+
+<Tip>
+  If your automation imports shared packages from elsewhere in the monorepo,
+  declare those packages in `pyproject.toml` using UV workspace, path, or source
+  configuration. AMP runs the automation from the selected folder, so shared
+  code should be installed as a dependency instead of relying on the repository
+  root being on the Python path.
+</Tip>
+
+## Troubleshooting
+
+### Working Directory Not Found
+
+Check that the path is relative to the repository or ZIP root. For ZIP uploads,
+the ZIP contents must include the working directory path exactly as entered.
+
+### Missing pyproject.toml
+
+The working directory should point to the Crew or Flow project folder, not just
+to a parent folder that contains several projects.
+
+### Missing uv.lock or poetry.lock
+
+Commit a lock file either in the selected project folder or in the repository
+root. For UV workspaces, keeping `uv.lock` at the workspace root is supported.
+
+### Auto-Deploy Is Unavailable
+
+Auto-deploy is disabled while a working directory is set. Use manual redeploys
+or trigger redeployments from CI/CD with the AMP API instead.
+
+<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
+  Continue with the deployment guide after choosing your monorepo working
+  directory.
+</Card>

docs/en/enterprise/guides/prepare-for-deployment.mdx

@@ -24,7 +24,7 @@ Understanding which type you're deploying is essential because they have differe
 
 <CardGroup cols={2}>
   <Card title="Crew Projects" icon="users">
-    Standalone AI agent teams with `crew.py` defining agents and tasks. Best for focused, collaborative tasks.
+    Standalone AI agent teams. New crews are JSON-first with `crew.jsonc` and `agents/`; classic crews can still use `crew.py`.
   </Card>
   <Card title="Flow Projects" icon="diagram-project">
     Orchestrated workflows with embedded crews in a `crews/` folder. Best for complex, multi-stage processes.
@@ -33,19 +33,19 @@ Understanding which type you're deploying is essential because they have differe
 
 | Aspect | Crew | Flow |
 |--------|------|------|
-| **Project structure** | `src/project_name/` with `crew.py` | `src/project_name/` with `crews/` folder |
-| **Main logic location** | `src/project_name/crew.py` | `src/project_name/main.py` (Flow class) |
-| **Entry point function** | `run()` in `main.py` | `kickoff()` in `main.py` |
+| **Project structure** | Project root with `crew.jsonc` and `agents/` | `src/project_name/` with `crews/` folder |
+| **Main logic location** | `crew.jsonc` (classic: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow class) |
+| **Entry point function** | Loaded from `crew.jsonc` (classic: `run()` in `main.py`) | `kickoff()` in `main.py` |
 | **pyproject.toml type** | `type = "crew"` | `type = "flow"` |
 | **CLI create command** | `crewai create crew name` | `crewai create flow name` |
-| **Config location** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` |
+| **Config location** | `crew.jsonc`, `agents/`, optional `tools/` | `src/project_name/crews/crew_name/config/` or embedded JSON crew folders |
 | **Can contain other crews** | No | Yes (in `crews/` folder) |
 
 ## Project Structure Reference
 
 ### Crew Project Structure
 
-When you run `crewai create crew my_crew`, you get this structure:
+When you run `crewai create crew my_crew`, you get the JSON-first structure:
 
 ```
 my_crew/
@@ -54,24 +54,27 @@ my_crew/
 ├── README.md
 ├── .env
 ├── uv.lock                  # REQUIRED for deployment
-└── src/
-    └── my_crew/
-        ├── __init__.py
-        ├── main.py          # Entry point with run() function
-        ├── crew.py          # Crew class with @CrewBase decorator
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml  # Agent definitions
-            └── tasks.yaml   # Task definitions
+├── crew.jsonc               # Crew settings, tasks, process, inputs
+├── agents/
+│   └── researcher.jsonc     # Agent definitions
+├── tools/                   # Optional custom:<name> tools
+├── knowledge/
+└── skills/
 ```
 
 <Warning>
-  The nested `src/project_name/` structure is critical for Crews.
-  Placing files at the wrong level will cause deployment failures.
+  For JSON-first crews, keep `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, and `skills/`
+  at the project root. Placing them under `src/` will prevent `crewai run` and deployment
+  validation from finding the crew definition.
 </Warning>
 
+<Info>
+  Classic projects created with `crewai create crew my_crew --classic` use the older
+  `src/project_name/crew.py`, `src/project_name/config/agents.yaml`, and
+  `src/project_name/config/tasks.yaml` layout. That layout remains supported for
+  decorator-based Python crews.
+</Info>
+
 ### Flow Project Structure
 
 When you run `crewai create flow my_flow`, you get this structure:
@@ -100,9 +103,9 @@ my_flow/
 ```
 
 <Info>
-  Both Crews and Flows use the `src/project_name/` structure.
-  The key difference is that Flows have a `crews/` folder for embedded crews,
-  while Crews have `crew.py` directly in the project folder.
+  JSON-first standalone crews use project-root JSON files. Flows still use
+  `src/project_name/` and can contain either classic embedded crews or embedded
+  JSON crew folders loaded with `crewai.project.load_crew`.
 </Info>
 
 ## Pre-Deployment Checklist
@@ -154,60 +157,91 @@ git commit -m "Add uv.lock for deployment"
 git push
 ```
 
-### 3. Validate CrewBase Decorator Usage
+### 3. Validate the Crew Definition
 
-**Every crew class must use the `@CrewBase` decorator.** This applies to:
+<Tabs>
+  <Tab title="JSON-first Crews">
+    JSON-first crews must have a `crew.jsonc` or `crew.json` file at the project root.
+    The `agents` array must reference files in `agents/`, and each task should reference
+    a valid agent name.
 
-- Standalone crew projects
-- Crews embedded inside Flow projects
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "Research {topic}.",
+          "expected_output": "A concise report.",
+          "agent": "researcher"
+        }
+      ],
+      "inputs": {
+        "topic": "AI Agents"
+      }
+    }
+    ```
 
-```python
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+    Custom tools are referenced as `"custom:<name>"` and must be implemented in
+    `tools/<name>.py` with a `BaseTool` subclass.
+  </Tab>
+  <Tab title="Classic Python/YAML Crews">
+    Classic crews and Python crews embedded in Flows must use the `@CrewBase` decorator.
 
-@CrewBase  # This decorator is REQUIRED
-class MyCrew():
-    """My crew description"""
+    ```python
+    from crewai import Agent, Crew, Process, Task
+    from crewai.project import CrewBase, agent, crew, task
+    from crewai.agents.agent_builder.base_agent import BaseAgent
+    from typing import List
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
+    @CrewBase
+    class MyCrew():
+        """My crew description"""
 
-    @agent
-    def my_agent(self) -> Agent:
-        return Agent(
-            config=self.agents_config['my_agent'],  # type: ignore[index]
-            verbose=True
-        )
+        agents: List[BaseAgent]
+        tasks: List[Task]
 
-    @task
-    def my_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['my_task']  # type: ignore[index]
-        )
+        @agent
+        def my_agent(self) -> Agent:
+            return Agent(
+                config=self.agents_config['my_agent'],  # type: ignore[index]
+                verbose=True
+            )
 
-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
+        @task
+        def my_task(self) -> Task:
+            return Task(
+                config=self.tasks_config['my_task']  # type: ignore[index]
+            )
 
-<Warning>
-  If you forget the `@CrewBase` decorator, your deployment will fail with
-  errors about missing agents or tasks configurations.
-</Warning>
+        @crew
+        def crew(self) -> Crew:
+            return Crew(
+                agents=self.agents,
+                tasks=self.tasks,
+                process=Process.sequential,
+                verbose=True,
+            )
+    ```
+  </Tab>
+</Tabs>
 
 ### 4. Check Project Entry Points
 
-Both Crews and Flows have their entry point in `src/project_name/main.py`:
+JSON-first standalone crews do not need a hand-written `src/project_name/main.py`; `crewai run`
+and deployment packaging load `crew.jsonc` directly. Classic crews and Flows use Python entry
+points:
 
 <Tabs>
-  <Tab title="For Crews">
+  <Tab title="JSON-first Crews">
+    Run locally from the project root:
+
+    ```bash
+    crewai run
+    ```
+  </Tab>
+  <Tab title="Classic Crews">
     The entry point uses a `run()` function:
 
     ```python
@@ -278,16 +312,17 @@ grep -A2 "\[tool.crewai\]" pyproject.toml
 # 2. Verify uv.lock exists
 ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'"
 
-# 3. Verify src/ structure exists
-ls -la src/*/main.py 2>/dev/null || echo "No main.py found in src/"
+# 3. For JSON-first crews, verify crew.jsonc and agents/ exist
+([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found"
+test -d agents || echo "No agents/ directory found"
 
-# 4. For Crews - verify crew.py exists
+# 4. For classic Crews - verify crew.py exists
 ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)"
 
 # 5. For Flows - verify crews/ folder exists
 ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)"
 
-# 6. Check for CrewBase usage
+# 6. For classic Python crews - check for CrewBase usage
 grep -r "@CrewBase" . --include="*.py"
 ```
 
@@ -297,8 +332,9 @@ grep -r "@CrewBase" . --include="*.py"
 |---------|---------|-----|
 | Missing `uv.lock` | Build fails during dependency resolution | Run `uv lock` and commit |
 | Wrong `type` in pyproject.toml | Build succeeds but runtime fails | Change to correct type |
-| Missing `@CrewBase` decorator | "Config not found" errors | Add decorator to all crew classes |
-| Files at root instead of `src/` | Entry point not found | Move to `src/project_name/` |
+| Missing `crew.jsonc` or `agents/` in a JSON-first crew | Crew definition not found | Keep `crew.jsonc` and `agents/` at the project root |
+| Missing `@CrewBase` decorator in a classic crew | "Config not found" errors | Add decorator to all classic crew classes |
+| Classic files at root instead of `src/` | Entry point not found | Move classic Python files to `src/project_name/` |
 | Missing `run()` or `kickoff()` | Cannot start automation | Add correct entry function |
 
 ## Next Steps

docs/en/enterprise/integrations/databricks.mdx

@@ -0,0 +1,123 @@
+---
+title: Databricks Integration
+description: "Connect CrewAI agents to Databricks Genie, SQL, Unity Catalog Functions, and Vector Search through Databricks managed MCP servers."
+icon: "layer-group"
+mode: "wide"
+---
+
+## Overview
+
+Connect your CrewAI agents directly to your Databricks workspace through [Databricks managed MCP servers](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). The Databricks integration lets your agents ask natural-language questions with **Genie**, run governed **SQL**, call **Unity Catalog Functions**, and retrieve documents with **Vector Search** — all without writing or hosting any connector code, and with Unity Catalog permissions enforced on every call.
+
+Under the hood, the Databricks integration is a managed wrapper around CrewAI's [Custom MCP Server](/en/enterprise/guides/custom-mcp-server) support. Databricks exposes each capability as its own [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to them securely on your behalf. Because each server is added separately, you can enable exactly the capabilities your crews need.
+
+## Key Capabilities
+
+<CardGroup cols={2}>
+  <Card title="Genie" icon="comments">
+    Ask questions in plain language and get grounded answers from your data with [Genie](https://docs.databricks.com/aws/en/genie/), which queries Genie Spaces and Unity Catalog and links back to the Databricks UI.
+  </Card>
+  <Card title="Databricks SQL" icon="database">
+    Run governed SQL against your Databricks warehouses to query, transform, and author data pipelines directly from your agents.
+  </Card>
+  <Card title="Unity Catalog Functions" icon="function">
+    Invoke [Unity Catalog functions](https://docs.databricks.com/aws/en/udf/unity-catalog) to run predefined SQL and custom business logic as governed, reusable tools.
+  </Card>
+  <Card title="Vector Search" icon="magnifying-glass">
+    Retrieve relevant documents for RAG and knowledge workflows from [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) indexes using semantic similarity.
+  </Card>
+</CardGroup>
+
+Every server runs behind the Unity AI Gateway and enforces Unity Catalog access controls, so your agents only ever see the data and tools they're permitted to use.
+
+## Prerequisites
+
+Before using the Databricks integration, ensure you have:
+
+- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
+- A Databricks workspace with the capabilities you want to expose (Genie Spaces, SQL warehouses, Unity Catalog functions, or Vector Search indexes)
+- Appropriate [Unity Catalog privileges](https://docs.databricks.com/aws/en/data-governance/unity-catalog) on the underlying objects
+- Your Databricks workspace hostname (e.g. `your-workspace.cloud.databricks.com`)
+
+## Databricks Managed MCP Servers
+
+Databricks publishes a separate managed MCP server for each capability. CrewAI exposes these as individual connections, each configured with your workspace host and the relevant Unity Catalog identifiers. The endpoints follow these patterns:
+
+| Server | What it does | MCP URL pattern |
+|--------|--------------|-----------------|
+| **Genie** | Natural-language Q&A over a Genie Space | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
+| **Databricks SQL** | Execute SQL against your warehouses | `https://<workspace-hostname>/api/2.0/mcp/sql` |
+| **Unity Catalog Functions** | Run registered UC functions | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
+| **Vector Search** | Query a Vector Search index | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
+
+<Note>
+You don't construct these URLs by hand — CrewAI builds each endpoint from the workspace host and identifiers (Genie Space ID, or catalog/schema) you provide when configuring the connection. For the full specification and the latest endpoint details, see the [Databricks managed MCP documentation](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp).
+</Note>
+
+## Connecting Databricks in CrewAI AMP
+
+<Frame>
+    <img src="/images/enterprise/databricks-configure.png" alt="Configure a Databricks managed MCP server in CrewAI AMP" />
+</Frame>
+
+Each Databricks capability — **Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, and **Databricks Vector Search** — appears as its own MCP server under the Databricks group on the **Tools & Integrations** page. Configure the ones you need:
+
+<Steps>
+    <Step title="Open Tools & Integrations">
+        Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP and locate the **Databricks** group in the Connections list. You'll see the Genie, SQL, Unity Catalog Functions, and Vector Search servers listed beneath it.
+    </Step>
+
+    <Step title="Configure a server">
+        Click **Configure** next to the capability you want to enable and provide its connection details:
+
+        - **Workspace Host** — your Databricks workspace hostname (e.g. `my-workspace.cloud.databricks.com`).
+        - **Genie** — the **Genie Space ID** to query.
+        - **Unity Catalog Functions** — the **catalog** and **schema** that contain your functions.
+        - **Vector Search** — the **catalog** and **schema** that contain your index.
+        - **Databricks SQL** — no additional identifiers; queries run against your workspace's SQL warehouses.
+    </Step>
+
+    <Step title="Choose an authentication method">
+        Select how CrewAI authenticates to Databricks. **OAuth** is recommended.
+
+        - **Use OAuth** — Connect securely using OAuth 2.0. Each user authenticates individually, and Databricks issues tokens scoped to the capability (`genie`, `sql`, `unity-catalog`, or `vector-search`). CrewAI handles the authorization flow and refreshes tokens automatically.
+        - **Use personal access token** — Authenticate with a [Databricks personal access token](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Use a least-privileged identity to limit exposure.
+    </Step>
+
+    <Step title="Authenticate">
+        Complete authentication. Once connected, the server's tools become available to your crews. Repeat for any other Databricks capabilities you want to enable.
+    </Step>
+</Steps>
+
+<Tip>
+Because each capability is a separate connection, you can mix and match — for example, enable Genie and Vector Search for a research crew while reserving SQL and Unity Catalog Functions for a data-engineering crew. Visibility settings let you control which team members can use each one.
+</Tip>
+
+## Using Databricks Tools in Your Crews
+
+Once connected, the tools each MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can:
+
+- **Assign tools to agents** in your crews just like any other CrewAI tool.
+- **Manage visibility** to control which team members can use each connection.
+- **Edit or remove** any connection at any time from the Connections list.
+
+Your agents can now ask Genie for grounded answers, run SQL against your warehouses, call Unity Catalog functions, and search Vector Search indexes — with results flowing back into their reasoning automatically.
+
+<Warning>
+Databricks enforces governance through Unity Catalog and the Unity AI Gateway: a user can only discover and invoke tools their workspace identity is permitted to use. If a tool call fails, confirm the connecting user (or token identity) has the required Unity Catalog privileges on the Genie Space, warehouse, function, or index. Some Genie and SQL queries run asynchronously and may take a moment to return results.
+</Warning>
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card title="Databricks Managed MCP Servers" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
+    Official Databricks documentation for the managed Genie, SQL, Unity Catalog Functions, and Vector Search MCP servers.
+  </Card>
+  <Card title="Custom MCP Servers in CrewAI" icon="plug" href="/en/enterprise/guides/custom-mcp-server">
+    Learn how CrewAI connects to any MCP server, the foundation the Databricks integration builds on.
+  </Card>
+</CardGroup>
+
+<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
+  Contact our support team for assistance with the Databricks integration or troubleshooting.
+</Card>

docs/en/enterprise/integrations/snowflake.mdx

@@ -0,0 +1,134 @@
+---
+title: Snowflake Integration
+description: "Connect CrewAI agents to Snowflake Cortex Analyst, Cortex Search, and SQL execution through the Snowflake-managed MCP server."
+icon: "snowflake"
+mode: "wide"
+---
+
+## Overview
+
+Connect your CrewAI agents directly to your Snowflake data through the [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). The Snowflake integration lets your agents query structured data with **Cortex Analyst**, search unstructured data with **Cortex Search**, and run governed SQL against your warehouses — all without writing or hosting any connector code.
+
+Under the hood, the Snowflake integration is a managed wrapper around CrewAI's [Custom MCP Server](/en/enterprise/guides/custom-mcp-server) support. Snowflake exposes its Cortex AI capabilities through a [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to it securely on your behalf. Any tool you expose on the Snowflake side — Cortex Analyst, Cortex Search, SQL execution, Cortex Agents, or your own custom tools — becomes available to your crews.
+
+## Key Capabilities
+
+<CardGroup cols={3}>
+  <Card title="Cortex Analyst" icon="chart-bar">
+    Ask questions in natural language and let [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) generate and run SQL against your **structured** data using rich semantic models.
+  </Card>
+  <Card title="Cortex Search" icon="magnifying-glass">
+    Retrieve relevant **unstructured** data for RAG and knowledge workflows with [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview), Snowflake's fully managed search service.
+  </Card>
+  <Card title="SQL Execution" icon="database">
+    Run governed SQL queries directly against your Snowflake warehouses, with configurable read-only mode, timeouts, and warehouse selection.
+  </Card>
+</CardGroup>
+
+Because the integration surfaces whatever tools your MCP server publishes, you can also expose **Cortex Agents** and **custom tools** (user-defined functions and stored procedures) to your CrewAI agents.
+
+## Prerequisites
+
+Before using the Snowflake integration, ensure you have:
+
+- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
+- A Snowflake account with access to Cortex AI features
+- A [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) configured with the tools you want to expose
+- Appropriate Snowflake privileges (USAGE/SELECT) on the MCP server and its underlying objects
+
+## Setting Up the Snowflake MCP Server
+
+The Snowflake-managed MCP server runs inside your Snowflake account and defines which tools are available to external clients like CrewAI. Create one with the [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) command, listing the Cortex Search services, Cortex Analyst semantic views, and SQL tools you want to expose.
+
+```sql
+CREATE MCP SERVER my_mcp_server
+  FROM SPECIFICATION $$
+    tools:
+      - name: "sales_analyst"
+        type: "CORTEX_ANALYST"
+        identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view"
+        description: "Answer questions about sales metrics"
+      - name: "docs_search"
+        type: "CORTEX_SEARCH_SERVICE_QUERY"
+        identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search"
+        description: "Search internal support documentation"
+      - name: "run_sql"
+        type: "SQL_EXECUTION"
+        description: "Execute read-only SQL queries"
+  $$;
+```
+
+<Note>
+The MCP endpoint follows the format `https://<account_URL>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. CrewAI builds this URL automatically from the **Account URL**, **Database**, **Schema**, and **MCP Server Name** you provide when configuring the integration.
+</Note>
+
+For the complete specification — including Cortex Agents, custom tools, response-size limits, and governance options — see the [Snowflake-managed MCP server documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp).
+
+## Connecting Snowflake in CrewAI AMP
+
+<Frame>
+    <img src="/images/enterprise/snowflake-configure.png" alt="Configure Snowflake integration in CrewAI AMP" />
+</Frame>
+
+<Steps>
+    <Step title="Open Tools & Integrations">
+        Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, find **Snowflake** in the list of applications, and open its configuration panel.
+    </Step>
+
+    <Step title="Provide connection details">
+        Fill in the connection fields that CrewAI uses to reach your Snowflake MCP server:
+
+        | Field | Required | Description |
+        |-------|----------|-------------|
+        | **Name** | Yes | A descriptive name for this connection (defaults to `Snowflake`). |
+        | **Description** | No | An optional summary of what this connection provides. |
+        | **Account URL** | Yes | Your Snowflake account URL, e.g. `xy12345.us-east-1.snowflakecomputing.com`. |
+        | **Database** | Yes | The database that contains your MCP server (e.g. `MY_DATABASE`). |
+        | **Schema** | Yes | The schema that contains your MCP server (e.g. `MY_SCHEMA`). |
+        | **MCP Server Name** | Yes | The name of the MCP server object you created in Snowflake (e.g. `MY_MCP_SERVER`). |
+    </Step>
+
+    <Step title="Choose an authentication method">
+        Select how CrewAI authenticates to Snowflake. **OAuth** is recommended.
+
+        - **Use OAuth** — Connect securely using OAuth 2.0 for token-based authentication without sharing your credentials. CrewAI handles the full authorization flow and refreshes tokens automatically. Copy the **Redirect URI** shown in the form (`https://oauth.crewai.com/oauth/add`) and register it as an authorized redirect URI in your Snowflake [OAuth security integration](https://docs.snowflake.com/en/user-guide/oauth-custom).
+        - **Use personal access token** — Authenticate using a [programmatic access token](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) generated from your Snowflake account settings. Assign a least-privileged role to the token to limit exposure.
+    </Step>
+
+    <Step title="Authenticate">
+        Click **Authenticate**. For OAuth, you'll be redirected to Snowflake to authorize access. Once authenticated, the Snowflake server appears in your Connections and its tools become available to your crews.
+    </Step>
+</Steps>
+
+<Tip>
+With OAuth, each user authenticates individually and queries run with their Snowflake `DEFAULT_ROLE`. Make sure connecting users have a default role and warehouse set (`ALTER USER <username> SET DEFAULT_ROLE = '<role>' DEFAULT_WAREHOUSE = '<warehouse>'`) so Cortex Analyst and SQL tools have compute to run on.
+</Tip>
+
+## Using Snowflake Tools in Your Crews
+
+Once connected, the tools your MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can:
+
+- **Assign tools to agents** in your crews just like any other CrewAI tool.
+- **Manage visibility** to control which team members can use the connection.
+- **Edit or remove** the connection at any time from the Connections list.
+
+Your agents can now ask Cortex Analyst for metrics, run Cortex Search over your documents, and execute SQL — with results flowing back into their reasoning automatically.
+
+<Warning>
+Snowflake enforces governance on the MCP server: role-based access control determines which tools a user can discover and invoke, and limits apply to response size, tool count (max 50 per server), and recursion depth. If a tool call fails, confirm the connecting user's role has the required privileges on the MCP server and its underlying objects.
+</Warning>
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card title="Snowflake-managed MCP Server" icon="snowflake" href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp">
+    Official Snowflake documentation for creating and governing the MCP server.
+  </Card>
+  <Card title="Custom MCP Servers in CrewAI" icon="plug" href="/en/enterprise/guides/custom-mcp-server">
+    Learn how CrewAI connects to any MCP server, the foundation the Snowflake integration builds on.
+  </Card>
+</CardGroup>
+
+<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
+  Contact our support team for assistance with the Snowflake integration or troubleshooting.
+</Card>

docs/en/guides/advanced/customizing-prompts.mdx

@@ -161,6 +161,18 @@ crew = Crew(
 )
 ```
 
+<Note>
+`agent.i18n` is maintained only for backward compatibility and is deprecated. For runtime prompt customization, pass `prompt_file` to `Crew`. For programmatic access to prompt slices, use the i18n utility directly:
+</Note>
+
+```python
+from crewai.utilities.i18n import get_i18n
+
+i18n = get_i18n("custom_prompts.json")
+format_slice = i18n.slice("format")
+tool_prompt = i18n.tools("ask_question")
+```
+
 #### Option 3: Disable System Prompts for o1 Models
 ```python
 agent = Agent(
@@ -208,6 +220,8 @@ One straightforward approach is to create a JSON file for the prompts you want t
 
 CrewAI then merges your customizations with the defaults, so you don't have to redefine every prompt. Here's how:
 
+For code that needs to read prompt slices directly, use `crewai.utilities.i18n.get_i18n()` with the same prompt file instead of reading `agent.i18n`.
+
 ### Example: Basic Prompt Customization
 
 Create a `custom_prompts.json` file with the prompts you want to modify. Ensure you list all top-level prompts it should contain, not just your changes:

docs/en/guides/coding-tools/build-with-ai.mdx

@@ -43,7 +43,7 @@ CrewAI is AI-native. This page brings together everything an AI coding agent nee
 
     | Skill | When it runs |
     |-------|--------------|
-    | `getting-started` | Scaffolding new projects, choosing between `LLM.call()` / `Agent` / `Crew` / `Flow`, wiring `crew.py` / `main.py` |
+    | `getting-started` | Scaffolding new projects, choosing between `LLM.call()` / `Agent` / `Crew` / `Flow`, wiring `crew.jsonc` / `main.py` |
     | `design-agent` | Configuring agents — role, goal, backstory, tools, LLMs, memory, guardrails |
     | `design-task` | Writing task descriptions, dependencies, structured output (`output_pydantic`, `output_json`), human review |
     | `ask-docs` | Querying the live [CrewAI docs MCP server](https://docs.crewai.com/mcp) for up-to-date API details |
@@ -64,7 +64,7 @@ CrewAI is AI-native. This page brings together everything an AI coding agent nee
   <Step title="Your agent gets instant CrewAI expertise">
     The skill pack teaches your agent:
     - **Flows** — stateful apps, steps, and crew kickoffs
-    - **Crews & Agents** — YAML-first patterns, roles, tasks, delegation
+    - **Crews & Agents** — JSON-first patterns (`crew.jsonc`, `agents/*.jsonc`), roles, tasks, delegation
     - **Tools & Integrations** — search, APIs, MCP servers, and common CrewAI tools
     - **Project layout** — CLI scaffolds and repo conventions
     - **Up-to-date patterns** — tracks current CrewAI docs and best practices

docs/en/guides/concepts/evaluating-use-cases.mdx

@@ -172,7 +172,7 @@ Flows are ideal when:
 
 ```python
 # Example: Customer Support Flow with structured processing
-from crewai.flow.flow import Flow, listen, router, start
+from crewai.flow.flow import Flow, listen, or_, router, start
 from pydantic import BaseModel
 from typing import List, Dict
 
@@ -238,7 +238,7 @@ class CustomerSupportFlow(Flow[SupportTicketState]):
 
     # Additional category handlers...
 
-    @listen("billing", "account_access", "technical_issue", "feature_request", "other")
+    @listen(or_("billing", "account_access", "technical_issue", "feature_request", "other"))
     def resolve_ticket(self, resolution_info):
         # Final resolution step
         self.state.resolution = f"Issue resolved: {resolution_info}"

docs/en/guides/crews/first-crew.mdx

@@ -1,396 +1,162 @@
 ---
 title: Build Your First Crew
-description: Step-by-step tutorial to create a collaborative AI team that works together to solve complex problems.
+description: Step-by-step tutorial to create a collaborative AI team with JSON-first crew configuration.
 icon: users-gear
 mode: "wide"
 ---
 
-## Unleashing the Power of Collaborative AI
+## Build a Research Crew
 
-Imagine having a team of specialized AI agents working together seamlessly to solve complex problems, each contributing their unique skills to achieve a common goal. This is the power of CrewAI - a framework that enables you to create collaborative AI systems that can accomplish tasks far beyond what a single AI could achieve alone.
-
-In this guide, we'll walk through creating a research crew that will help us research and analyze a topic, then create a comprehensive report. This practical example demonstrates how AI agents can collaborate to accomplish complex tasks, but it's just the beginning of what's possible with CrewAI.
-
-### What You'll Build and Learn
-
-By the end of this guide, you'll have:
-
-1. **Created a specialized AI research team** with distinct roles and responsibilities
-2. **Orchestrated collaboration** between multiple AI agents
-3. **Automated a complex workflow** that involves gathering information, analysis, and report generation
-4. **Built foundational skills** that you can apply to more ambitious projects
-
-While we're building a simple research crew in this guide, the same patterns and techniques can be applied to create much more sophisticated teams for tasks like:
-
-- Multi-stage content creation with specialized writers, editors, and fact-checkers
-- Complex customer service systems with tiered support agents
-- Autonomous business analysts that gather data, create visualizations, and generate insights
-- Product development teams that ideate, design, and plan implementation
-
-Let's get started building your first crew!
+In this guide, you will create a two-agent research crew that gathers information about a topic and writes a markdown report. New crew projects are JSON-first: agents are defined in `agents/*.jsonc`, tasks and crew settings are defined in `crew.jsonc`, and `crewai run` loads the JSON definition directly.
 
 ### Prerequisites
 
 Before starting, make sure you have:
 
 1. Installed CrewAI following the [installation guide](/en/installation)
-2. Set up your LLM API key in your environment, following the [LLM setup
-   guide](/en/concepts/llms#setting-up-your-llm)
-3. Basic understanding of Python
+2. Set up your LLM API key following the [LLM setup guide](/en/concepts/llms#setting-up-your-llm)
+3. A [Serper.dev](https://serper.dev/) API key if you want the researcher to use web search
 
-## Step 1: Create a New CrewAI Project
-
-First, let's create a new CrewAI project using the CLI. This command will set up a complete project structure with all the necessary files, allowing you to focus on defining your agents and their tasks rather than setting up boilerplate code.
+## Step 1: Create a New Crew
 
 ```bash
 crewai create crew research_crew
 cd research_crew
 ```
 
-This will generate a project with the basic structure needed for your crew. The CLI automatically creates:
+The CLI creates a JSON-first project:
 
-- A project directory with the necessary files
-- Configuration files for agents and tasks
-- A basic crew implementation
-- A main script to run the crew
-
-<Frame caption="CrewAI Framework Overview">
-  <img src="/images/crews.png" alt="CrewAI Framework Overview" />
-</Frame>
-
-
-## Step 2: Explore the Project Structure
-
-Let's take a moment to understand the project structure created by the CLI. CrewAI follows best practices for Python projects, making it easy to maintain and extend your code as your crews become more complex.
-
-```
+```text
 research_crew/
 ├── .gitignore
+├── .env
+├── agents/
+│   └── researcher.jsonc
+├── crew.jsonc
+├── knowledge/
 ├── pyproject.toml
 ├── README.md
-├── .env
-└── src/
-    └── research_crew/
-        ├── __init__.py
-        ├── main.py
-        ├── crew.py
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml
-            └── tasks.yaml
+├── skills/
+└── tools/
 ```
 
-This structure follows best practices for Python projects and makes it easy to organize your code. The separation of configuration files (in YAML) from implementation code (in Python) makes it easy to modify your crew's behavior without changing the underlying code.
+<Tip>
+Need the older `crew.py`, `config/agents.yaml`, and `config/tasks.yaml` layout? Create it with `crewai create crew research_crew --classic`.
+</Tip>
 
-## Step 3: Configure Your Agents
+## Step 2: Define Your Agents
 
-Now comes the fun part - defining your AI agents! In CrewAI, agents are specialized entities with specific roles, goals, and backstories that shape their behavior. Think of them as characters in a play, each with their own personality and purpose.
+Replace the generated `agents/researcher.jsonc` file and add `agents/analyst.jsonc`. The file names are the names you reference from `crew.jsonc`.
 
-For our research crew, we'll create two agents:
-1. A **researcher** who excels at finding and organizing information
-2. An **analyst** who can interpret research findings and create insightful reports
-
-Let's modify the `agents.yaml` file to define these specialized agents. Be sure
-to set `llm` to the provider you are using.
-
-```yaml
-# src/research_crew/config/agents.yaml
-researcher:
-  role: >
-    Senior Research Specialist for {topic}
-  goal: >
-    Find comprehensive and accurate information about {topic}
-    with a focus on recent developments and key insights
-  backstory: >
-    You are an experienced research specialist with a talent for
-    finding relevant information from various sources. You excel at
-    organizing information in a clear and structured manner, making
-    complex topics accessible to others.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
-
-analyst:
-  role: >
-    Data Analyst and Report Writer for {topic}
-  goal: >
-    Analyze research findings and create a comprehensive, well-structured
-    report that presents insights in a clear and engaging way
-  backstory: >
-    You are a skilled analyst with a background in data interpretation
-    and technical writing. You have a talent for identifying patterns
-    and extracting meaningful insights from research data, then
-    communicating those insights effectively through well-crafted reports.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
+```jsonc agents/researcher.jsonc
+{
+  "role": "Senior Research Specialist for {topic}",
+  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
+  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
+  // Replace with your model, for example "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-Notice how each agent has a distinct role, goal, and backstory. These elements aren't just descriptive - they actively shape how the agent approaches its tasks. By crafting these carefully, you can create agents with specialized skills and perspectives that complement each other.
-
-## Step 4: Define Your Tasks
-
-With our agents defined, we now need to give them specific tasks to perform. Tasks in CrewAI represent the concrete work that agents will perform, with detailed instructions and expected outputs.
-
-For our research crew, we'll define two main tasks:
-1. A **research task** for gathering comprehensive information
-2. An **analysis task** for creating an insightful report
-
-Let's modify the `tasks.yaml` file:
-
-```yaml
-# src/research_crew/config/tasks.yaml
-research_task:
-  description: >
-    Conduct thorough research on {topic}. Focus on:
-    1. Key concepts and definitions
-    2. Historical development and recent trends
-    3. Major challenges and opportunities
-    4. Notable applications or case studies
-    5. Future outlook and potential developments
-
-    Make sure to organize your findings in a structured format with clear sections.
-  expected_output: >
-    A comprehensive research document with well-organized sections covering
-    all the requested aspects of {topic}. Include specific facts, figures,
-    and examples where relevant.
-  agent: researcher
-
-analysis_task:
-  description: >
-    Analyze the research findings and create a comprehensive report on {topic}.
-    Your report should:
-    1. Begin with an executive summary
-    2. Include all key information from the research
-    3. Provide insightful analysis of trends and patterns
-    4. Offer recommendations or future considerations
-    5. Be formatted in a professional, easy-to-read style with clear headings
-  expected_output: >
-    A polished, professional report on {topic} that presents the research
-    findings with added analysis and insights. The report should be well-structured
-    with an executive summary, main sections, and conclusion.
-  agent: analyst
-  context:
-    - research_task
-  output_file: output/report.md
+```jsonc agents/analyst.jsonc
+{
+  "role": "Report Analyst for {topic}",
+  "goal": "Turn research findings into a clear, well-structured report.",
+  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
+  // Replace with your model, for example "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-Note the `context` field in the analysis task - this is a powerful feature that allows the analyst to access the output of the research task. This creates a workflow where information flows naturally between agents, just as it would in a human team.
+Replace `provider/model-id` with the model you use, for example `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, or `gemini/gemini-2.0-flash-001`.
 
-## Step 5: Configure Your Crew
+## Step 3: Define Tasks and Crew Settings
 
-Now it's time to bring everything together by configuring our crew. The crew is the container that orchestrates how agents work together to complete tasks.
+Replace `crew.jsonc` with:
 
-Let's modify the `crew.py` file:
-
-```python
-# src/research_crew/crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai_tools import SerperDevTool
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
-
-@CrewBase
-class ResearchCrew():
-    """Research crew for comprehensive topic analysis and reporting"""
-
-    agents: List[BaseAgent]
-    tasks: List[Task]
-
-    @agent
-    def researcher(self) -> Agent:
-        return Agent(
-            config=self.agents_config['researcher'], # type: ignore[index]
-            verbose=True,
-            tools=[SerperDevTool()]
-        )
-
-    @agent
-    def analyst(self) -> Agent:
-        return Agent(
-            config=self.agents_config['analyst'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def research_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['research_task'] # type: ignore[index]
-        )
-
-    @task
-    def analysis_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['analysis_task'], # type: ignore[index]
-            output_file='output/report.md'
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the research crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
-
-In this code, we're:
-1. Creating the researcher agent and equipping it with the SerperDevTool to search the web
-2. Creating the analyst agent
-3. Setting up the research and analysis tasks
-4. Configuring the crew to run tasks sequentially (the analyst will wait for the researcher to finish)
-
-This is where the magic happens - with just a few lines of code, we've defined a collaborative AI system where specialized agents work together in a coordinated process.
-
-## Step 6: Set Up Your Main Script
-
-Now, let's set up the main script that will run our crew. This is where we provide the specific topic we want our crew to research.
-
-```python
-#!/usr/bin/env python
-# src/research_crew/main.py
-import os
-from research_crew.crew import ResearchCrew
-
-# Create output directory if it doesn't exist
-os.makedirs('output', exist_ok=True)
-
-def run():
-    """
-    Run the research crew.
-    """
-    inputs = {
-        'topic': 'Artificial Intelligence in Healthcare'
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
+      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis_task",
+      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
+      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
+      "agent": "analyst",
+      "context": ["research_task"],
+      "output_file": "output/report.md",
+      "markdown": true
     }
-
-    # Create and run the crew
-    result = ResearchCrew().crew().kickoff(inputs=inputs)
-
-    # Print the result
-    print("\n\n=== FINAL REPORT ===\n\n")
-    print(result.raw)
-
-    print("\n\nReport has been saved to output/report.md")
-
-if __name__ == "__main__":
-    run()
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "Artificial Intelligence in Healthcare"
+  }
+}
 ```
 
-This script prepares the environment, specifies our research topic, and kicks off the crew's work. The power of CrewAI is evident in how simple this code is - all the complexity of managing multiple AI agents is handled by the framework.
+`context` points to prior task names, so the analyst receives the research task output. The `inputs` object provides default values for `{topic}`. If you remove a default, `crewai run` prompts for it.
 
-## Step 7: Set Up Your Environment Variables
+## Step 4: Set Environment Variables
 
-Create a `.env` file in your project root with your API keys:
+Open `.env` and add the keys your model and tools need:
 
 ```sh
 SERPER_API_KEY=your_serper_api_key
-# Add your provider's API key here too.
+# Add your model provider API key here too.
 ```
 
-See the [LLM Setup guide](/en/concepts/llms#setting-up-your-llm) for details on configuring your provider of choice. You can get a Serper API key from [Serper.dev](https://serper.dev/).
+See the [LLM setup guide](/en/concepts/llms#setting-up-your-llm) for provider-specific keys.
 
-## Step 8: Install Dependencies
-
-Install the required dependencies using the CrewAI CLI:
+## Step 5: Install and Run
 
 ```bash
 crewai install
-```
-
-This command will:
-1. Read the dependencies from your project configuration
-2. Create a virtual environment if needed
-3. Install all required packages
-
-## Step 9: Run Your Crew
-
-Now for the exciting moment - it's time to run your crew and see AI collaboration in action!
-
-```bash
 crewai run
 ```
 
-When you run this command, you'll see your crew spring to life. The researcher will gather information about the specified topic, and the analyst will then create a comprehensive report based on that research. You'll see the agents' thought processes, actions, and outputs in real-time as they work together to complete their tasks.
+`crewai run` detects `crew.jsonc`, loads the agents from `agents/`, prompts for missing placeholders, and runs the crew. When the run finishes, open `output/report.md`.
 
-## Step 10: Review the Output
+## How It Works
 
-Once the crew completes its work, you'll find the final report in the `output/report.md` file. The report will include:
+1. `crew.jsonc` defines the crew, task order, process, memory, and runtime inputs.
+2. `agents/researcher.jsonc` and `agents/analyst.jsonc` define the agents.
+3. The researcher runs first.
+4. The analyst runs second with `context: ["research_task"]`.
+5. The final task writes `output/report.md`.
 
-1. An executive summary
-2. Detailed information about the topic
-3. Analysis and insights
-4. Recommendations or future considerations
+## Extending Your Crew
 
-Take a moment to appreciate what you've accomplished - you've created a system where multiple AI agents collaborated on a complex task, each contributing their specialized skills to produce a result that's greater than what any single agent could achieve alone.
+You can add:
 
-## Exploring Other CLI Commands
+- More agents by creating new `agents/<name>.jsonc` files and listing them in `crew.jsonc`
+- More tasks by appending objects to the `tasks` array
+- Built-in tools by adding tool class names such as `"FileReadTool"` or `"SerperDevTool"`
+- Custom tools with `"custom:<name>"`, which loads `tools/<name>.py`
+- Hierarchical execution with `"process": "hierarchical"` and a `manager_llm` or `manager_agent`
 
-CrewAI offers several other useful CLI commands for working with crews:
-
-```bash
-# View all available commands
-crewai --help
-
-# Run the crew
-crewai run
-
-# Test the crew
-crewai test
-
-# Reset crew memories
-crewai reset-memories
-
-# Replay from a specific task
-crewai replay -t <task_id>
-```
-
-## The Art of the Possible: Beyond Your First Crew
-
-What you've built in this guide is just the beginning. The skills and patterns you've learned can be applied to create increasingly sophisticated AI systems. Here are some ways you could extend this basic research crew:
-
-### Expanding Your Crew
-
-You could add more specialized agents to your crew:
-- A **fact-checker** to verify research findings
-- A **data visualizer** to create charts and graphs
-- A **domain expert** with specialized knowledge in a particular area
-- A **critic** to identify weaknesses in the analysis
-
-### Adding Tools and Capabilities
-
-You could enhance your agents with additional tools:
-- Web browsing tools for real-time research
-- CSV/database tools for data analysis
-- Code execution tools for data processing
-- API connections to external services
-
-### Creating More Complex Workflows
-
-You could implement more sophisticated processes:
-- Hierarchical processes where manager agents delegate to worker agents
-- Iterative processes with feedback loops for refinement
-- Parallel processes where multiple agents work simultaneously
-- Dynamic processes that adapt based on intermediate results
-
-### Applying to Different Domains
-
-The same patterns can be applied to create crews for:
-- **Content creation**: Writers, editors, fact-checkers, and designers working together
-- **Customer service**: Triage agents, specialists, and quality control working together
-- **Product development**: Researchers, designers, and planners collaborating
-- **Data analysis**: Data collectors, analysts, and visualization specialists
-
-## Next Steps
-
-Now that you've built your first crew, you can:
-
-1. Experiment with different agent configurations and personalities
-2. Try more complex task structures and workflows
-3. Implement custom tools to give your agents new capabilities
-4. Apply your crew to different topics or problem domains
-5. Explore [CrewAI Flows](/en/guides/flows/first-flow) for more advanced workflows with procedural programming
+<Warning>
+Only run JSON crew projects from sources you trust. `custom:<name>` tools and `{"python": "module.attribute"}` references execute local Python code when the crew loads.
+</Warning>
 
 <Check>
-Congratulations! You've successfully built your first CrewAI crew that can research and analyze any topic you provide. This foundational experience has equipped you with the skills to create increasingly sophisticated AI systems that can tackle complex, multi-stage problems through collaborative intelligence.
+You now have a working JSON-first crew that researches a topic and writes a report.
 </Check>

docs/en/guides/flows/conversational-flows.mdx

@@ -0,0 +1,501 @@
+---
+title: Conversational Flows
+description: Build multi-turn chat apps with handle_turn per turn, message history, intent routing, tracing, and WebSocket bridges.
+icon: comments
+mode: "wide"
+---
+
+## Overview
+
+Conversational apps treat each user line as a **new flow run** with the **same session id**. CrewAI adds helpers for message history, optional intent routing, deferred tracing, UI bridges, and a local `flow.chat()` REPL for conversational flows.
+
+| Concept | Implementation |
+|---------|----------------|
+| Session id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
+| User line | `handle_turn(message)` appends to `state.messages` before the graph runs |
+| Turn complete | `FlowFinished` for **this run** only; chat continues on the next `handle_turn` |
+| Full-session trace | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+
+## Turn APIs
+
+Use **`flow.handle_turn(message, session_id=...)`** for every user message from REST, WebSocket, tests, and custom UIs. Use **`flow.chat()`** when you want a local terminal chat loop for a conversational `Flow`.
+
+`Flow.kickoff()` does **not** accept `user_message=` or `session_id=` keyword arguments. For conversational flows, `handle_turn()` stores the pending message and calls `kickoff(inputs={"id": session_id})` internally after resetting per-turn execution state.
+
+| API | Use for |
+|-----|---------|
+| `handle_turn(message, session_id=...)` | Ergonomic one-turn wrapper for conversational `Flow` |
+| `chat()` | Local terminal REPL for conversational `Flow` |
+| `kickoff(inputs={...})` | Advanced flow execution without conversational turn handling |
+| `ask()` | Blocking prompt **inside** one step (wizard, clarification) |
+| `@human_feedback` | Approve/reject **a step output** — not the next chat line |
+| `ChatSession.handle_turn(...)` | Transport layer over `handle_turn` (SSE / WebSocket) |
+
+## Quick start
+
+```python
+from uuid import uuid4
+
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context):
+        message = (self.state.current_user_message or "").lower()
+        if "order" in message:
+            return "order"
+        if "bye" in message or "goodbye" in message:
+            return "goodbye"
+        return "help"
+
+    @listen("order")
+    def handle_order(self):
+        reply = "Your order is on the way."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("help")
+    def handle_help(self):
+        reply = "How can I help?"
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("goodbye")
+    def handle_goodbye(self):
+        reply = "Goodbye!"
+        self.append_assistant_message(reply)
+        return reply
+
+
+session_id = str(uuid4())
+flow = SupportFlow()
+
+try:
+    flow.handle_turn("Where is my order?", session_id=session_id)
+    flow.handle_turn("What about returns?", session_id=session_id)
+finally:
+    flow.finalize_session_traces()  # one trace link for the whole chat
+```
+
+## Turn lifecycle
+
+Each `handle_turn` runs this pipeline:
+
+1. **Turn setup** — stores the pending user message, resolves the session id, resets per-turn execution tracking, and calls `kickoff(inputs={"id": session_id})`.
+2. **State restore** — if `inputs["id"]` exists and `@persist` is configured, loads the latest snapshot.
+3. **`FlowStarted`** — emitted on the first deferred session turn only.
+4. **Pending turn hydration** — appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`, and optionally classifies when `intents` / `default_intents` + `intent_llm` are set.
+5. **Graph execution** — `conversation_start` → `route_conversation` → the selected `@listen` handler.
+6. **End of run** — per-turn `flow_finished` and trace finalization are **skipped** when deferral is enabled; nested `Agent.kickoff()` / crews do not close the parent batch either.
+
+Handlers should call **`append_assistant_message(reply)`** so the next turn’s `conversation_messages` includes assistant text. The user line is already stored by `handle_turn` — do not append it again in handlers.
+
+## `ConversationConfig` (class-level defaults)
+
+Decorate your conversational `Flow` subclass with `ConversationConfig`.
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `system_prompt` | Framework default | System message used by the built-in `converse_turn`. |
+| `llm` | `None` | Conversation LLM used by `converse_turn` and as router fallback. |
+| `router` | `None` | `RouterConfig` for LLM-driven routing. |
+| `intent_llm` | `None` | LLM for `intents=` / `default_intents` pre-classification. |
+| `default_intents` | `None` | Outcome labels for pre-classification. |
+| `defer_trace_finalization` | `True` | Keep one trace batch open across `handle_turn()` calls. |
+
+Override pre-classification per turn with `handle_turn(..., intents=..., intent_llm=...)`.
+
+## Lower-level `ChatState` helpers
+
+`ChatState`, `ConversationalConfig`, and `crewai.flow.conversation` helpers are still importable for advanced orchestration, tests, or custom wrappers. They do not add `user_message=` or `session_id=` keyword arguments to `Flow.kickoff()`.
+
+```python
+from crewai.flow import ChatState
+
+
+class MyChatState(ChatState):
+    # Inherited: id, messages, last_user_message, last_intent, session_ready
+    research_turn_count: int = 0
+    custom_flag: bool = False
+```
+
+| Field | Role |
+|-------|------|
+| `id` | Session UUID (same as `inputs["id"]`) |
+| `messages` | `list` of `{role, content}` for LLM history |
+| `last_user_message` | Latest user line for this turn |
+| `last_intent` | Route label after classification (if used) |
+| `session_ready` | One-time bootstrap flag (permissions, caches, etc.) |
+
+`ConversationalInputs` is a `TypedDict` for conventional `kickoff(inputs={...})` keys: `id`, `user_message`, `last_intent`.
+
+## `Flow` conversational API
+
+### `handle_turn` parameters
+
+| Parameter | Purpose |
+|-----------|---------|
+| `message` | This turn’s text |
+| `session_id` | Conversation UUID → `inputs["id"]` / `state.id` |
+| `intents` | Outcome labels for pre-kickoff `classify_intent` |
+| `intent_llm` | LLM for classification (required with `intents`) |
+| `**kickoff_kwargs` | Forwarded to `kickoff()` for options like `input_files`, `from_checkpoint`, and `restore_from_state_id` |
+
+### `kickoff` parameters
+
+`Flow.kickoff()` accepts `inputs`, `input_files`, `from_checkpoint`, and `restore_from_state_id`. Pass `inputs={"id": session_id}` when you need raw flow execution, but use `handle_turn()` when the call represents a chat message.
+
+### Instance attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `conversational` | Set to `True` to enable the conversational graph and `handle_turn()` |
+| `defer_trace_finalization` | Instance flag; set automatically from config on `handle_turn()` |
+| `suppress_flow_events` | Hides console flow panels; **tracing still records** method/flow events |
+| `stream` | Enable streaming; use with `ChatSession.handle_turn(..., stream=True)` |
+
+### Methods and properties
+
+| Name | Description |
+|------|-------------|
+| `append_assistant_message(content)` | Append a user-visible assistant reply to `state.messages` |
+| `append_message(role, content, **extra)` | Lower-level append to `state.messages` |
+| `conversation_messages` | Read-only history for LLM calls |
+| `classify_intent(text, outcomes, *, llm, context=None)` | Map text to one outcome (same collapse logic as `@human_feedback`) |
+| `receive_user_message(text, *, outcomes=None, llm=None)` | Append user message; optionally set `last_intent` |
+| `finalize_session_traces()` | Emit deferred `flow_finished` and finalize the session trace batch |
+| `_should_defer_trace_finalization()` | Whether this flow defers per-turn trace finalization |
+| `input_history` | Audit trail of `ask()` prompts and responses |
+
+### Module helpers (`crewai.flow.conversation`)
+
+Importable for tests or custom orchestration:
+
+| Function | Description |
+|----------|-------------|
+| `normalize_kickoff_inputs(inputs, user_message=..., session_id=...)` | Merge conversational kwargs into `inputs` |
+| `get_conversation_messages(flow)` | Read messages from state or internal buffer |
+| `append_message(flow, role, content, **extra)` | Same as instance method |
+| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | Lower-level turn hydration for custom wrappers |
+| `receive_user_message(flow, text, ...)` | Same as instance method |
+| `set_state_field(flow, name, value)` | Set a field on dict or Pydantic state |
+| `get_conversational_config(flow)` | Read class `conversational_config` |
+| `input_history_to_messages(entries)` | Convert `input_history` to LLM message format |
+
+## Intent routing patterns
+
+### A. Pre-classify via `ConversationConfig` (simplest)
+
+Set `default_intents` and `intent_llm`. Each `handle_turn()` runs classification before routing; read `self.state.last_intent` in `route_turn()`.
+
+### B. Classify inside `route_turn` (richer prompts)
+
+Set `default_intents=None` so `handle_turn()` only appends the user message. In `route_turn()`, call `classify_intent` with a custom prompt or descriptions:
+
+```python
+def route_turn(self, context):
+    intent = self.classify_intent(
+        self._routing_prompt(self.state.current_user_message),
+        ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
+        llm="gpt-4o-mini",
+    )
+    self.state.last_intent = intent
+    return intent
+```
+
+Use **`@listen("RESEARCH")`** (or similar) for steps that run `Agent.kickoff()` with tools — not bare `LLM.call()` — when you need web research or multi-step tool use.
+
+## When the flow finishes but the user keeps chatting
+
+`FlowFinished` means **this graph run** completed. The conversation continues with another `handle_turn()` and the same `session_id`. `@persist` restores `messages`, flags, and context.
+
+**Persist pattern:** prefer `@persist` on a **single terminal step** (for example `finalize`) rather than on the whole `Flow` class. Class-level persist saves after every method; `load_state` uses the latest row, which may be a mid-run snapshot (for example right after `bootstrap`) and miss handler updates from the same turn.
+
+Do **not** use `@human_feedback` for follow-up chat lines unless a human must approve a specific step output before it is shown.
+
+## Conversational `Flow` (experimental)
+
+<Warning>
+  **This is an experimental feature.** The conversational `Flow` surface
+  (`conversational = True`, `handle_turn`, `ConversationConfig`,
+  `RouterConfig`, `ConversationState`, the built-in graph + helpers) lives
+  under `crewai.experimental` and may change shape before it graduates.
+  Pin your CrewAI version if you depend on specific behavior, and watch the
+  changelog for breaking updates. Open issues / feedback welcome.
+</Warning>
+
+Opt into the conversational chat graph by setting `conversational = True` on a `Flow` subclass. The base `Flow` then ships a built-in `@start` / `@router` / `converse_turn` / `end_conversation` graph, manages `state.messages`, can drive a router LLM, and keeps the trace batch open across turns. You write the **custom routes**; the framework owns the rest.
+
+Use this when you want a multi-turn chat with a router and per-route handlers without wiring the lifecycle yourself. Use `Flow[ChatState]` (the lower-level pattern above) when you need full control.
+
+### Quick example
+
+```python
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context: dict) -> str | None:
+        message = (self.state.current_user_message or "").lower()
+        if "search" in message or "news" in message:
+            return "INTERNET_SEARCH"
+        if "docs" in message or "crewai" in message:
+            return "CREWAI_DOCS"
+        return "converse"
+
+    @listen("INTERNET_SEARCH")
+    def handle_internet_search(self) -> str:
+        """Fresh web research, current news, real-time lookups."""
+        reply = "I would run the web research route here."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("CREWAI_DOCS")
+    def handle_crewai_docs(self) -> str:
+        """Look up the CrewAI documentation for framework/API questions."""
+        reply = "I would look up the CrewAI docs here."
+        self.append_assistant_message(reply)
+        return reply
+
+
+flow = SupportFlow()
+try:
+    flow.handle_turn("What can you do?")              # routes to converse
+    flow.handle_turn("Search the web for AI news.")   # routes to INTERNET_SEARCH
+    flow.handle_turn("Check the CrewAI docs.")         # routes to CREWAI_DOCS
+finally:
+    flow.finalize_session_traces()
+```
+
+For a local terminal chat, use `chat()`:
+
+```python
+def kickoff() -> None:
+    SupportFlow().chat()
+```
+
+`chat()` wraps `handle_turn()` in a REPL, exits on `exit` / `quit`, skips blank lines by default, and calls `finalize_session_traces()` when the session ends.
+
+### `ConversationConfig`
+
+Class decorator that attaches per-class chat defaults.
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `system_prompt` | `slices.conversational_system_prompt` from i18n | System message used by the built-in `converse_turn`. Pass `""` to opt out entirely. |
+| `llm` | `None` | Conversation LLM (used by `converse_turn` and as router fallback). |
+| `router` | `None` | `RouterConfig` for LLM-driven routing. Without it, the flow always falls through to `converse`. |
+| `answer_from_history_prompt` | Framework default | System message for the optional `answer_from_history` route. |
+| `answer_from_history_llm` | `None` | Enables the `answer_from_history` short-circuit when set. |
+| `intent_llm` | `None` | LLM for legacy `intents=`/`default_intents` pre-classification. |
+| `default_intents` | `None` | Outcome labels for legacy pre-classification. |
+| `visible_agent_outputs` | `None` | `"all"`, or a list of agent names whose `append_agent_result()` calls should be promoted to public assistant messages. |
+| `defer_trace_finalization` | `True` | Keep one trace batch open across `handle_turn()` calls. |
+
+### `RouterConfig` and the auto-built route catalog
+
+```python
+from typing import Literal
+
+from pydantic import BaseModel
+
+from crewai import LLM
+from crewai.experimental.conversational import RouterConfig
+
+
+class MyRoute(BaseModel):
+    intent: Literal["INTERNET_SEARCH", "CREWAI_DOCS", "converse"]
+
+
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+router_config = RouterConfig(
+    prompt="Optional domain framing (policy, voice, persona).",
+    response_format=MyRoute,        # optional; auto-generated otherwise
+    llm=ROUTER_LLM,                  # falls back to ConversationConfig.llm
+    routes=["INTERNET_SEARCH", "CREWAI_DOCS"],   # optional; inferred from listeners
+    route_descriptions={
+        "INTERNET_SEARCH": "Override the docstring for this one route.",
+    },
+    default_intent="converse",       # used when LLM call fails or no LLM available
+    fallback_intent="converse",      # used when LLM returns an invalid route
+    intent_field="intent",
+)
+```
+
+The router prompt that gets sent to the LLM is built automatically. For each route the framework picks a description with this precedence:
+
+1. `RouterConfig.route_descriptions[label]` — explicit override.
+2. `Flow.builtin_route_descriptions[label]` — framework-canned text for `converse`, `end`, `answer_from_history` (phrased for the router LLM).
+3. First non-empty line of the `@listen(label)` handler's docstring.
+4. Empty (the route is listed without a description).
+
+So in practice, **adding a new route is `@listen("X")` + a one-line docstring**:
+
+```python
+from crewai.flow import listen
+
+
+@listen("INTERNET_SEARCH")
+def handle_internet_search(self) -> str:
+    """Fresh web research, current news, real-time lookups."""
+    ...
+```
+
+…and the router LLM sees:
+
+```
+Routes:
+- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions.
+- INTERNET_SEARCH: Fresh web research, current news, real-time lookups.
+- converse: Ordinary chat, follow-ups, summaries, clarifications…
+- end: User signals the conversation is finished (goodbye, exit, done).
+```
+
+`RouterConfig.prompt` is for **domain framing** (assistant persona, business rules, voice). The route catalog is auto-built — don't list routes in `prompt`; they'll drift the moment you add a handler.
+
+### Built-in routes
+
+| Route | Handler | Purpose |
+|-------|---------|---------|
+| `converse` | `converse_turn` | Default chat handler. Calls `ConversationConfig.llm` with the system prompt + canonical message history. |
+| `end` | `end_conversation` | Sets `state.ended = True` and emits a terminator reply. |
+| `answer_from_history` | `answer_from_history_turn` | Optional. Routes here when `ConversationConfig.answer_from_history_llm` is set and the message can be answered from existing history. |
+
+You can override any of these by defining a same-named handler in your subclass.
+
+### `handle_turn()` semantics
+
+`flow.handle_turn(message)` runs one turn:
+
+1. Resets per-execution tracking (`_completed_methods`, `_method_outputs`) so the graph re-runs — without this, repeated `kickoff` calls on the same flow instance would short-circuit on turn 2+ because `Flow.kickoff_async` treats `inputs={"id": ...}` as a checkpoint restore.
+2. Appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`. `last_intent` is **preserved from the prior turn** so the router LLM can use it as a signal.
+3. Runs `conversation_start` → `route_conversation` → the chosen `@listen` handler.
+4. The router stores its decision in `state.last_intent` (visible to the next turn's router context).
+5. If your handler returned a string and didn't already call `append_assistant_message`, `handle_turn` appends it for you.
+
+Call `handle_turn()` for chat messages. Calling `kickoff(inputs={"id": ...})` directly runs the flow graph without applying the conversational turn wrapper.
+
+### `chat()` for local REPLs
+
+`flow.chat()` is the batteries-included terminal wrapper around `handle_turn()`:
+
+```python
+flow = SupportFlow()
+flow.chat()
+```
+
+It handles the common local loop:
+
+1. Prompts for a user message.
+2. Stops on `exit` / `quit`, `EOFError`, or `KeyboardInterrupt`.
+3. Calls `handle_turn(message, session_id=...)`.
+4. Prints the assistant result.
+5. Finalizes deferred session traces in a `finally` block.
+
+Customize the terminal behavior with injectable I/O:
+
+```python
+flow.chat(
+    session_id="demo-session",
+    prompt="You: ",
+    assistant_prefix="Assistant: ",
+    exit_commands=("exit", "quit", "bye"),
+)
+```
+
+For web apps, background workers, tests, and custom transports, keep using `handle_turn()` directly.
+
+### Custom router behavior
+
+To run side effects (event bus setup, telemetry) on every routing decision, override `route_turn`:
+
+```python
+from typing import Any
+
+from crewai import Flow
+from crewai.experimental.conversational import ConversationState
+
+
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context: dict[str, Any]) -> str | None:
+        self.event_bus = MyBus(self)
+        return super().route_turn(context)
+```
+
+To bypass the LLM router entirely and pick a route programmatically, return a string from `route_turn`; returning `None` falls back to `_route_with_config(...)`.
+
+### `append_assistant_message` and `append_agent_result`
+
+Inside a `@listen(label)` handler, choose:
+
+- `self.append_assistant_message(text)` — adds a user-visible assistant turn to `state.messages`. The next turn's `converse_turn` sees it.
+- `self.append_agent_result(agent_name, result, visibility="private")` — records a structured event in `state.events` and a thread in `state.agent_threads[agent_name]`. Public visibility also calls `append_assistant_message` for you. Use private results for scratch work that shouldn't pollute the canonical history.
+
+`ConversationConfig.visible_agent_outputs` can promote specific agents' private results to public globally (`"all"`, or a list of agent names).
+
+## Tracing across turns
+
+With `defer_trace_finalization=True` (default in `ConversationConfig`):
+
+- **One trace batch** for the whole chat session.
+- **`flow_started`** on the first turn only; **`flow_finished`** once in `finalize_session_traces()`.
+- **Per-turn** `kickoff` does not print “Trace batch finalized”.
+- **Nested work** (`Agent.kickoff()`, crews, Exa tools) appends to the **parent** batch; inner `AgentExecutor` flows do not close the session batch early.
+
+```python
+flow.chat(session_id=session_id)
+```
+
+`flow.chat()` calls `finalize_session_traces()` for you. When you own the loop
+with `handle_turn()`, call `finalize_session_traces()` when
+the session ends.
+
+`suppress_flow_events=True` only hides Rich console panels; trace and method events still emit for observability.
+
+### Conversational `Flow` trace lifecycle
+
+The experimental [conversational `Flow`](#conversational-flow-experimental) uses the same tracing lifecycle: `defer_trace_finalization` defaults to `True`, so each `handle_turn()` keeps the session trace open. Always finalize at the end of the session — wrap your REPL/loop in `try/finally` and call `flow.finalize_session_traces()` on exit. Without it, the trace batch stays open and the final conversation may never export.
+
+## Streaming
+
+Set `stream = True` on the `Flow` class. `kickoff(...)` will then emit `assistant_delta` (and related) events through the standard event bus.
+
+## Imports
+
+```python
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+    Flow,
+    listen,
+    persist,
+    router,
+    start,
+)
+```
+
+## See also
+
+- [Mastering Flow State Management](/en/guides/flows/mastering-flow-state) — persistence, Pydantic state, `@persist`
+- [Build Your First Flow](/en/guides/flows/first-flow) — flow basics
+- Demo: `lib/crewai/runner_conversational_flow_simple.py` — minimal REPL with `RESEARCH` + Exa agent

docs/en/guides/flows/first-flow.mdx

@@ -65,7 +65,7 @@ This will generate a project with the basic structure needed for your flow.
 
 ## Step 2: Understanding the Project Structure
 
-The generated project has the following structure. Take a moment to familiarize yourself with it, as understanding this structure will help you create more complex flows in the future.
+The generated project has the following structure. The starter embedded crew uses the classic Python/YAML layout, and in Step 4 we will replace the content crew with a JSONC crew.
 
 ```
 guide_creator_flow/
@@ -73,21 +73,24 @@ guide_creator_flow/
 ├── pyproject.toml
 ├── README.md
 ├── .env
-├── main.py
-├── crews/
-│   └── poem_crew/
-│       ├── config/
-│       │   ├── agents.yaml
-│       │   └── tasks.yaml
-│       └── poem_crew.py
-└── tools/
-    └── custom_tool.py
+└── src/
+    └── guide_creator_flow/
+        ├── __init__.py
+        ├── main.py
+        ├── crews/
+        │   └── poem_crew/
+        │       ├── config/
+        │       │   ├── agents.yaml
+        │       │   └── tasks.yaml
+        │       └── poem_crew.py
+        └── tools/
+            └── custom_tool.py
 ```
 
 This structure provides a clear separation between different components of your flow:
-- The main flow logic in the `main.py` file
-- Specialized crews in the `crews` directory
-- Custom tools in the `tools` directory
+- The main flow logic in the `src/guide_creator_flow/main.py` file
+- Specialized crews in the `src/guide_creator_flow/crews` directory
+- Custom tools in the `src/guide_creator_flow/tools` directory
 
 We'll modify this structure to create our guide creator flow, which will orchestrate the process of generating comprehensive learning guides.
 
@@ -103,157 +106,82 @@ This command automatically creates the necessary directories and template files
 
 ## Step 4: Configure the Content Writer Crew
 
-Now, let's modify the generated files for the content writer crew. We'll set up two specialized agents - a writer and a reviewer - that will collaborate to create high-quality content for our guide.
+Now, let's configure the content writer crew with JSONC. We'll set up two specialized agents - a writer and a reviewer - that collaborate to create high-quality content for our guide.
 
-1. First, update the agents configuration file to define our content creation team:
+1. Create `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`:
 
-   Remember to set `llm` to the provider you are using.
-
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/agents.yaml
-content_writer:
-  role: >
-    Educational Content Writer
-  goal: >
-    Create engaging, informative content that thoroughly explains the assigned topic
-    and provides valuable insights to the reader
-  backstory: >
-    You are a talented educational writer with expertise in creating clear, engaging
-    content. You have a gift for explaining complex concepts in accessible language
-    and organizing information in a way that helps readers build their understanding.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
-
-content_reviewer:
-  role: >
-    Educational Content Reviewer and Editor
-  goal: >
-    Ensure content is accurate, comprehensive, well-structured, and maintains
-    consistency with previously written sections
-  backstory: >
-    You are a meticulous editor with years of experience reviewing educational
-    content. You have an eye for detail, clarity, and coherence. You excel at
-    improving content while maintaining the original author's voice and ensuring
-    consistent quality across multiple sections.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
+```jsonc
+{
+  "role": "Educational Content Writer",
+  "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.",
+  "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-These agent definitions establish the specialized roles and perspectives that will shape how our AI agents approach content creation. Notice how each agent has a distinct purpose and expertise.
+2. Create `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`:
 
-2. Next, update the tasks configuration file to define the specific writing and reviewing tasks:
-
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
-write_section_task:
-  description: >
-    Write a comprehensive section on the topic: "{section_title}"
-
-    Section description: {section_description}
-    Target audience: {audience_level} level learners
-
-    Your content should:
-    1. Begin with a brief introduction to the section topic
-    2. Explain all key concepts clearly with examples
-    3. Include practical applications or exercises where appropriate
-    4. End with a summary of key points
-    5. Be approximately 500-800 words in length
-
-    Format your content in Markdown with appropriate headings, lists, and emphasis.
-
-    Previously written sections:
-    {previous_sections}
-
-    Make sure your content maintains consistency with previously written sections
-    and builds upon concepts that have already been explained.
-  expected_output: >
-    A well-structured, comprehensive section in Markdown format that thoroughly
-    explains the topic and is appropriate for the target audience.
-  agent: content_writer
-
-review_section_task:
-  description: >
-    Review and improve the following section on "{section_title}":
-
-    {draft_content}
-
-    Target audience: {audience_level} level learners
-
-    Previously written sections:
-    {previous_sections}
-
-    Your review should:
-    1. Fix any grammatical or spelling errors
-    2. Improve clarity and readability
-    3. Ensure content is comprehensive and accurate
-    4. Verify consistency with previously written sections
-    5. Enhance the structure and flow
-    6. Add any missing key information
-
-    Provide the improved version of the section in Markdown format.
-  expected_output: >
-    An improved, polished version of the section that maintains the original
-    structure but enhances clarity, accuracy, and consistency.
-  agent: content_reviewer
-  context:
-    - write_section_task
+```jsonc
+{
+  "role": "Educational Content Reviewer and Editor",
+  "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.",
+  "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-These task definitions provide detailed instructions to our agents, ensuring they produce content that meets our quality standards. Note how the `context` parameter in the review task creates a workflow where the reviewer has access to the writer's output.
+Replace `provider/model-id` with the model you use, for example `openai/gpt-4o`, `gemini/gemini-2.0-flash-001`, or `anthropic/claude-sonnet-4-6`.
 
-3. Now, update the crew implementation file to define how our agents and tasks work together:
+3. Create `src/guide_creator_flow/crews/content_crew/crew.jsonc`:
+
+```jsonc
+{
+  "name": "Content Crew",
+  "agents": ["content_writer", "content_reviewer"],
+  "tasks": [
+    {
+      "name": "write_section_task",
+      "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}",
+      "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.",
+      "agent": "content_writer",
+      "markdown": true
+    },
+    {
+      "name": "review_section_task",
+      "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.",
+      "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.",
+      "agent": "content_reviewer",
+      "context": ["write_section_task"],
+      "markdown": true
+    }
+  ],
+  "process": "sequential",
+  "verbose": true
+}
+```
+
+The `context` field lets the reviewer use the writer's output.
+
+4. Replace `src/guide_creator_flow/crews/content_crew/content_crew.py` with a small loader:
 
 ```python
-# src/guide_creator_flow/crews/content_crew/content_crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+from pathlib import Path
 
-@CrewBase
-class ContentCrew():
-    """Content writing crew"""
+from crewai.project import load_crew
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
 
-    @agent
-    def content_writer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_writer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @agent
-    def content_reviewer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_reviewer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def write_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['write_section_task'] # type: ignore[index]
-        )
-
-    @task
-    def review_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['review_section_task'], # type: ignore[index]
-            context=[self.write_section_task()]
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the content writing crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
+def kickoff_content_crew(inputs: dict):
+    crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+    return crew.kickoff(inputs={**default_inputs, **inputs})
 ```
 
-This crew definition establishes the relationship between our agents and tasks, setting up a sequential process where the content writer creates a draft and then the reviewer improves it. While this crew can function independently, in our flow it will be orchestrated as part of a larger system.
+This loader turns `crew.jsonc` into a `Crew` at runtime. While this crew can function independently, in our flow it will be orchestrated as part of a larger system.
 
 ## Step 5: Create the Flow
 
@@ -275,7 +203,7 @@ from typing import List, Dict
 from pydantic import BaseModel, Field
 from crewai import LLM
 from crewai.flow.flow import Flow, listen, start
-from guide_creator_flow.crews.content_crew.content_crew import ContentCrew
+from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew
 
 # Define our models for structured data
 class Section(BaseModel):
@@ -380,7 +308,7 @@ class GuideCreatorFlow(Flow[GuideCreatorState]):
                 previous_sections_text = "No previous sections written yet."
 
             # Run the content crew for this section
-            result = ContentCrew().crew().kickoff(inputs={
+            result = kickoff_content_crew(inputs={
                 "section_title": section.title,
                 "section_description": section.description,
                 "audience_level": self.state.audience_level,
@@ -600,7 +528,7 @@ This provides a type-safe way to track and transform data throughout your flow.
 Flows can seamlessly integrate with crews for complex collaborative tasks:
 
 ```python
-result = ContentCrew().crew().kickoff(inputs={
+result = kickoff_content_crew(inputs={
     "section_title": section.title,
     # ...
 })
@@ -617,6 +545,7 @@ Now that you've built your first flow, you can:
 3. Explore the `and_` and `or_` functions for more complex parallel execution
 4. Connect your flow to external APIs, databases, or user interfaces
 5. Combine multiple specialized crews in a single flow
+6. Build multi-turn chat apps with [Conversational Flows](/en/guides/flows/conversational-flows) (`kickoff` per message, `ChatSession`, deferred tracing)
 
 <Check>
 Congratulations! You've successfully built your first CrewAI Flow that combines regular code, direct LLM calls, and crew-based processing to create a comprehensive guide. These foundational skills enable you to create increasingly sophisticated AI applications that can tackle complex, multi-stage problems through a combination of procedural control and collaborative intelligence.

docs/en/guides/flows/mastering-flow-state.mdx

@@ -22,6 +22,8 @@ Effective state management enables you to:
 5. **Scale your applications** - Support complex workflows with proper data organization
 6. **Enable conversational applications** - Store and access conversation history for context-aware AI interactions
 
+For multi-turn chat (`kickoff` per user line, `ChatState`, intent routing, deferred tracing, and `ChatSession`), see [Conversational Flows](/en/guides/flows/conversational-flows).
+
 Let's explore how to leverage these capabilities effectively.
 
 ## State Management Fundamentals

docs/en/guides/migration/upgrading-crewai.mdx

@@ -141,7 +141,7 @@ crew = Crew(
     process=Process.sequential,   # or Process.hierarchical
     memory=True,
     cache=True,
-    embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},
+    embedder={"provider": "openai", "config": {"model": "text-embedding-3-large"}},
 )
 ```
 
@@ -173,7 +173,7 @@ write = Task(
 
 ### Memory & embedder config {#memory-embedder-config}
 
-If `memory=True` and you're not using the default OpenAI embeddings, you must pass an `embedder`:
+If `memory=True` and you're not using the default OpenAI `text-embedding-3-large` embeddings, you must pass an `embedder`:
 
 ```python
 crew = Crew(
@@ -187,4 +187,4 @@ crew = Crew(
 )
 ```
 
-Set the relevant provider credentials (`OPENAI_API_KEY`, `OLLAMA_HOST`, etc.) in your `.env` file. Memory storage paths are project-local by default — delete the project's memory directory if you change embedders, since dimensions don't mix.
+Set the relevant provider credentials (`OPENAI_API_KEY`, `OLLAMA_HOST`, etc.) in your `.env` file. Memory storage paths are project-local by default. Existing local memory stores created with 1536-dimensional embeddings may not be compatible with the default OpenAI `text-embedding-3-large` embedder, which uses 3072 dimensions. If you hit a dimension mismatch, delete the project's memory directory, run `crewai reset-memories -m`, or explicitly configure the older embedder model until you migrate.

docs/en/installation.mdx

@@ -116,7 +116,7 @@ If you haven't installed `uv` yet, follow **step 1** to quickly get it set up on
 
 # Creating a CrewAI Project
 
-We recommend using the `YAML` template scaffolding for a structured approach to defining agents and tasks. Here's how to get started:
+`crewai create crew` now creates a JSON-first crew project. Agents live in `agents/*.jsonc`, tasks and crew-level settings live in `crew.jsonc`, and `crewai run` loads that JSON definition directly.
 
 <Steps>
   <Step title="Generate Project Scaffolding">
@@ -129,21 +129,20 @@ We recommend using the `YAML` template scaffolding for a structured approach to
       ```
       my_project/
       ├── .gitignore
+      ├── .env
+      ├── agents/
+      │   └── researcher.jsonc
+      ├── crew.jsonc
       ├── knowledge/
       ├── pyproject.toml
       ├── README.md
-      ├── .env
-      └── src/
-          └── my_project/
-              ├── __init__.py
-              ├── main.py
-              ├── crew.py
-              ├── tools/
-              │   ├── custom_tool.py
-              │   └── __init__.py
-              └── config/
-                  ├── agents.yaml
-                  └── tasks.yaml
+      ├── skills/
+      └── tools/
+      ```
+
+    - If you need the older Python/YAML scaffold with `crew.py`, `config/agents.yaml`, and `config/tasks.yaml`, run:
+      ```shell
+      crewai create crew <your_project_name> --classic
       ```
 
   </Step>
@@ -152,15 +151,15 @@ We recommend using the `YAML` template scaffolding for a structured approach to
     - Your project will contain these essential files:
       | File | Purpose |
       | --- | --- |
-      | `agents.yaml` | Define your AI agents and their roles |
-      | `tasks.yaml` | Set up agent tasks and workflows |
+      | `crew.jsonc` | Configure the crew, task order, process, and input defaults |
+      | `agents/*.jsonc` | Define each agent's role, goal, backstory, LLM, tools, and behavior |
       | `.env` | Store API keys and environment variables |
-      | `main.py` | Project entry point and execution flow |
-      | `crew.py` | Crew orchestration and coordination |
-      | `tools/` | Directory for custom agent tools |
-      | `knowledge/` | Directory for knowledge base |
+      | `tools/` | Optional Python files for `custom:<name>` tools |
+      | `knowledge/` | Optional knowledge files for agents |
+      | `skills/` | Optional skill files applied to the crew |
 
-    - Start by editing `agents.yaml` and `tasks.yaml` to define your crew's behavior.
+    - Start by editing `crew.jsonc` and the files in `agents/` to define your crew's behavior.
+    - Use `{placeholder}` values in agent and task text, then set defaults in `crew.jsonc` under `inputs`. When you run `crewai run`, the CLI prompts for any missing values.
     - Keep sensitive information like API keys in `.env`.
 
   </Step>

docs/en/learn/using-annotations.mdx

@@ -1,15 +1,19 @@
 ---
 title: "Using Annotations in crew.py"
-description: "Learn how to use annotations to properly structure agents, tasks, and components in CrewAI"
+description: "Learn how to use classic Python annotations to structure agents, tasks, and components in CrewAI"
 icon: "at"
 mode: "wide"
 ---
 
-This guide explains how to use annotations to properly reference **agents**, **tasks**, and other components in the `crew.py` file.
+This guide explains how to use annotations to properly reference **agents**, **tasks**, and other components in a classic `crew.py` file.
+
+<Note>
+New crew projects created with `crewai create crew <name>` are JSON-first and use `crew.jsonc` plus `agents/*.jsonc`. Use this annotations guide when you are working in a classic project created with `crewai create crew <name> --classic`, migrating an existing Python/YAML project, or need decorator-based Python control.
+</Note>
 
 ## Introduction
 
-Annotations in the CrewAI framework are used to decorate classes and methods, providing metadata and functionality to various components of your crew. These annotations help in organizing and structuring your code, making it more readable and maintainable.
+Annotations in the CrewAI framework are used to decorate classes and methods, providing metadata and functionality to various components of your crew. In classic Python/YAML projects, these annotations help organize the code that loads `config/agents.yaml`, `config/tasks.yaml`, and returns the `Crew` object.
 
 ## Available Annotations
 
@@ -113,9 +117,9 @@ def crew(self) -> Crew:
 
 The `@crew` annotation is used to decorate the method that creates and returns the `Crew` object. This method assembles all the components (agents and tasks) into a functional crew.
 
-## YAML Configuration
+## Classic YAML Configuration
 
-The agent configurations are typically stored in a YAML file. Here's an example of how the `agents.yaml` file might look for the researcher agent:
+In classic projects, agent configurations are typically stored in a YAML file. Here's an example of how the `agents.yaml` file might look for the researcher agent:
 
 ```yaml
 researcher:
@@ -146,6 +150,6 @@ Note how the `llm` and `tools` in the YAML file correspond to the methods decora
 - **Consistent Naming**: Use clear and consistent naming conventions for your methods. For example, agent methods could be named after their roles (e.g., researcher, reporting_analyst).
 - **Environment Variables**: Use environment variables for sensitive information like API keys.
 - **Flexibility**: Design your crew to be flexible by allowing easy addition or removal of agents and tasks.
-- **YAML-Code Correspondence**: Ensure that the names and structures in your YAML files correspond correctly to the decorated methods in your Python code.
+- **YAML-Code Correspondence**: In classic projects, ensure that the names and structures in your YAML files correspond correctly to the decorated methods in your Python code.
 
-By following these guidelines and properly using annotations, you can create well-structured and maintainable crews using the CrewAI framework.
+By following these guidelines and properly using annotations, you can maintain classic Python/YAML crews cleanly. For new crews, prefer the JSON-first structure covered in [Crews](/en/concepts/crews).

docs/en/quickstart.mdx

@@ -39,85 +39,60 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
   This creates a Flow app under `src/latest_ai_flow/`, including a starter crew under `crews/content_crew/` that you will replace with a minimal **single-agent** research crew in the next steps.
   </Step>
 
-  <Step title="Configure one agent in `agents.yaml`">
-  Replace the contents of `src/latest_ai_flow/crews/content_crew/config/agents.yaml` with a single researcher. Variables like `{topic}` are filled from `crew.kickoff(inputs=...)`.
+  <Step title="Configure one agent in JSONC">
+  Create `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (create the `agents/` directory if needed). Variables like `{topic}` are filled from `crew.kickoff(inputs=...)`.
 
-    ```yaml agents.yaml
-    # src/latest_ai_flow/crews/content_crew/config/agents.yaml
-    researcher:
-      role: >
-        {topic} Senior Data Researcher
-      goal: >
-        Uncover cutting-edge developments in {topic}
-      backstory: >
-        You're a seasoned researcher with a knack for uncovering the latest
-        developments in {topic}. You find the most relevant information and
-        present it clearly.
+    ```jsonc agents/researcher.jsonc
+    {
+      "role": "{topic} Senior Data Researcher",
+      "goal": "Uncover cutting-edge developments in {topic}",
+      "backstory": "You're a seasoned researcher who finds relevant information and presents it clearly.",
+      "tools": ["SerperDevTool"],
+      "settings": {
+        "verbose": true
+      }
+    }
     ```
 
   </Step>
 
-  <Step title="Configure one task in `tasks.yaml`">
-    ```yaml tasks.yaml
-    # src/latest_ai_flow/crews/content_crew/config/tasks.yaml
-    research_task:
-      description: >
-        Conduct thorough research about {topic}. Use web search to find current,
-        credible information. The current year is 2026.
-      expected_output: >
-        A markdown report with clear sections: key trends, notable tools or companies,
-        and implications. Aim for 800–1200 words. No fenced code blocks around the whole document.
-      agent: researcher
-      output_file: output/report.md
+  <Step title="Configure the crew in `crew.jsonc`">
+  Create `src/latest_ai_flow/crews/content_crew/crew.jsonc`:
+
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "Conduct thorough research about {topic}. Use web search to find recent, credible information.",
+          "expected_output": "A markdown report with clear sections: key trends, notable tools or companies, and implications. Aim for 800-1200 words. No fenced code blocks around the whole document.",
+          "agent": "researcher",
+          "output_file": "output/report.md",
+          "markdown": true
+        }
+      ],
+      "process": "sequential",
+      "verbose": true
+    }
     ```
 
   </Step>
 
-  <Step title="Wire the crew class (`content_crew.py`)">
-  Point the generated crew at your YAML and attach `SerperDevTool` to the researcher.
+  <Step title="Load the JSON crew (`content_crew.py`)">
+  Replace the generated `content_crew.py` with a small loader that turns `crew.jsonc` into a `Crew`.
 
     ```python content_crew.py
     # src/latest_ai_flow/crews/content_crew/content_crew.py
-    from typing import List
+    from pathlib import Path
 
-    from crewai import Agent, Crew, Process, Task
-    from crewai.agents.agent_builder.base_agent import BaseAgent
-    from crewai.project import CrewBase, agent, crew, task
-    from crewai_tools import SerperDevTool
+    from crewai.project import load_crew
 
 
-    @CrewBase
-    class ResearchCrew:
-      """Single-agent research crew used inside the Flow."""
-
-      agents: List[BaseAgent]
-      tasks: List[Task]
-
-      agents_config = "config/agents.yaml"
-      tasks_config = "config/tasks.yaml"
-
-      @agent
-      def researcher(self) -> Agent:
-        return Agent(
-          config=self.agents_config["researcher"],  # type: ignore[index]
-          verbose=True,
-          tools=[SerperDevTool()],
-        )
-
-      @task
-      def research_task(self) -> Task:
-        return Task(
-          config=self.tasks_config["research_task"],  # type: ignore[index]
-        )
-
-      @crew
-      def crew(self) -> Crew:
-        return Crew(
-          agents=self.agents,
-          tasks=self.tasks,
-          process=Process.sequential,
-          verbose=True,
-        )
+    def kickoff_content_crew(inputs: dict):
+      crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+      return crew.kickoff(inputs={**default_inputs, **inputs})
     ```
 
   </Step>
@@ -131,7 +106,7 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
 
     from crewai.flow import Flow, listen, start
 
-    from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew
+    from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew
 
 
     class ResearchFlowState(BaseModel):
@@ -150,7 +125,7 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
 
       @listen(prepare_topic)
       def run_research(self):
-        result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic})
+        result = kickoff_content_crew(inputs={"topic": self.state.topic})
         self.state.report = result.raw
         print("Research crew finished.")
 
@@ -172,7 +147,7 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
     ```
 
   <Tip>
-  If your package name differs from `latest_ai_flow`, change the import of `ResearchCrew` to match your project’s module path.
+  If your package name differs from `latest_ai_flow`, change the `kickoff_content_crew` import to match your project’s module path.
   </Tip>
   </Step>
 
@@ -202,7 +177,7 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
 
   <CodeGroup>
     ```markdown output/report.md
-    # AI Agents in 2026: Landscape and Trends
+    # AI Agents: Recent Landscape and Trends
 
     ## Executive summary
     …
@@ -223,7 +198,7 @@ If you have not installed CrewAI yet, follow the [installation guide](/en/instal
 ## How this run fits together
 
 1. **Flow** — `LatestAiFlow` runs `prepare_topic` first, then `run_research`, then `summarize`. State (`topic`, `report`) lives on the Flow.
-2. **Crew** — `ResearchCrew` runs one task with one agent: the researcher uses **Serper** to search the web, then writes the structured report.
+2. **Crew** — `kickoff_content_crew` loads `crew.jsonc` and runs one task with one agent: the researcher uses **Serper** to search the web, then writes the structured report.
 3. **Artifact** — The task’s `output_file` writes the report under `output/report.md`.
 
 To go deeper on Flow patterns (routing, persistence, human-in-the-loop), see [Build your first Flow](/en/guides/flows/first-flow) and [Flows](/en/concepts/flows). For crews without a Flow, see [Crews](/en/concepts/crews). For a single `Agent` and `kickoff()` without tasks, see [Agents](/en/concepts/agents#direct-agent-interaction-with-kickoff).
@@ -234,7 +209,10 @@ You now have an end-to-end Flow with an agent crew and a saved report — a soli
 
 ### Naming consistency
 
-YAML keys (`researcher`, `research_task`) must match the method names on your `@CrewBase` class. See [Crews](/en/concepts/crews) for the full decorator pattern.
+The names in `crew.jsonc` must match the files and task references you use:
+
+- `agents: ["researcher"]` loads `agents/researcher.jsonc`
+- `tasks[].agent: "researcher"` assigns the task to that agent
 
 ## Deploying
 

docs/en/skills.mdx

@@ -20,7 +20,7 @@ That pulls the official skill pack into your agent workflow so it can apply Crew
 ## What your agent gets
 
 - **Flows** — structure stateful apps, steps, and crew kickoffs the CrewAI way
-- **Crews & agents** — YAML-first patterns, roles, tasks, and delegation
+- **Crews & agents** — JSON-first patterns (`crew.jsonc`, `agents/*.jsonc`), roles, tasks, and delegation
 - **Tools & integrations** — hook agents to search, APIs, and common CrewAI tools
 - **Project layout** — align with CLI scaffolds and repo conventions
 - **Up-to-date patterns** — skills track current CrewAI docs and recommended practices

docs/ko/changelog.mdx

@@ -4,6 +4,248 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 6월 11일">
+  ## v1.14.7
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
+
+  ## 변경 사항
+
+  ### 기능
+  - 메모리, 지식, RAG 및 흐름에 대한 플러그 가능한 기본 백엔드를 추가했습니다.
+  - LLM 이벤트에서 실제 finish_reason, 샘플링 매개변수 및 response.id를 표시합니다.
+  - 경로 인식 장식자로서의 타입 DSL 트리거를 설정합니다.
+  - 대화 흐름을 위한 채팅 API를 추가했습니다.
+  - 잠금 백엔드를 재정의 가능하도록 만듭니다.
+  - Flow DSL 메타데이터에서 FlowDefinition을 빌드합니다.
+  - 네이티브 Snowflake Cortex LLM 공급자를 추가했습니다.
+  - 훈련된 에이전트 파일 지원을 추가했습니다.
+
+  ### 버그 수정
+  - 복원 시 사용자 정의 BaseLLM을 구체적인 LLM으로 재구성하도록 체크포인트를 수정했습니다.
+  - 라이브 스냅샷이 재개로 재생되지 않도록 플래그를 사용하여 복원을 제한합니다.
+  - 실행마다 런타임 상태의 범위를 설정하여 성장을 제한하고 동시 실행을 격리합니다.
+  - crewai-login에서 텔레메트리 설정을 수정했습니다.
+  - 메서드 실행 이벤트에 대해 suppress_flow_events를 존중합니다.
+  - uv 도구 설치를 위해 crewai 패키지에서 [project.scripts]를 복원합니다.
+  - aiohttp, docling 및 docling-core에 대한 pip-audit CVE를 해결합니다.
+  - 파일 입력이 신뢰할 수 없게 작동하는 문제를 수정했습니다.
+  - Snowflake Claude의 불완전한 도구 결과 기록을 수정했습니다.
+
+  ### 문서
+  - v1.14.7에 대한 변경 로그 및 버전을 업데이트했습니다.
+  - OpenTelemetry 수집기 문서를 업데이트했습니다.
+  - NVIDIA Nemotron LLM 가이드를 업데이트했습니다.
+  - Databricks 통합 가이드를 추가했습니다.
+  - Snowflake 통합 가이드를 추가했습니다.
+
+  ### 성능
+  - docling 가져오기를 지연 로딩하여 crewai 가져오기 속도를 개선했습니다.
+
+  ### 리팩토링
+  - 흐름 조건 평가를 이벤트별로 상태 비저장으로 단순화했습니다.
+  - 대화 논리를 런타임에서 분리하고 conversational_definition을 추가했습니다.
+  - `flow.py`를 DSL, 정의 및 런타임으로 분리했습니다.
+
+  ## 기여자
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 10일">
+  ## v1.14.7rc2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 라이브 스냅샷이 재개로 재생되는 것을 방지하기 위한 플래그에서 게이트 복원
+
+  ### 문서
+  - v1.14.7rc1에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 6월 10일">
+  ## v1.14.7rc1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
+
+  ## 변경 사항
+
+  ### 기능
+  - 누적된 버스 상태를 해제하기 위해 `reset_runtime_state` 추가
+  - 사용자 정의 프롬프트를 모두 지원하도록 처리
+  - 대화 논리를 런타임과 분리하고 `conversational_definition` 추가
+
+  ### 버그 수정
+  - 실행당 런타임 상태의 범위를 수정하여 성장 제한 및 동시 실행 격리
+  - `crewai-login`에서 원격 측정 설정 수정
+  - 메서드 실행 이벤트에 대한 `suppress_flow_events` 존중 수정
+
+  ### 문서
+  - OpenTelemetry 이미지 업데이트
+  - OpenTelemetry 수집기의 새로운 상태를 반영하도록 문서 업데이트
+  - v1.14.7a4에 대한 변경 로그 및 버전 업데이트
+
+  ### 리팩토링
+  - 이벤트당 상태 비저장 방식으로 흐름 조건 평가 단순화
+  - 경로를 하나 줄여 대화 라우팅 사이클 개선
+
+  ## 기여자
+
+  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 9일">
+  ## v1.14.7a4
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
+
+  ## 변경 사항
+
+  ### 기능
+  - @listen/@router 런타임을 FlowDefinition에서 읽도록 마이그레이션
+  - 메모리, 지식, rag 및 flow에 대한 플러그형 기본 백엔드 추가
+
+  ### 문서
+  - v1.14.7a3에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 8일">
+  ## v1.14.7a3
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 실험적인 `AgentExecutor`에서 `ask_for_human_input` 노출 문제 수정
+  - `aiohttp`, `docling`, `docling-core`, 및 `pip`에 대한 pip-audit CVE 해결
+
+  ### 리팩토링
+  - `@start`를 `FlowDefinition`에서 읽도록 마이그레이션
+
+  ### 문서화
+  - v1.14.7a2에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 5일">
+  ## v1.14.7a2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
+
+  ## 변경 사항
+
+  ### 기능
+  - 대화 흐름 추적 지원 추가.
+  - `handle_turn`을 활용하도록 대화 흐름 문서 업데이트.
+  - LLM 이벤트에서 실제 `finish_reason`, 샘플링 매개변수 및 `response.id` 표시.
+  - 라우트 인식 데코레이터로서 DSL 트리거 유형 지정.
+  - 대화 흐름을 위한 채팅 API 구현.
+  - 잠금 저장소에서 백엔드 잠금 오버라이드 가능하게 설정.
+  - 흐름 DSL 모놀리스를 집중된 데코레이터 모듈로 분할.
+  - `_usage_to_dict`에서 LiteLLM 캐시/추론 사용 하위 카운트 평탄화.
+  - 흐름 DSL 메타데이터에서 `FlowDefinition` 구축.
+
+  ### 문서
+  - NVIDIA Nemotron LLM 가이드 추가.
+  - 모노레포 배포 문서화.
+  - v1.14.7a1에 대한 변경 로그 및 버전 업데이트.
+
+  ## 기여자
+
+  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="2026년 6월 3일">
+  ## v1.14.7a1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a1)
+
+  ## 변경 사항
+
+  ### 기능
+  - 승무원 교육을 받은 에이전트 파일 지원 추가
+  - 네이티브 Snowflake Cortex LLM 공급자 추가
+  - Databricks 통합 가이드 추가
+  - Snowflake 통합 가이드 추가
+
+  ### 버그 수정
+  - UV 도구 설치를 위한 crewai 패키지에서 `[project.scripts]` 복원하여 CLI 수정
+  - 파일 입력 신뢰성 문제 해결
+  - Snowflake Claude에서 불완전한 도구 결과 기록 수정
+  - Snowflake Claude를 위한 문자열화된 도구 호출 처리
+  - 라우터 주도 사이클 전반에 걸쳐 다중 소스 `or_` 리스너 재장착
+
+  ### 성능
+  - docling 가져오기를 지연 로딩하여 crewai 가져오기 속도 개선
+
+  ### 리팩토링
+  - `flow.py`를 DSL, 정의 및 런타임으로 분할
+
+  ## 기여자
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @jessemiller, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="2026년 5월 28일">
+  ## v1.14.6
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6)
+
+  ## 변경 사항
+
+  ### 기능
+  - 환경 변수 유출을 방지하기 위해 StdioTransport 강화
+  - 계획 구성 및 관찰 처리 개선
+  - DatabricksQueryTool에서 env_vars 선언
+  - 에이전트 제어 평면 문서 추가
+
+  ### 버그 수정
+  - 도구 호출 루프에서 구조화된 출력 유출 수정
+  - 체크포인트에서 원형으로 돌아갈 수 없는 콜백 및 어댑터 상태 제거
+  - 체크포인트에서 type[BaseModel] 필드를 JSON 스키마로 직렬화
+  - 복원 범위 복원 시 고아 task_started 방지
+  - AgentExecutor가 체크포인트에서 복원할 수 있도록 허용
+  - package_dependencies에서 mongodb 오타를 pymongo로 수정
+
+  ### 문서
+  - 에이전트 제어 평면 페이지에 ACP (Beta) 문서 탐색 블록 추가
+  - 프로세스 페이지에서 합의 프로세스 참조 제거
+  - 체크포인트 페이지 구조 재편성
+  - 일회성 관리자 패키지 설치 단계 문서화
+  - Secrets Manager / Workload Identity를 replicated-config에서 마이그레이션
+  - `<Steps>` 렌더링을 방해하는 `{" "}` JSX 표현 제거
+
+  ### 리팩토링
+  - Skills Repository를 실험적 + CREWAI_EXPERIMENTAL 게이트로 이동
+
+  ## 기여자
+
+  @akaKuruma, @alex-clawd, @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="2026년 5월 27일">
   ## v1.14.6a2
 

docs/ko/concepts/agents.mdx

@@ -66,13 +66,39 @@ CrewAI AOP에는 코드를 작성하지 않고도 에이전트 생성 및 구성
 
 ## 에이전트 생성
 
-CrewAI에서 에이전트를 생성하는 방법에는 **YAML 구성(권장)**을 사용하는 방법과 **코드에서 직접 정의**하는 두 가지가 있습니다.
+CrewAI에서 에이전트를 생성하는 일반적인 방법은 **JSONC 프로젝트 구성(새 crew 권장)** 또는 **코드에서 직접 정의**입니다.
 
-### YAML 구성 (권장)
+### JSONC 구성 (권장)
 
-YAML 구성을 사용하면 에이전트를 보다 깔끔하고 유지 관리하기 쉽도록 정의할 수 있습니다. CrewAI 프로젝트에서 이 방식을 사용하는 것을 강력히 권장합니다.
+`crewai create crew <name>`으로 만든 새 프로젝트는 JSON-first 구성을 사용합니다. 각 에이전트는 `agents/<agent_name>.jsonc`에 정의하고, `crew.jsonc`에서 crew에 포함할 에이전트를 나열합니다.
 
-[설치](/ko/installation) 섹션에 설명된 대로 CrewAI 프로젝트를 생성한 후, `src/latest_ai_development/config/agents.yaml` 파일로 이동하여 템플릿을 여러분의 요구 사항에 맞게 수정하세요.
+```jsonc agents/researcher.jsonc
+{
+  "role": "{topic} Senior Data Researcher",
+  "goal": "Uncover cutting-edge developments in {topic}",
+  "backstory": "You find the most relevant information and present it clearly.",
+  "llm": "openai/gpt-4o",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
+```
+
+`role`, `goal`, `backstory`에 `{placeholder}`를 사용할 수 있습니다. 기본값은 `crew.jsonc`의 `inputs`에 넣고, 빠진 값은 `crewai run`이 실행 시 물어봅니다. `verbose`, `allow_delegation`, `max_iter`, `memory`, `cache`, `planning_config` 같은 동작 필드는 최상위 또는 `settings` 안에 둘 수 있습니다.
+
+<Note>
+JSONC는 주석과 trailing comma를 지원합니다. `agents/<name>.jsonc`와 `agents/<name>.json`이 모두 있으면 CrewAI는 JSONC 파일을 사용합니다.
+</Note>
+
+### 클래식 YAML 구성
+
+`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `config/agents.yaml`과 `crew.py`의 `@CrewBase` 클래스를 사용합니다.
+
+YAML 구성은 기존 Python/YAML 프로젝트와 `@CrewBase` 클래스에서 에이전트를 정의하려는 팀을 위해 계속 지원됩니다.
+
+클래식 프로젝트를 만든 후, `src/<project_name>/config/agents.yaml` 파일로 이동하여 템플릿을 여러분의 요구 사항에 맞게 수정하세요.
 
 <Note>
 YAML 파일의 변수(예: `{topic}`)는 crew를 실행할 때 입력값에서 가져온 값으로 대체됩니다:
@@ -84,7 +110,7 @@ crew.kickoff(inputs={'topic': 'AI Agents'})
 아래는 YAML을 사용하여 에이전트를 구성하는 예시입니다:
 
 ```yaml agents.yaml
-# src/latest_ai_development/config/agents.yaml
+# src/<project_name>/config/agents.yaml
 researcher:
   role: >
     {topic} Senior Data Researcher
@@ -109,7 +135,7 @@ reporting_analyst:
 이 YAML 구성을 코드에서 사용하려면, `CrewBase`를 상속하는 crew 클래스를 생성하세요:
 
 ```python Code
-# src/latest_ai_development/crew.py
+# src/<project_name>/crew.py
 from crewai import Agent, Crew, Process
 from crewai.project import CrewBase, agent, crew
 from crewai_tools import SerperDevTool

docs/ko/concepts/cli.mdx

@@ -52,6 +52,8 @@ crewai create crew my_new_crew
 crewai create flow my_new_flow
 ```
 
+기본적으로 `crewai create crew`는 `crew.jsonc`와 `agents/*.jsonc`가 있는 JSON-first 프로젝트를 만듭니다. `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요할 때만 `crewai create crew my_new_crew --classic`을 사용하세요.
+
 ### 2. 버전
 
 설치된 CrewAI의 버전을 표시합니다.
@@ -183,7 +185,20 @@ crewai chat
 이 명령어들은 CrewAI 프로젝트의 루트 디렉터리에서 실행해야 합니다.
 </Note>
 <Note>
-중요: 이 명령어를 사용하려면 `crew.py` 파일에서 `chat_llm` 속성을 설정해야 합니다.
+중요: 이 명령어를 사용하려면 crew 정의에 `chat_llm` 속성을 설정해야 합니다.
+
+JSON-first crew에서는 `crew.jsonc`에 추가합니다:
+
+```jsonc
+{
+  "name": "My Crew",
+  "agents": ["researcher"],
+  "tasks": [],
+  "chat_llm": "openai/gpt-4o"
+}
+```
+
+클래식 Python/YAML crew에서는 `crew.py`에 설정합니다:
 
 ```python
 @crew
@@ -313,7 +328,7 @@ CLI를 사용하여 [CrewAI AMP](http://app.crewai.com)에 crew를 배포하는
 
 ### 11. API 키
 
-`crewai create crew` 명령어를 실행하면, CLI에서 선택할 수 있는 LLM 제공업체 목록이 표시되고, 그 다음으로 선택한 제공업체에 대한 모델 선택이 이어집니다.
+`crewai create crew` 명령어를 실행하면, CLI에서 선택할 수 있는 LLM 제공업체 목록이 표시되고, 그 다음으로 선택한 제공업체에 대한 모델 선택이 이어집니다. 선택한 모델은 생성된 `.env`에 저장되며 각 에이전트 JSONC 파일은 자체 `llm`을 설정할 수 있습니다.
 
 LLM 제공업체와 모델을 선택하면, API 키를 입력하라는 메시지가 표시됩니다.
 

docs/ko/concepts/crews.mdx

@@ -41,13 +41,54 @@ crewAI에서 crew는 일련의 작업을 달성하기 위해 함께 협력하는
 
 ## 크루 생성하기
 
-CrewAI에서 크루를 생성하는 방법은 두 가지가 있습니다: **YAML 구성(권장)**을 사용하는 방법과 **코드에서 직접 정의**하는 방법입니다.
+CrewAI에서 크루를 생성하는 주요 방법은 **JSONC 구성(새 crew 권장)**을 사용하는 방법과 클래식 프로젝트나 고급 사용 사례에서 **코드로 직접 정의**하는 방법입니다.
 
-### YAML 구성 (권장)
+### JSONC 구성 (권장)
 
-YAML 구성을 사용하면 crew를 정의할 때 더 깔끔하고 유지 관리하기 쉬운 방법을 제공하며, CrewAI 프로젝트에서 agent 및 task를 정의하는 방식과 일관성을 유지할 수 있습니다.
+`crewai create crew <name>`으로 만든 새 프로젝트는 crew 수준 설정과 태스크를 `crew.jsonc`에 두고, 각 에이전트를 `agents/`의 별도 파일에 둡니다. `crewai run`은 `crew.jsonc` 또는 `crew.json`을 감지해 에이전트를 로드하고, 빠진 placeholder 값을 물은 뒤 crew를 시작합니다.
 
-[설치](/ko/installation) 섹션에 설명된 대로 CrewAI 프로젝트를 생성한 후, `CrewBase`를 상속받는 클래스에서 데코레이터를 이용해 agent, task, 그리고 crew 자체를 정의할 수 있습니다.
+```jsonc crew.jsonc
+{
+  "name": "Market Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research",
+      "description": "Research {topic} and collect the most relevant facts.",
+      "expected_output": "Structured research notes about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis",
+      "description": "Analyze the research and write a concise report.",
+      "expected_output": "A markdown report with findings and recommendations.",
+      "agent": "analyst",
+      "context": ["research"],
+      "output_file": "output/report.md"
+    }
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
+```
+
+`agents`의 각 문자열은 먼저 `agents/<name>.jsonc`, 그 다음 `agents/<name>.json`으로 해석됩니다. 계층형 crew는 `"process": "hierarchical"`와 `manager_llm` 또는 `manager_agent`를 사용하세요.
+
+<Warning>
+신뢰하는 출처의 JSON crew 프로젝트만 실행하세요. `custom:<name>` 도구와 `{"python": "module.attribute"}` 참조는 crew 로드 시 로컬 Python 코드를 실행합니다.
+</Warning>
+
+### 클래식 YAML 구성
+
+`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, `@CrewBase`, `@agent`, `@task`, `@crew` 데코레이터를 사용합니다.
+
+이 방식은 기존 Python/YAML 프로젝트와 Python 데코레이터 제어가 필요한 팀을 위해 계속 지원됩니다.
+
+클래식 프로젝트를 만든 후, `CrewBase`를 상속받는 클래스에서 데코레이터를 이용해 agent, task, 그리고 crew 자체를 정의할 수 있습니다.
 
 #### 데코레이터가 적용된 예시 Crew 클래스
 
@@ -416,4 +457,4 @@ crewai log-tasks-outputs
 crewai replay -t <task_id>
 ```
 
-이 명령어들을 사용하면 이전에 실행된 작업의 컨텍스트를 유지하면서 최신 kickoff 작업부터 다시 실행할 수 있습니다.
+이 명령어들을 사용하면 이전에 실행된 작업의 컨텍스트를 유지하면서 최신 kickoff 작업부터 다시 실행할 수 있습니다.

docs/ko/concepts/flows.mdx

@@ -221,6 +221,48 @@ Flow가 실행된 후, 이러한 메소드들에 의해 수행된 업데이트
 최종 메소드의 출력이 반환되고 상태에 접근할 수 있도록 함으로써, CrewAI Flow는 AI 워크플로우의 결과를 더 큰 애플리케이션이나 시스템에 쉽게 통합할 수 있게 하며,
 Flow 실행 과정 전반에 걸쳐 상태를 유지하고 접근하면서도 이를 용이하게 만듭니다.
 
+## 플로우 사용 메트릭
+
+Flow 실행이 완료된 후, `usage_metrics` 속성에 접근하여 실행 동안 발생한 **모든 LLM 호출**의 토큰 사용량 집계를 확인할 수 있습니다. 여기에는 Flow가 오케스트레이션한 모든 Crew의 호출, Agent의 도구 내부에서 발생한 호출, 그리고 Flow 메서드에서 직접 호출한 `LLM.call(...)`이 모두 포함됩니다. 이는 CrewAI Enterprise UI에 표시되는 총량과 동등한 SDK 측 값입니다.
+
+```python Code
+from crewai import LLM
+from crewai.flow.flow import Flow, listen, start
+
+class UsageMetricsFlow(Flow):
+    @start()
+    def run_first_crew(self):
+        self.state.first_result = FirstCrew().crew().kickoff()
+
+    @listen(run_first_crew)
+    def call_llm_directly(self):
+        # 직접 LLM 호출 — flow.usage_metrics에서도 집계됩니다
+        llm = LLM(model="openai/gpt-4o-mini")
+        self.state.summary = llm.call("핵심 내용을 요약해 주세요.")
+
+    @listen(call_llm_directly)
+    def run_second_crew(self):
+        self.state.second_result = SecondCrew().crew().kickoff()
+
+flow = UsageMetricsFlow()
+flow.kickoff()
+
+print(flow.usage_metrics)
+# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
+#              cached_prompt_tokens=0, reasoning_tokens=0,
+#              cache_creation_tokens=0, successful_requests=5)
+```
+
+<Note>
+  `flow.usage_metrics`는 `flow.kickoff().token_usage`와 **동일하지 않습니다**.
+  후자는 `CrewOutput`을 반환한 **마지막** `@listen` 메서드의
+  `CrewOutput.token_usage`만 반환하므로, 이전에 실행된 Crew들과 Flow 메서드에서
+  직접 호출한 `LLM.call(...)`은 전혀 포함되지 않습니다. Flow 실행에 대한
+  **전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오.
+</Note>
+
+반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다.
+
 ## 플로우 상태 관리
 
 상태를 효과적으로 관리하는 것은 신뢰할 수 있고 유지 보수가 용이한 AI 워크플로를 구축하는 데 매우 중요합니다. CrewAI 플로우는 비정형 및 정형 상태 관리를 위한 강력한 메커니즘을 제공하여, 개발자가 자신의 애플리케이션에 가장 적합한 접근 방식을 선택할 수 있도록 합니다.
@@ -781,7 +823,7 @@ CrewAI에서 여러 crews로 flow를 생성하는 것은 간단합니다.
 crewai create flow name_of_flow
 ```
 
-이 명령어는 필요한 폴더 구조를 갖춘 새 CrewAI 프로젝트를 생성합니다. 생성된 프로젝트에는 이미 동작 중인 미리 구축된 crew인 `poem_crew`가 포함되어 있습니다. 이 crew를 템플릿으로 사용하여 복사, 붙여넣기, 수정함으로써 다른 crew를 만들 수 있습니다.
+이 명령어는 필요한 폴더 구조를 갖춘 새 CrewAI 프로젝트를 생성합니다. 생성된 프로젝트에는 이미 동작 중인 미리 구축된 crew인 `poem_crew`가 포함되어 있습니다. 시작용 embedded crew는 클래식 Python/YAML 레이아웃을 사용하며, `crewai create crew`로 만든 새 독립 실행형 crew는 JSON-first 레이아웃을 사용합니다.
 
 ### 폴더 구조
 
@@ -811,7 +853,29 @@ crewai create flow name_of_flow
 - `config/tasks.yaml`: 크루의 task를 정의합니다.
 - `poem_crew.py`: agent, task, 그리고 크루 자체를 포함한 crew 정의가 들어 있습니다.
 
-`poem_crew`를 복사, 붙여넣기, 그리고 편집하여 다른 크루를 생성할 수 있습니다.
+`poem_crew`를 복사, 붙여넣기, 그리고 편집하여 다른 클래식 embedded crew를 생성할 수 있습니다.
+
+JSON-first embedded crew는 `crew.jsonc`와 `agents/*.jsonc`가 있는 폴더를 사용하세요:
+
+```text
+crews/
+└── research_crew/
+    ├── agents/
+    │   └── researcher.jsonc
+    └── crew.jsonc
+```
+
+그런 다음 Flow 단계에서 로드합니다:
+
+```python
+from pathlib import Path
+from crewai.project import load_crew
+
+crew, default_inputs = load_crew(
+    Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc"
+)
+result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"})
+```
 
 ### `main.py`에서 Crew 연결하기
 

docs/ko/concepts/llms.mdx

@@ -106,7 +106,7 @@ CrewAI 코드 내에는 사용할 모델을 지정할 수 있는 여러 위치
 </Tabs>
 
 <Info>
-  CrewAI는 OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock에 대해 네이티브 SDK 통합을 제공합니다 — 제공자별 extras(예: `uv add "crewai[openai]"`) 외에 추가 설치가 필요하지 않습니다.
+  CrewAI는 OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock, Snowflake Cortex에 대해 네이티브 SDK 통합을 제공합니다 — 제공자별 extras(예: `uv add "crewai[openai]"`) 외에 추가 설치가 필요하지 않습니다.
 
   그 외 모든 제공자는 **LiteLLM**을 통해 지원됩니다. 이를 사용하려면 프로젝트에 의존성으로 추가하세요:
   ```bash
@@ -230,6 +230,55 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     ```
   </Accordion>
 
+  <Accordion title="Snowflake Cortex">
+    CrewAI는 OpenAI 호환 Chat Completions 엔드포인트를 통해 Snowflake Cortex REST API와 네이티브로 통합됩니다. `snowflake/...` 모델은 LiteLLM fallback 없이 사용됩니다. CrewAI에서 Snowflake Cortex는 현재 Chat Completions만 지원하므로 기본 `api` 모드를 사용하고 `api="responses"`를 설정하지 마세요.
+
+    ```toml Code
+    # Required
+    SNOWFLAKE_PAT=<your-programmatic-access-token>
+    SNOWFLAKE_ACCOUNT_URL=https://<account-identifier>.snowflakecomputing.com
+
+    # Alternative account configuration
+    SNOWFLAKE_ACCOUNT=<account-identifier>
+    ```
+
+    **기본 사용법:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/openai-gpt-4.1",
+        temperature=0.7,
+        max_completion_tokens=1024,
+    )
+    ```
+
+    **Cortex의 Claude 모델:**
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="snowflake/claude-sonnet-4-5",
+        max_completion_tokens=1024,
+        stream=True,
+    )
+    ```
+
+    **지원 환경 변수:**
+    - `SNOWFLAKE_PAT`, `SNOWFLAKE_TOKEN`, 또는 `SNOWFLAKE_JWT`: Bearer 자격 증명으로 사용할 토큰
+    - `SNOWFLAKE_ACCOUNT_URL`: 전체 Snowflake 계정 URL
+    - `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_ACCOUNT_ID`, 또는 `SNOWFLAKE_ACCOUNT_IDENTIFIER`: 계정 URL을 만들 계정 식별자
+
+    Snowflake REST 요청은 사용자의 기본 Snowflake role을 사용합니다. 해당 role에 `SNOWFLAKE.CORTEX_USER` 또는 `SNOWFLAKE.CORTEX_REST_API_USER`가 있는지 확인하세요. Cortex REST Chat Completions 엔드포인트에는 database, schema, warehouse, 명시적 role 파라미터가 필요하지 않습니다.
+
+    **기능:**
+    - `model="snowflake/<model-name>"`을 통한 네이티브 provider 선택
+    - Streaming 및 non-streaming Chat Completions만 지원; `api="responses"`는 지원되지 않음
+    - 토큰 사용량 추적
+    - Snowflake 호스팅 OpenAI 및 Claude 모델의 함수 호출
+    - Snowflake Claude 모델에서 유효하지 않은 마지막 assistant prefill 자동 제거
+  </Accordion>
+
   <Accordion title="Anthropic">
     ```toml Code
     # Required

docs/ko/concepts/processes.mdx

@@ -16,7 +16,6 @@ mode: "wide"
 
 - **순차적(Sequential)**: 작업을 순차적으로 실행하여 작업이 질서 있게 진행되도록 보장합니다.
 - **계층적(Hierarchical)**: 작업을 관리 계층 구조로 조직하며, 작업은 체계적인 명령 체계를 기반으로 위임 및 실행됩니다. 계층적 프로세스를 활성화하려면 매니저 언어 모델(`manager_llm`) 또는 커스텀 매니저 에이전트(`manager_agent`)를 crew에서 지정해야 하며, 이를 통해 매니저가 작업을 생성하고 관리할 수 있도록 지원합니다.
-- **합의 프로세스(Consensual Process, 계획됨)**: 에이전트들 간에 작업 실행에 대한 협력적 의사결정을 목표로 하며, 이 프로세스 유형은 CrewAI 내에서 작업 관리를 민주적으로 접근하도록 도입됩니다. 앞으로 개발될 예정이며, 현재 코드베이스에는 구현되어 있지 않습니다.
 
 ## 팀워크에서 프로세스의 역할
 프로세스는 개별 에이전트가 통합된 단위로 작동할 수 있도록 하여, 공통된 목표를 효율적이고 일관성 있게 달성하도록 노력하는 과정을 간소화합니다.
@@ -59,9 +58,9 @@ crew = Crew(
 
 ## Process 클래스: 상세 개요
 
-`Process` 클래스는 열거형(`Enum`)으로 구현되어 타입 안전성을 보장하며, 프로세스 값을 정의된 타입(`sequential`, `hierarchical`)으로 제한합니다. 합의 기반(consensual) 프로세스는 향후 추가될 예정이며, 이는 지속적인 개발과 혁신에 대한 우리의 의지를 강조합니다.
+`Process` 클래스는 열거형(`Enum`)으로 구현되어 타입 안전성을 보장하며, 프로세스 값을 정의된 타입(`sequential`, `hierarchical`)으로 제한합니다.
 
 ## 결론
 
 CrewAI 내의 프로세스를 통해 촉진되는 구조화된 협업은 에이전트 간 체계적인 팀워크를 가능하게 하는 데 매우 중요합니다.  
-이 문서는 최신 기능, 향상 사항, 그리고 예정된 Consensual Process 통합을 반영하도록 업데이트되었으며, 사용자가 가장 최신이고 포괄적인 정보를 이용할 수 있도록 보장합니다.
+이 문서는 최신 기능과 향상 사항을 반영하도록 업데이트되었으며, 사용자가 가장 최신이고 포괄적인 정보를 이용할 수 있도록 보장합니다.

docs/ko/concepts/tasks.mdx

@@ -64,13 +64,48 @@ crew = Crew(
 
 ## 작업 생성하기
 
-CrewAI에서 작업을 생성하는 방법에는 **YAML 구성(권장)** 을 사용하는 방법과 **코드에서 직접 정의하는 방법** 두 가지가 있습니다.
+CrewAI에서 작업을 생성하는 일반적인 방법은 **JSONC 프로젝트 구성(새 crew 권장)** 또는 **코드에서 직접 정의**입니다.
 
-### YAML 구성 (권장)
+### JSONC 구성 (권장)
 
-YAML 구성을 사용하면 작업을 정의할 때 더 깔끔하고 유지 관리가 용이한 방법을 제공합니다. CrewAI 프로젝트에서 작업을 정의할 때 이 방식을 사용하는 것을 강력히 권장합니다.
+`crewai create crew <name>`으로 만든 새 프로젝트는 `crew.jsonc`에 태스크를 정의합니다.
 
-[설치](/ko/installation) 섹션에 따라 CrewAI 프로젝트를 생성한 후, `src/latest_ai_development/config/tasks.yaml` 파일로 이동하여 템플릿을 귀하의 특정 작업 요구 사항에 맞게 수정하세요.
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "reporting_analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research about {topic}.",
+      "expected_output": "A list of the most relevant information about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "reporting_task",
+      "description": "Review the research and expand it into a detailed report.",
+      "expected_output": "A polished markdown report.",
+      "agent": "reporting_analyst",
+      "context": ["research_task"],
+      "markdown": true,
+      "output_file": "report.md"
+    }
+  ],
+  "inputs": {
+    "topic": "AI Agents"
+  }
+}
+```
+
+각 태스크에는 `description`과 `expected_output`이 필요합니다. `agent` 값은 `agents`에 나열된 에이전트 이름과 일치해야 합니다. `context`는 이전 태스크 이름만 참조할 수 있으며, 이후 태스크 참조는 거부됩니다.
+
+### 클래식 YAML 구성
+
+`crewai create crew <name> --classic`으로 만든 클래식 프로젝트는 `config/tasks.yaml`과 `crew.py`의 `@CrewBase` 클래스를 사용합니다.
+
+YAML 구성은 기존 Python/YAML 프로젝트와 `@CrewBase` 클래스에서 태스크를 정의하려는 팀을 위해 계속 지원됩니다.
+
+클래식 프로젝트를 만든 후, `src/<project_name>/config/tasks.yaml` 파일로 이동하여 템플릿을 작업 요구 사항에 맞게 수정하세요.
 
 <Note>
 YAML 파일 내 변수(예: `{topic}`)는 크루를 실행할 때 입력값에서 가져온 값으로 대체됩니다:
@@ -106,7 +141,7 @@ reporting_task:
 이 YAML 구성을 코드에서 사용하려면 `CrewBase`를 상속받는 크루 클래스를 생성하세요:
 
 ```python crew.py
-# src/latest_ai_development/crew.py
+# src/<project_name>/crew.py
 
 from crewai import Agent, Crew, Process, Task
 from crewai.project import CrewBase, agent, crew, task

docs/ko/enterprise/features/agent-control-plane/monitoring.mdx

@@ -6,6 +6,14 @@ icon: "gauge"
 mode: "wide"
 ---
 
+<Info>
+  **ACP (베타) 문서 내비게이션**
+
+  - [개요](/ko/enterprise/features/agent-control-plane/overview)
+  - **모니터링** *(현재 페이지)*
+  - [규칙](/ko/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## 개요
 
 **Automations** 탭은 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)의 읽기 전용 운영 뷰입니다. 두 개의 메트릭 카드, 인터랙티브 sankey, 그리고 **Automations**와 **Consumption** 두 개의 서브 테이블을 결합해 검색·필터·정렬을 지원합니다.

docs/ko/enterprise/features/agent-control-plane/overview.mdx

@@ -5,6 +5,14 @@ sidebarTitle: 개요
 icon: "book-open"
 ---
 
+<Info>
+  **ACP (베타) 문서 내비게이션**
+
+  - **개요** *(현재 페이지)*
+  - [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
+  - [규칙](/ko/enterprise/features/agent-control-plane/rules)
+</Info>
+
 ## 개요
 
 **Agent Control Plane**(ACP)은 CrewAI AMP에서 실행 중인 모든 워크로드를 위한 운영 허브입니다. **Automations**와 **Rules** 두 개의 탭으로 구성된 단일 화면에서 다음 작업을 할 수 있습니다:

docs/ko/enterprise/features/agent-control-plane/rules.mdx

@@ -6,6 +6,14 @@ icon: "shield-check"
 mode: "wide"
 ---
 
+<Info>
+  **ACP (베타) 문서 내비게이션**
+
+  - [개요](/ko/enterprise/features/agent-control-plane/overview)
+  - [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
+  - **규칙** *(현재 페이지)*
+</Info>
+
 ## 개요
 
 규칙(Rules)은 각 deployment를 개별 설정하는 대신, 정책 — 현재: **PII Redaction** — 을 한 번에 여러 자동화에 적용할 수 있게 해줍니다. 관리하려면 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)에서 **Rules** 탭을 엽니다.

docs/ko/enterprise/features/secrets-manager/verify-rotation.mdx

@@ -26,10 +26,10 @@ icon: "arrows-rotate"
 
 ## 1단계 — 검증 Crew 스캐폴딩
 
-새 Crew 프로젝트를 만듭니다. CrewAI CLI가 구조를 스캐폴딩합니다:
+이 예제는 `crew.py`를 통해 Python 도구를 연결하므로 클래식 crew 프로젝트를 만듭니다:
 
 ```bash
-crewai create crew rotation_verifier --skip_provider
+crewai create crew rotation_verifier --classic --skip_provider
 cd rotation_verifier
 ```
 

docs/ko/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자
 
 1. CrewAI AMP에서 **Settings** > **OpenTelemetry Collectors**로 이동합니다.
 2. **Add Collector**를 클릭합니다.
-3. 통합 유형을 선택합니다 — **OpenTelemetry Traces** 또는 **OpenTelemetry Logs**.
-4. 연결을 구성합니다:
-   - **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`).
-   - **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름.
-   - **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다.
-   - **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다.
-5. **Save**를 클릭합니다.
+3. 통합을 선택합니다:
+   - **OpenTelemetry Traces** 및 **OpenTelemetry Logs** — OTLP 호환 수집기 또는 백엔드로 내보냅니다.
+   - **Datadog** — 별도의 수집기나 Datadog Agent 없이 트레이스를 Datadog의 OTLP 인테이크로 직접 전송합니다.
+4. 연결을 구성합니다. 필드는 선택한 통합에 따라 달라집니다:
 
-<Frame>![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    **OpenTelemetry Traces**와 **OpenTelemetry Logs**는 동일한 필드를 공유하는 별개의 통합입니다 — 내보내려는 신호에 맞는 것을 선택하세요.
+
+    - **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`).
+    - **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름.
+    - **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다.
+    - **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다.
+
+    <Frame>![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — Datadog 사이트의 OTLP 호스트만 입력합니다 (프로토콜이나 경로 제외). CrewAI가 전체 HTTPS OTLP 엔드포인트를 자동으로 구성합니다. [Datadog 사이트](https://docs.datadoghq.com/getting_started/site/)에 맞는 호스트를 사용하세요:
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — Datadog API 키입니다. [키 생성 방법](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)을 참고하세요.
+
+    Datadog 통합은 **트레이스**를 내보냅니다.
+
+    <Frame>![Datadog 수집기 구성](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(선택 사항)* **Test Connection**을 클릭하여 제공한 자격 증명으로 CrewAI가 엔드포인트에 연결할 수 있는지 확인합니다.
+6. **Save**를 클릭합니다.
 
 <Tip>
   여러 수집기를 추가할 수 있습니다 — 예를 들어, 트레이스용 하나와 로그용 하나를 추가하거나, 다른 목적을 위해 다른 백엔드로 전송할 수 있습니다.

docs/ko/enterprise/guides/deploy-to-amp.mdx

@@ -163,6 +163,12 @@ Crew를 GitHub 저장소에 푸시해야 합니다. 아직 Crew를 만들지 않
       ![Select Repository](/images/enterprise/select-repo.png)
     </Frame>
 
+    <Tip>
+      Crew 또는 Flow가 모노레포 하위 폴더 안에 있다면 배포 전에
+      **Advanced**를 펼치고 작업 디렉터리를 설정하세요.
+      [모노레포 배포](/ko/enterprise/guides/monorepo-deployments)를 참조하세요.
+    </Tip>
+
   </Step>
 
   <Step title="환경 변수 설정하기">
@@ -367,17 +373,17 @@ git push
 
 **해결책**: 프로젝트가 예상 구조와 일치하는지 확인합니다:
 
-- **Crews와 Flows 모두**: 진입점이 `src/project_name/main.py`에 있어야 합니다
-- **Crews**: 진입점으로 `run()` 함수 사용
-- **Flows**: 진입점으로 `kickoff()` 함수 사용
+- **JSON-first Crews**: `crew.jsonc` 또는 `crew.json`과 `agents/`를 프로젝트 루트에 둡니다
+- **클래식 Crews**: `src/project_name/main.py`에 `run()` 진입점을 둡니다
+- **Flows**: `src/project_name/main.py`에 `kickoff()` 진입점을 둡니다
 
 자세한 구조 다이어그램은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.
 
-#### CrewBase 데코레이터 누락
+#### 클래식 Crew의 CrewBase 데코레이터 누락
 
 **증상**: "Crew not found", "Config not found" 또는 agent/task 구성 오류
 
-**해결책**: **모든** crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다:
+**해결책**: 클래식 Python/YAML crew에서는 모든 crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다. JSON-first crew에는 이 데코레이터가 필요하지 않습니다.
 
 ```python
 from crewai.project import CrewBase, agent, crew, task
@@ -397,8 +403,8 @@ class YourCrew():
 ```
 
 <Info>
-  이것은 독립 실행형 Crews와 Flow 프로젝트 내에 포함된 crews 모두에 적용됩니다.
-  모든 crew 클래스에 데코레이터가 필요합니다.
+  이것은 Flow 프로젝트에 포함된 클래식 crew를 포함하여 클래식 Python crew 클래스에 적용됩니다.
+  JSON-first crew는 `crew.jsonc`와 `agents/`를 기준으로 검증됩니다.
 </Info>
 
 #### 잘못된 pyproject.toml 타입
@@ -435,9 +441,9 @@ type = "flow"
 **해결책**:
 1. AMP 대시보드에서 실행 로그를 확인합니다 (Traces 탭)
 2. 모든 도구에 필요한 API 키가 구성되어 있는지 확인합니다
-3. `agents.yaml`의 agent 구성이 유효한지 확인합니다
-4. `tasks.yaml`의 task 구성에 구문 오류가 없는지 확인합니다
+3. JSON-first crew의 경우 `crew.jsonc`와 `agents/`에서 참조한 파일을 검증합니다
+4. 클래식 crew의 경우 `agents.yaml`과 `tasks.yaml`이 유효한지 확인합니다
 
 <Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
   배포 문제 또는 AMP 플랫폼에 대한 문의 사항이 있으시면 지원팀에 연락해 주세요.
-</Card>
+</Card>

docs/ko/enterprise/guides/monorepo-deployments.mdx

@@ -0,0 +1,226 @@
+---
+title: "모노레포 배포"
+description: "더 큰 저장소의 하위 폴더에서 Crew 또는 Flow 배포하기"
+icon: "folder-tree"
+mode: "wide"
+---
+
+<Note>
+  Crew 또는 Flow가 더 큰 저장소 안에 있을 때 작업 디렉터리를 사용하세요.
+  CrewAI AMP는 저장소 루트 대신 해당 하위 폴더에서 자동화를 검증, 빌드,
+  실행합니다.
+</Note>
+
+## 사용 시점
+
+모노레포 배포는 하나의 저장소에 여러 자동화, 공유 패키지 또는 다른 애플리케이션
+코드가 함께 있을 때 유용합니다:
+
+```text
+company-ai/
+|-- uv.lock
+|-- packages/
+|   `-- shared_tools/
+`-- crews/
+    |-- support_agent/
+    |   |-- pyproject.toml
+    |   |-- crew.jsonc
+    |   `-- agents/
+    |       `-- support_agent.jsonc
+    `-- research_flow/
+        |-- pyproject.toml
+        `-- src/
+            `-- research_flow/
+                `-- main.py
+```
+
+`support_agent`를 배포하려면 작업 디렉터리를 다음과 같이 설정합니다:
+
+```text
+crews/support_agent
+```
+
+AMP는 여전히 전체 저장소를 가져오거나 업로드하지만, 선택한 폴더를 자동화
+프로젝트 루트로 처리합니다.
+
+## 작업 디렉터리가 제어하는 항목
+
+작업 디렉터리가 설정되면 AMP는 해당 폴더를 다음 용도로 사용합니다:
+
+- `pyproject.toml`, JSON crew 파일, 클래식 Crew 또는 Flow 진입점을 포함한 프로젝트 검증
+- `uv`를 사용한 종속성 설치
+- 실행 중인 프로세스의 작업 디렉터리
+- `CREW_ROOT_DIR` 환경 변수
+
+필드를 비워 두면 기존 동작이 유지되며 저장소 루트를 사용합니다.
+
+## 지원되는 소스
+
+다음 소스에서 배포를 만들 때 작업 디렉터리를 설정할 수 있습니다:
+
+- 연결된 GitHub 저장소
+- AMP에 구성된 Git 저장소
+- ZIP 업로드
+
+<Info>
+  작업 디렉터리는 AMP 웹 인터페이스에서 구성하세요.
+  `crewai deploy create` CLI 흐름은 이 필드를 묻지 않습니다.
+</Info>
+
+기존 배포의 **Settings** 페이지에서도 작업 디렉터리를 추가하거나 변경할 수
+있습니다. 변경 사항은 다음 배포부터 적용됩니다.
+
+<Warning>
+  작업 디렉터리와 auto-deploy는 함께 사용할 수 없습니다. 배포에 작업
+  디렉터리가 설정되어 있으면 해당 배포의 auto-deploy가 비활성화됩니다.
+  작업 디렉터리를 설정하기 전에 auto-deploy를 끄세요.
+</Warning>
+
+## 새 배포 구성
+
+<Steps>
+  <Step title="Deploy from Code 열기">
+    CrewAI AMP에서 새 배포를 만들고 소스를 선택합니다: GitHub, Git
+    Repository 또는 ZIP 업로드.
+  </Step>
+
+  <Step title="저장소, 브랜치 또는 ZIP 파일 선택">
+    모노레포가 들어 있는 저장소와 브랜치를 선택하거나, 루트에 모노레포 내용이
+    포함된 ZIP 파일을 업로드합니다.
+  </Step>
+
+  <Step title="고급 설정 열기">
+    배포 양식에서 **Advanced** 섹션을 펼칩니다.
+  </Step>
+
+  <Step title="작업 디렉터리 입력">
+    저장소 루트에서 Crew 또는 Flow 프로젝트까지의 경로를 입력합니다:
+
+    ```text
+    crews/support_agent
+    ```
+
+    앞에 슬래시를 붙이지 마세요.
+  </Step>
+
+  <Step title="배포">
+    필요한 환경 변수를 추가한 다음 배포를 시작합니다.
+  </Step>
+</Steps>
+
+## 기존 배포 구성
+
+<Steps>
+  <Step title="배포 설정 열기">
+    AMP에서 자동화로 이동한 뒤 **Settings**를 엽니다.
+  </Step>
+
+  <Step title="필요한 경우 auto-deploy 끄기">
+    auto-deploy가 활성화되어 있으면 먼저 끄세요. auto-deploy가 켜져 있는
+    동안에는 작업 디렉터리 필드를 사용할 수 없습니다.
+  </Step>
+
+  <Step title="작업 디렉터리 설정">
+    **Basic settings**에서 다음과 같은 하위 폴더 경로를 입력합니다:
+
+    ```text
+    crews/support_agent
+    ```
+  </Step>
+
+  <Step title="다시 배포">
+    설정을 저장하고 자동화를 다시 배포합니다. 새 작업 디렉터리는 다음 배포부터
+    사용됩니다.
+  </Step>
+</Steps>
+
+## 경로 규칙
+
+작업 디렉터리는 저장소 또는 ZIP 루트 안의 상대 경로여야 합니다.
+
+| 규칙 | 예시 |
+|------|------|
+| 상대 경로를 사용합니다 | `crews/support_agent` |
+| `/`로 시작하지 않습니다 | `/crews/support_agent`는 유효하지 않습니다 |
+| `.` 또는 `..` 경로 세그먼트를 사용하지 않습니다 | `crews/../support_agent`는 유효하지 않습니다 |
+| 문자, 숫자, 하이픈, 밑줄, 점, 슬래시만 사용합니다 | `crews/support agent`는 유효하지 않습니다 |
+| 경로는 255자 이하로 유지합니다 | 더 긴 경로는 거부됩니다 |
+
+AMP는 앞뒤 공백을 제거하고, 반복된 슬래시를 하나로 줄이며, 끝의 슬래시를
+제거합니다. 빈 값은 저장소 루트를 사용합니다.
+
+## Lock 파일과 UV 워크스페이스
+
+선택한 폴더에는 자동화의 `pyproject.toml`과 프로젝트 유형에 맞는 파일이
+있어야 합니다:
+
+- JSON-first crew: `crew.jsonc` 또는 `crew.json`과 `agents/`
+- 클래식 Crew 또는 Flow: Python 진입점이 있는 `src/`
+
+`uv.lock` 또는 `poetry.lock` 파일은 선택한 폴더나 저장소 루트에 둘 수
+있습니다.
+
+이 방식은 일반적인 두 가지 lock 파일 배치를 모두 지원합니다:
+
+<Tabs>
+  <Tab title="프로젝트 lock 파일">
+    ```text
+    company-ai/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- uv.lock
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+
+  <Tab title="워크스페이스 lock 파일">
+    ```text
+    company-ai/
+    |-- uv.lock
+    |-- packages/
+    |   `-- shared_tools/
+    `-- crews/
+        `-- support_agent/
+            |-- pyproject.toml
+            |-- crew.jsonc
+            `-- agents/
+                `-- support_agent.jsonc
+    ```
+  </Tab>
+</Tabs>
+
+<Tip>
+  자동화가 모노레포의 다른 위치에 있는 공유 패키지를 가져온다면, UV
+  workspace, path 또는 source 설정을 사용해 해당 패키지를 `pyproject.toml`에
+  선언하세요. AMP는 선택한 폴더에서 자동화를 실행하므로, 저장소 루트가
+  Python path에 있다고 가정하기보다 공유 코드를 종속성으로 설치해야 합니다.
+</Tip>
+
+## 문제 해결
+
+### 작업 디렉터리를 찾을 수 없음
+
+경로가 저장소 또는 ZIP 루트를 기준으로 한 상대 경로인지 확인하세요. ZIP
+업로드의 경우 ZIP 내용에 입력한 작업 디렉터리 경로가 정확히 포함되어야 합니다.
+
+### pyproject.toml 누락
+
+작업 디렉터리는 여러 프로젝트를 담은 상위 폴더가 아니라 Crew 또는 Flow 프로젝트
+폴더를 가리켜야 합니다.
+
+### uv.lock 또는 poetry.lock 누락
+
+선택한 프로젝트 폴더 또는 저장소 루트에 lock 파일을 커밋하세요. UV
+워크스페이스의 경우 `uv.lock`을 워크스페이스 루트에 두는 방식이 지원됩니다.
+
+### Auto-Deploy를 사용할 수 없음
+
+작업 디렉터리가 설정되어 있으면 auto-deploy가 비활성화됩니다. 수동 재배포를
+사용하거나 AMP API로 CI/CD에서 재배포를 트리거하세요.
+
+<Card title="AMP에 배포하기" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
+  모노레포 작업 디렉터리를 선택한 뒤 배포 가이드를 계속 진행하세요.
+</Card>

docs/ko/enterprise/guides/prepare-for-deployment.mdx

@@ -24,7 +24,7 @@ CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프
 
 <CardGroup cols={2}>
   <Card title="Crew 프로젝트" icon="users">
-    에이전트와 작업을 정의하는 `crew.py`가 있는 독립 실행형 AI 에이전트 팀. 집중적이고 협업적인 작업에 적합합니다.
+    독립 실행형 AI 에이전트 팀입니다. 새 crew는 `crew.jsonc`와 `agents/`를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 `crew.py`를 사용할 수 있습니다.
   </Card>
   <Card title="Flow 프로젝트" icon="diagram-project">
     `crews/` 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.
@@ -33,19 +33,19 @@ CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프
 
 | 측면 | Crew | Flow |
 |------|------|------|
-| **프로젝트 구조** | `crew.py`가 있는 `src/project_name/` | `crews/` 폴더가 있는 `src/project_name/` |
-| **메인 로직 위치** | `src/project_name/crew.py` | `src/project_name/main.py` (Flow 클래스) |
-| **진입점 함수** | `main.py`의 `run()` | `main.py`의 `kickoff()` |
+| **프로젝트 구조** | 프로젝트 루트의 `crew.jsonc`와 `agents/` | `crews/` 폴더가 있는 `src/project_name/` |
+| **메인 로직 위치** | `crew.jsonc` (클래식: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow 클래스) |
+| **진입점 함수** | `crew.jsonc`에서 로드됨 (클래식: `main.py`의 `run()`) | `main.py`의 `kickoff()` |
 | **pyproject.toml 타입** | `type = "crew"` | `type = "flow"` |
 | **CLI 생성 명령어** | `crewai create crew name` | `crewai create flow name` |
-| **설정 위치** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` |
+| **설정 위치** | `crew.jsonc`, `agents/`, 선택적 `tools/` | `src/project_name/crews/crew_name/config/` 또는 포함된 JSON crew 폴더 |
 | **다른 crew 포함 가능** | 아니오 | 예 (`crews/` 폴더 내) |
 
 ## 프로젝트 구조 참조
 
 ### Crew 프로젝트 구조
 
-`crewai create crew my_crew`를 실행하면 다음 구조를 얻습니다:
+`crewai create crew my_crew`를 실행하면 JSON-first 구조를 얻습니다:
 
 ```
 my_crew/
@@ -54,24 +54,25 @@ my_crew/
 ├── README.md
 ├── .env
 ├── uv.lock                  # 배포에 필수
-└── src/
-    └── my_crew/
-        ├── __init__.py
-        ├── main.py          # run() 함수가 있는 진입점
-        ├── crew.py          # @CrewBase 데코레이터가 있는 Crew 클래스
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml  # 에이전트 정의
-            └── tasks.yaml   # 작업 정의
+├── crew.jsonc               # Crew 설정, 태스크, 프로세스, 입력
+├── agents/
+│   └── researcher.jsonc     # 에이전트 정의
+├── tools/                   # 선택적 custom:<name> 도구
+├── knowledge/
+└── skills/
 ```
 
 <Warning>
-  중첩된 `src/project_name/` 구조는 Crews에 매우 중요합니다.
-  잘못된 레벨에 파일을 배치하면 배포 실패의 원인이 됩니다.
+  JSON-first crew에서는 `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, `skills/`를
+  프로젝트 루트에 두세요. 이를 `src/` 아래에 두면 `crewai run`과 배포 검증이 crew 정의를 찾지 못합니다.
 </Warning>
 
+<Info>
+  `crewai create crew my_crew --classic`으로 만든 클래식 프로젝트는 기존
+  `src/project_name/crew.py`, `src/project_name/config/agents.yaml`,
+  `src/project_name/config/tasks.yaml` 구조를 사용합니다. 이 구조는 decorator 기반 Python crew를 위해 계속 지원됩니다.
+</Info>
+
 ### Flow 프로젝트 구조
 
 `crewai create flow my_flow`를 실행하면 다음 구조를 얻습니다:
@@ -100,9 +101,9 @@ my_flow/
 ```
 
 <Info>
-  Crews와 Flows 모두 `src/project_name/` 구조를 사용합니다.
-  핵심 차이점은 Flows는 포함된 crews를 위한 `crews/` 폴더가 있고,
-  Crews는 프로젝트 폴더에 직접 `crew.py`가 있다는 것입니다.
+  JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다.
+  Flow는 여전히 `src/project_name/`을 사용하며, 클래식 포함 crew나
+  `crewai.project.load_crew`로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다.
 </Info>
 
 ## 배포 전 체크리스트
@@ -154,60 +155,88 @@ git commit -m "Add uv.lock for deployment"
 git push
 ```
 
-### 3. CrewBase 데코레이터 사용 확인
+### 3. Crew 정의 검증
 
-**모든 crew 클래스는 `@CrewBase` 데코레이터를 사용해야 합니다.** 이것은 다음에 적용됩니다:
+<Tabs>
+  <Tab title="JSON-first Crews">
+    JSON-first crew는 프로젝트 루트에 `crew.jsonc` 또는 `crew.json` 파일이 있어야 합니다.
+    `agents` 배열은 `agents/` 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.
 
-- 독립 실행형 crew 프로젝트
-- Flow 프로젝트 내에 포함된 crews
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "Research {topic}.",
+          "expected_output": "A concise report.",
+          "agent": "researcher"
+        }
+      ],
+      "inputs": {
+        "topic": "AI Agents"
+      }
+    }
+    ```
 
-```python
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+    커스텀 도구는 `"custom:<name>"`으로 참조하며, `tools/<name>.py`에 `BaseTool` 서브클래스로 구현해야 합니다.
+  </Tab>
+  <Tab title="클래식 Python/YAML Crews">
+    클래식 crew와 Flow 안에 포함된 Python crew는 `@CrewBase` 데코레이터를 사용해야 합니다.
 
-@CrewBase  # 이 데코레이터는 필수입니다
-class MyCrew():
-    """내 crew 설명"""
+    ```python
+    from crewai import Agent, Crew, Process, Task
+    from crewai.project import CrewBase, agent, crew, task
+    from crewai.agents.agent_builder.base_agent import BaseAgent
+    from typing import List
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
+    @CrewBase
+    class MyCrew():
+        """내 crew 설명"""
 
-    @agent
-    def my_agent(self) -> Agent:
-        return Agent(
-            config=self.agents_config['my_agent'],  # type: ignore[index]
-            verbose=True
-        )
+        agents: List[BaseAgent]
+        tasks: List[Task]
 
-    @task
-    def my_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['my_task']  # type: ignore[index]
-        )
+        @agent
+        def my_agent(self) -> Agent:
+            return Agent(
+                config=self.agents_config['my_agent'],  # type: ignore[index]
+                verbose=True
+            )
 
-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
+        @task
+        def my_task(self) -> Task:
+            return Task(
+                config=self.tasks_config['my_task']  # type: ignore[index]
+            )
 
-<Warning>
-  `@CrewBase` 데코레이터를 잊으면 에이전트나 작업 구성이 누락되었다는
-  오류와 함께 배포가 실패합니다.
-</Warning>
+        @crew
+        def crew(self) -> Crew:
+            return Crew(
+                agents=self.agents,
+                tasks=self.tasks,
+                process=Process.sequential,
+                verbose=True,
+            )
+    ```
+  </Tab>
+</Tabs>
 
 ### 4. 프로젝트 진입점 확인
 
-Crews와 Flows 모두 `src/project_name/main.py`에 진입점이 있습니다:
+JSON-first 독립 실행형 crew는 직접 작성한 `src/project_name/main.py`가 필요하지 않습니다.
+`crewai run`과 배포 패키징이 `crew.jsonc`를 직접 로드합니다. 클래식 crew와 Flow는 Python 진입점을 사용합니다:
 
 <Tabs>
-  <Tab title="Crews의 경우">
+  <Tab title="JSON-first Crews">
+    프로젝트 루트에서 로컬 실행합니다:
+
+    ```bash
+    crewai run
+    ```
+  </Tab>
+  <Tab title="클래식 Crews">
     진입점은 `run()` 함수를 사용합니다:
 
     ```python
@@ -278,16 +307,17 @@ grep -A2 "\[tool.crewai\]" pyproject.toml
 # 2. uv.lock 존재 확인
 ls -la uv.lock || echo "오류: uv.lock이 없습니다! 'uv lock'을 실행하세요"
 
-# 3. src/ 구조 존재 확인
-ls -la src/*/main.py 2>/dev/null || echo "src/에서 main.py를 찾을 수 없습니다"
+# 3. JSON-first crew의 경우 crew.jsonc와 agents/ 확인
+([ -f crew.jsonc ] || [ -f crew.json ]) || echo "crew.jsonc 또는 crew.json을 찾을 수 없습니다"
+test -d agents || echo "agents/ 디렉터리를 찾을 수 없습니다"
 
-# 4. Crews의 경우 - crew.py 존재 확인
+# 4. 클래식 Crews의 경우 - crew.py 존재 확인
 ls -la src/*/crew.py 2>/dev/null || echo "crew.py가 없습니다 (Crews에서 예상됨)"
 
 # 5. Flows의 경우 - crews/ 폴더 존재 확인
 ls -la src/*/crews/ 2>/dev/null || echo "crews/ 폴더가 없습니다 (Flows에서 예상됨)"
 
-# 6. CrewBase 사용 확인
+# 6. 클래식 Python crews의 경우 - CrewBase 사용 확인
 grep -r "@CrewBase" . --include="*.py"
 ```
 
@@ -297,8 +327,9 @@ grep -r "@CrewBase" . --include="*.py"
 |------|------|----------|
 | `uv.lock` 누락 | 의존성 해결 중 빌드 실패 | `uv lock` 실행 후 커밋 |
 | pyproject.toml의 잘못된 `type` | 빌드 성공하지만 런타임 실패 | 올바른 타입으로 변경 |
-| `@CrewBase` 데코레이터 누락 | "Config not found" 오류 | 모든 crew 클래스에 데코레이터 추가 |
-| `src/` 대신 루트에 파일 배치 | 진입점을 찾을 수 없음 | `src/project_name/`으로 이동 |
+| JSON-first crew에서 `crew.jsonc` 또는 `agents/` 누락 | Crew 정의를 찾을 수 없음 | `crew.jsonc`와 `agents/`를 프로젝트 루트에 둠 |
+| 클래식 crew에서 `@CrewBase` 데코레이터 누락 | "Config not found" 오류 | 모든 클래식 crew 클래스에 데코레이터 추가 |
+| 클래식 파일을 `src/` 대신 루트에 배치 | 진입점을 찾을 수 없음 | 클래식 Python 파일을 `src/project_name/`으로 이동 |
 | `run()` 또는 `kickoff()` 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 |
 
 ## 다음 단계

docs/ko/enterprise/integrations/databricks.mdx

@@ -0,0 +1,123 @@
+---
+title: Databricks 연동
+description: "Databricks 관리형 MCP 서버를 통해 CrewAI 에이전트를 Databricks Genie, SQL, Unity Catalog Functions, Vector Search에 연결하세요."
+icon: "layer-group"
+mode: "wide"
+---
+
+## 개요
+
+[Databricks 관리형 MCP 서버](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 통해 CrewAI 에이전트를 Databricks 워크스페이스에 직접 연결하세요. Databricks 연동을 사용하면 에이전트가 **Genie**로 자연어 질문을 하고, 거버넌스가 적용된 **SQL**을 실행하며, **Unity Catalog Functions**를 호출하고, **Vector Search**로 문서를 검색할 수 있습니다. 커넥터 코드를 작성하거나 호스팅할 필요가 없으며, 모든 호출에 Unity Catalog 권한이 적용됩니다.
+
+내부적으로 Databricks 연동은 CrewAI의 [커스텀 MCP 서버](/ko/enterprise/guides/custom-mcp-server) 지원을 감싼 관리형 래퍼입니다. Databricks는 각 기능을 개별 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트로 노출하며, CrewAI가 사용자를 대신해 안전하게 연결합니다. 각 서버를 개별적으로 추가하므로 크루에 필요한 기능만 정확히 활성화할 수 있습니다.
+
+## 주요 기능
+
+<CardGroup cols={2}>
+  <Card title="Genie" icon="comments">
+    [Genie](https://docs.databricks.com/aws/en/genie/)로 자연어 질문을 하고 데이터 기반의 근거 있는 답변을 받으세요. Genie는 Genie Spaces와 Unity Catalog를 조회하고 Databricks UI로 연결되는 링크를 제공합니다.
+  </Card>
+  <Card title="Databricks SQL" icon="database">
+    에이전트에서 직접 Databricks 웨어하우스에 거버넌스가 적용된 SQL을 실행하여 데이터를 조회, 변환하고 데이터 파이프라인을 작성하세요.
+  </Card>
+  <Card title="Unity Catalog Functions" icon="function">
+    [Unity Catalog 함수](https://docs.databricks.com/aws/en/udf/unity-catalog)를 호출하여 사전 정의된 SQL과 맞춤형 비즈니스 로직을 거버넌스가 적용된 재사용 가능한 도구로 실행하세요.
+  </Card>
+  <Card title="Vector Search" icon="magnifying-glass">
+    [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) 인덱스에서 의미 유사도를 사용해 RAG 및 지식 워크플로우에 필요한 관련 문서를 검색하세요.
+  </Card>
+</CardGroup>
+
+모든 서버는 Unity AI Gateway 뒤에서 실행되며 Unity Catalog 접근 제어를 적용하므로, 에이전트는 허용된 데이터와 도구만 볼 수 있습니다.
+
+## 사전 준비사항
+
+Databricks 연동을 사용하기 전에 다음을 준비해야 합니다:
+
+- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
+- 노출하려는 기능이 있는 Databricks 워크스페이스(Genie Spaces, SQL 웨어하우스, Unity Catalog 함수 또는 Vector Search 인덱스)
+- 기본 객체에 대한 적절한 [Unity Catalog 권한](https://docs.databricks.com/aws/en/data-governance/unity-catalog)
+- Databricks 워크스페이스 호스트명(예: `your-workspace.cloud.databricks.com`)
+
+## Databricks 관리형 MCP 서버
+
+Databricks는 각 기능마다 별도의 관리형 MCP 서버를 게시합니다. CrewAI는 이를 개별 연결로 노출하며, 각 연결은 워크스페이스 호스트와 관련 Unity Catalog 식별자로 구성됩니다. 엔드포인트는 다음 패턴을 따릅니다:
+
+| 서버 | 기능 | MCP URL 패턴 |
+|------|------|--------------|
+| **Genie** | Genie Space에 대한 자연어 Q&A | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
+| **Databricks SQL** | 웨어하우스에 SQL 실행 | `https://<workspace-hostname>/api/2.0/mcp/sql` |
+| **Unity Catalog Functions** | 등록된 UC 함수 실행 | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
+| **Vector Search** | Vector Search 인덱스 조회 | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
+
+<Note>
+이러한 URL을 직접 만들 필요는 없습니다. CrewAI는 연결을 구성할 때 입력한 워크스페이스 호스트와 식별자(Genie Space ID 또는 catalog/schema)로 각 엔드포인트를 생성합니다. 전체 사양과 최신 엔드포인트 세부 정보는 [Databricks 관리형 MCP 문서](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 참고하세요.
+</Note>
+
+## CrewAI AMP에서 Databricks 연결하기
+
+<Frame>
+    <img src="/images/enterprise/databricks-configure.png" alt="CrewAI AMP에서 Databricks 관리형 MCP 서버 구성" />
+</Frame>
+
+각 Databricks 기능(**Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, **Databricks Vector Search**)은 **Tools & Integrations** 페이지의 Databricks 그룹 아래에 별도의 MCP 서버로 표시됩니다. 필요한 것을 구성하세요:
+
+<Steps>
+    <Step title="Tools & Integrations 열기">
+        CrewAI AMP 왼쪽 사이드바에서 **Tools & Integrations**로 이동하여 Connections 목록에서 **Databricks** 그룹을 찾습니다. 그 아래에 Genie, SQL, Unity Catalog Functions, Vector Search 서버가 나열됩니다.
+    </Step>
+
+    <Step title="서버 구성하기">
+        활성화하려는 기능 옆의 **Configure**를 클릭하고 연결 세부 정보를 입력합니다:
+
+        - **Workspace Host** — Databricks 워크스페이스 호스트명(예: `my-workspace.cloud.databricks.com`).
+        - **Genie** — 조회할 **Genie Space ID**.
+        - **Unity Catalog Functions** — 함수가 포함된 **catalog**와 **schema**.
+        - **Vector Search** — 인덱스가 포함된 **catalog**와 **schema**.
+        - **Databricks SQL** — 추가 식별자가 필요 없으며, 쿼리는 워크스페이스의 SQL 웨어하우스에서 실행됩니다.
+    </Step>
+
+    <Step title="인증 방법 선택하기">
+        CrewAI가 Databricks에 인증하는 방법을 선택합니다. **OAuth**를 권장합니다.
+
+        - **Use OAuth** — OAuth 2.0으로 안전하게 연결합니다. 각 사용자가 개별적으로 인증하며, Databricks는 해당 기능(`genie`, `sql`, `unity-catalog` 또는 `vector-search`)으로 범위가 지정된 토큰을 발급합니다. CrewAI가 인증 흐름을 처리하고 토큰을 자동으로 갱신합니다.
+        - **Use personal access token** — [Databricks 개인 액세스 토큰](https://docs.databricks.com/aws/en/dev-tools/auth/pat)으로 인증합니다. 노출을 제한하려면 최소 권한 ID를 사용하세요.
+    </Step>
+
+    <Step title="인증하기">
+        인증을 완료합니다. 연결되면 해당 서버의 도구를 크루에서 사용할 수 있습니다. 활성화하려는 다른 Databricks 기능에 대해서도 반복합니다.
+    </Step>
+</Steps>
+
+<Tip>
+각 기능이 별도의 연결이므로 자유롭게 조합할 수 있습니다. 예를 들어 리서치 크루에는 Genie와 Vector Search를 활성화하고, 데이터 엔지니어링 크루에는 SQL과 Unity Catalog Functions를 사용하도록 할 수 있습니다. 가시성(Visibility) 설정으로 각 기능을 사용할 수 있는 팀원을 제어할 수 있습니다.
+</Tip>
+
+## 크루에서 Databricks 도구 사용하기
+
+연결되면 각 MCP 서버가 노출하는 도구가 **Tools & Integrations** 페이지의 기본 제공 연결과 함께 표시됩니다. 다음을 할 수 있습니다:
+
+- 다른 CrewAI 도구와 마찬가지로 크루의 에이전트에 **도구 할당**.
+- 각 연결을 사용할 수 있는 팀원을 제어하는 **가시성 관리**.
+- Connections 목록에서 언제든지 연결 **편집 또는 제거**.
+
+이제 에이전트는 Genie에 근거 있는 답변을 요청하고, 웨어하우스에 SQL을 실행하며, Unity Catalog 함수를 호출하고, Vector Search 인덱스를 검색할 수 있으며, 그 결과가 자동으로 추론에 반영됩니다.
+
+<Warning>
+Databricks는 Unity Catalog와 Unity AI Gateway를 통해 거버넌스를 적용합니다. 사용자는 워크스페이스 ID에 허용된 도구만 검색하고 호출할 수 있습니다. 도구 호출이 실패하면 연결하는 사용자(또는 토큰 ID)가 Genie Space, 웨어하우스, 함수 또는 인덱스에 필요한 Unity Catalog 권한을 가지고 있는지 확인하세요. 일부 Genie 및 SQL 쿼리는 비동기로 실행되어 결과를 반환하는 데 시간이 걸릴 수 있습니다.
+</Warning>
+
+## 더 알아보기
+
+<CardGroup cols={2}>
+  <Card title="Databricks 관리형 MCP 서버" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
+    관리형 Genie, SQL, Unity Catalog Functions, Vector Search MCP 서버에 대한 공식 Databricks 문서입니다.
+  </Card>
+  <Card title="CrewAI의 커스텀 MCP 서버" icon="plug" href="/ko/enterprise/guides/custom-mcp-server">
+    Databricks 연동의 기반이 되는, CrewAI가 모든 MCP 서버에 연결하는 방법을 알아보세요.
+  </Card>
+</CardGroup>
+
+<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
+  Databricks 연동 구성 또는 문제 해결에 대한 지원이 필요하면 지원팀에 문의하세요.
+</Card>

docs/ko/enterprise/integrations/snowflake.mdx

@@ -0,0 +1,134 @@
+---
+title: Snowflake 연동
+description: "Snowflake 관리형 MCP 서버를 통해 CrewAI 에이전트를 Snowflake Cortex Analyst, Cortex Search 및 SQL 실행에 연결합니다."
+icon: "snowflake"
+mode: "wide"
+---
+
+## 개요
+
+[Snowflake 관리형 MCP 서버](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)를 통해 CrewAI 에이전트를 Snowflake 데이터에 직접 연결하세요. Snowflake 연동을 사용하면 에이전트가 **Cortex Analyst**로 구조화된 데이터를 쿼리하고, **Cortex Search**로 비구조화된 데이터를 검색하며, 커넥터 코드를 작성하거나 호스팅할 필요 없이 웨어하우스에 대해 관리되는 SQL을 실행할 수 있습니다.
+
+내부적으로 Snowflake 연동은 CrewAI의 [Custom MCP Server](/ko/enterprise/guides/custom-mcp-server) 지원을 기반으로 하는 관리형 래퍼입니다. Snowflake는 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트를 통해 Cortex AI 기능을 노출하며, CrewAI가 이를 안전하게 연결합니다. Snowflake 측에서 노출하는 모든 도구 — Cortex Analyst, Cortex Search, SQL 실행, Cortex Agents 또는 사용자 정의 도구 — 가 크루에서 사용할 수 있게 됩니다.
+
+## 주요 기능
+
+<CardGroup cols={3}>
+  <Card title="Cortex Analyst" icon="chart-bar">
+    자연어로 질문하고 [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst)가 풍부한 시맨틱 모델을 사용하여 **구조화된** 데이터에 대해 SQL을 생성하고 실행하도록 합니다.
+  </Card>
+  <Card title="Cortex Search" icon="magnifying-glass">
+    Snowflake의 완전 관리형 검색 서비스인 [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview)를 사용하여 RAG 및 지식 워크플로우를 위한 관련 **비구조화된** 데이터를 검색합니다.
+  </Card>
+  <Card title="SQL 실행" icon="database">
+    구성 가능한 읽기 전용 모드, 타임아웃 및 웨어하우스 선택을 통해 Snowflake 웨어하우스에 대해 관리되는 SQL 쿼리를 직접 실행합니다.
+  </Card>
+</CardGroup>
+
+연동이 MCP 서버가 게시하는 도구를 노출하므로, **Cortex Agents** 및 **사용자 정의 도구**(사용자 정의 함수 및 저장 프로시저)도 CrewAI 에이전트에 노출할 수 있습니다.
+
+## 사전 준비 사항
+
+Snowflake 연동을 사용하기 전에 다음을 확인하십시오:
+
+- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정
+- Cortex AI 기능에 액세스할 수 있는 Snowflake 계정
+- 노출하려는 도구가 구성된 [Snowflake 관리형 MCP 서버](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
+- MCP 서버 및 기본 객체에 대한 적절한 Snowflake 권한(USAGE/SELECT)
+
+## Snowflake MCP 서버 설정
+
+Snowflake 관리형 MCP 서버는 Snowflake 계정 내에서 실행되며 CrewAI와 같은 외부 클라이언트에서 사용할 수 있는 도구를 정의합니다. [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) 명령을 사용하여 노출하려는 Cortex Search 서비스, Cortex Analyst 시맨틱 뷰 및 SQL 도구를 나열하여 생성합니다.
+
+```sql
+CREATE MCP SERVER my_mcp_server
+  FROM SPECIFICATION $$
+    tools:
+      - name: "sales_analyst"
+        type: "CORTEX_ANALYST"
+        identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view"
+        description: "Answer questions about sales metrics"
+      - name: "docs_search"
+        type: "CORTEX_SEARCH_SERVICE_QUERY"
+        identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search"
+        description: "Search internal support documentation"
+      - name: "run_sql"
+        type: "SQL_EXECUTION"
+        description: "Execute read-only SQL queries"
+  $$;
+```
+
+<Note>
+MCP 엔드포인트는 `https://<account_URL>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}` 형식을 따릅니다. CrewAI는 연동 구성 시 제공하는 **계정 URL**, **데이터베이스**, **스키마** 및 **MCP 서버 이름**을 사용하여 이 URL을 자동으로 구성합니다.
+</Note>
+
+Cortex Agents, 사용자 정의 도구, 응답 크기 제한 및 거버넌스 옵션을 포함한 전체 사양은 [Snowflake 관리형 MCP 서버 문서](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)를 참조하세요.
+
+## CrewAI AMP에서 Snowflake 연결
+
+<Frame>
+    <img src="/images/enterprise/snowflake-configure.png" alt="CrewAI AMP에서 Snowflake 연동 구성" />
+</Frame>
+
+<Steps>
+    <Step title="도구 및 연동 열기">
+        CrewAI AMP 왼쪽 사이드바에서 **도구 및 연동**으로 이동하고, 애플리케이션 목록에서 **Snowflake**를 찾아 구성 패널을 엽니다.
+    </Step>
+
+    <Step title="연결 세부 정보 제공">
+        CrewAI가 Snowflake MCP 서버에 연결하는 데 사용하는 연결 필드를 채웁니다:
+
+        | 필드 | 필수 | 설명 |
+        |------|------|------|
+        | **이름** | 예 | 이 연결의 설명적 이름(기본값: `Snowflake`). |
+        | **설명** | 아니오 | 이 연결이 제공하는 내용에 대한 선택적 요약. |
+        | **계정 URL** | 예 | Snowflake 계정 URL, 예: `xy12345.us-east-1.snowflakecomputing.com`. |
+        | **데이터베이스** | 예 | MCP 서버가 포함된 데이터베이스(예: `MY_DATABASE`). |
+        | **스키마** | 예 | MCP 서버가 포함된 스키마(예: `MY_SCHEMA`). |
+        | **MCP 서버 이름** | 예 | Snowflake에서 생성한 MCP 서버 객체의 이름(예: `MY_MCP_SERVER`). |
+    </Step>
+
+    <Step title="인증 방법 선택">
+        CrewAI가 Snowflake에 인증하는 방법을 선택합니다. **OAuth**가 권장됩니다.
+
+        - **OAuth 사용** — 자격 증명을 공유하지 않고 토큰 기반 인증을 위해 OAuth 2.0을 사용하여 안전하게 연결합니다. CrewAI가 전체 인증 흐름을 처리하고 자동으로 토큰을 갱신합니다. 양식에 표시된 **리디렉트 URI**(`https://oauth.crewai.com/oauth/add`)를 복사하여 Snowflake [OAuth 보안 연동](https://docs.snowflake.com/en/user-guide/oauth-custom)에 인증된 리디렉트 URI로 등록하세요.
+        - **개인 액세스 토큰 사용** — Snowflake 계정 설정에서 생성한 [프로그래밍 방식 액세스 토큰](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens)을 사용하여 인증합니다. 노출을 제한하기 위해 토큰에 최소 권한 역할을 할당하세요.
+    </Step>
+
+    <Step title="인증">
+        **인증**을 클릭합니다. OAuth의 경우 Snowflake로 리디렉션되어 액세스를 승인합니다. 인증되면 Snowflake 서버가 연결 목록에 나타나고 해당 도구를 크루에서 사용할 수 있게 됩니다.
+    </Step>
+</Steps>
+
+<Tip>
+OAuth를 사용하면 각 사용자가 개별적으로 인증하며 쿼리는 해당 Snowflake `DEFAULT_ROLE`로 실행됩니다. 연결하는 사용자에게 기본 역할과 웨어하우스가 설정되어 있는지 확인하세요(`ALTER USER <username> SET DEFAULT_ROLE = '<role>' DEFAULT_WAREHOUSE = '<warehouse>'`). 그래야 Cortex Analyst 및 SQL 도구에 실행할 컴퓨팅이 있습니다.
+</Tip>
+
+## 크루에서 Snowflake 도구 사용
+
+연결되면 MCP 서버가 노출하는 도구가 **도구 및 연동** 페이지에서 기본 연결과 함께 표시됩니다. 다음을 수행할 수 있습니다:
+
+- 다른 CrewAI 도구처럼 크루의 **에이전트에 도구를 할당**합니다.
+- **가시성을 관리**하여 어떤 팀원이 연결을 사용할 수 있는지 제어합니다.
+- 연결 목록에서 언제든지 연결을 **편집하거나 제거**합니다.
+
+이제 에이전트가 Cortex Analyst에 메트릭을 요청하고, 문서에 대해 Cortex Search를 실행하고, SQL을 실행할 수 있으며 — 결과가 자동으로 추론에 반영됩니다.
+
+<Warning>
+Snowflake는 MCP 서버에 거버넌스를 적용합니다: 역할 기반 액세스 제어가 사용자가 발견하고 호출할 수 있는 도구를 결정하며, 응답 크기, 도구 수(서버당 최대 50개) 및 재귀 깊이에 제한이 적용됩니다. 도구 호출이 실패하면 연결하는 사용자의 역할에 MCP 서버 및 기본 객체에 대한 필수 권한이 있는지 확인하세요.
+</Warning>
+
+## 자세히 알아보기
+
+<CardGroup cols={2}>
+  <Card title="Snowflake 관리형 MCP 서버" icon="snowflake" href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp">
+    MCP 서버를 생성하고 관리하기 위한 공식 Snowflake 문서.
+  </Card>
+  <Card title="CrewAI의 Custom MCP 서버" icon="plug" href="/ko/enterprise/guides/custom-mcp-server">
+    CrewAI가 모든 MCP 서버에 연결하는 방법을 알아보세요. Snowflake 연동이 기반으로 하는 기초입니다.
+  </Card>
+</CardGroup>
+
+<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
+  Snowflake 연동 또는 문제 해결에 대해 지원팀에 문의하세요.
+</Card>

docs/ko/guides/advanced/customizing-prompts.mdx

@@ -161,6 +161,18 @@ crew = Crew(
 )
 ```
 
+<Note>
+`agent.i18n`은 이전 버전과의 호환성을 위해서만 유지되며 사용이 중단될 예정입니다. 런타임 프롬프트 커스터마이징에는 `Crew`에 `prompt_file`을 전달하세요. 프롬프트 슬라이스를 코드에서 직접 읽어야 한다면 i18n 유틸리티를 직접 사용하세요:
+</Note>
+
+```python
+from crewai.utilities.i18n import get_i18n
+
+i18n = get_i18n("custom_prompts.json")
+format_slice = i18n.slice("format")
+tool_prompt = i18n.tools("ask_question")
+```
+
 #### 옵션 3: o1 모델에 대한 시스템 프롬프트 비활성화
 ```python
 agent = Agent(
@@ -208,6 +220,8 @@ agent = Agent(
 
 그러면 CrewAI가 기본값과 사용자가 지정한 내용을 병합하므로, 모든 프롬프트를 다시 정의할 필요가 없습니다. 방법은 다음과 같습니다:
 
+프롬프트 슬라이스를 코드에서 직접 읽어야 하는 경우에는 `agent.i18n`을 읽는 대신 동일한 프롬프트 파일로 `crewai.utilities.i18n.get_i18n()`을 사용하세요.
+
 ### 예시: 기본 프롬프트 커스터마이징
 
 수정하고 싶은 프롬프트를 포함하는 `custom_prompts.json` 파일을 생성하세요. 변경 사항만이 아니라 포함해야 하는 모든 최상위 프롬프트를 반드시 나열해야 합니다:
@@ -314,4 +328,4 @@ CrewAI에서의 저수준 prompt 커스터마이제이션은 매우 맞춤화되
 
 <Check>
 이제 CrewAI에서 고급 prompt 커스터마이징을 위한 기초를 갖추었습니다. 모델별 구조나 도메인별 제약에 맞춰 적용하든, 이러한 저수준 접근 방식은 agent 상호작용을 매우 전문적으로 조정할 수 있게 해줍니다.
-</Check>
+</Check>

docs/ko/guides/coding-tools/build-with-ai.mdx

@@ -43,7 +43,7 @@ CrewAI는 AI 네이티브입니다. 이 페이지는 Claude Code, Codex, Cursor,
 
     | 스킬 | 실행 시점 |
     |------|-------------|
-    | `getting-started` | 새 프로젝트 스캐폴딩, `LLM.call()` / `Agent` / `Crew` / `Flow` 선택, `crew.py` / `main.py` 연결 |
+    | `getting-started` | 새 프로젝트 스캐폴딩, `LLM.call()` / `Agent` / `Crew` / `Flow` 선택, `crew.jsonc` / `main.py` 연결 |
     | `design-agent` | 에이전트 구성 — 역할, 목표, 배경 이야기, 도구, LLM, 메모리, 가드레일 |
     | `design-task` | 태스크 설명, 의존성, 구조화된 출력(`output_pydantic`, `output_json`), 사람 검토 |
     | `ask-docs` | 최신 API 정보를 위해 [CrewAI 문서 MCP 서버](https://docs.crewai.com/mcp) 조회 |
@@ -64,7 +64,7 @@ CrewAI는 AI 네이티브입니다. 이 페이지는 Claude Code, Codex, Cursor,
   <Step title="에이전트가 즉시 CrewAI 전문성을 갖춤">
     스킬 팩이 에이전트에게 알려 주는 내용:
     - **Flow** — 상태ful 앱, 단계, crew 킥오프
-    - **Crew 및 에이전트** — YAML 우선 패턴, 역할, 태스크, 위임
+    - **Crew 및 에이전트** — JSON-first 패턴(`crew.jsonc`, `agents/*.jsonc`), 역할, 태스크, 위임
     - **도구 및 통합** — 검색, API, MCP 서버, 일반적인 CrewAI 도구
     - **프로젝트 레이아웃** — CLI 스캐폴드와 저장소 관례
     - **최신 패턴** — 현재 CrewAI 문서와 모범 사례 반영

docs/ko/guides/crews/first-crew.mdx

@@ -1,392 +1,140 @@
 ---
-title: 첫 번째 크루 만들기
-description: 복잡한 문제를 함께 해결할 수 있는 협업 AI 팀을 만드는 단계별 튜토리얼입니다.
+title: 첫 번째 Crew 만들기
+description: JSON-first crew 설정으로 협업 AI 팀을 만드는 단계별 튜토리얼입니다.
 icon: users-gear
 mode: "wide"
 ---
 
-## 협업 AI의 힘을 발휘하기
+## 리서치 Crew 만들기
 
-여러 AI 에이전트가 각자의 전문성을 바탕으로 원활하게 협력하며 복잡한 문제를 해결한다고 상상해 보세요. 각자 고유한 기술을 발휘해 공동의 목표를 달성합니다. 이것이 바로 CrewAI의 힘입니다. CrewAI 프레임워크를 통해 단일 AI로는 달성할 수 없는 과업을 협업 AI 시스템으로 실현할 수 있습니다.
+이 가이드에서는 두 에이전트가 주제를 조사하고 markdown 보고서를 작성하는 crew를 만듭니다. 새 crew 프로젝트는 JSON-first입니다. 에이전트는 `agents/*.jsonc`, 태스크와 crew 설정은 `crew.jsonc`에 두며, `crewai run`이 이 정의를 직접 로드합니다.
 
-이 가이드에서는 연구 크루를 만들어 주제를 조사 및 분석하고, 종합적인 보고서를 작성하는 과정을 안내합니다. 이 실용적인 예시는 AI 에이전트들이 어떻게 협력하여 복잡한 작업을 수행할 수 있는지 보여 주지만, CrewAI로 실현할 수 있는 가능성의 시작에 불과합니다.
+### 준비 사항
 
-### 무엇을 만들고 배우게 될까요
+1. [설치 가이드](/ko/installation)에 따라 CrewAI 설치
+2. [LLM 설정](/ko/concepts/llms#setting-up-your-llm)에 따라 모델 API 키 설정
+3. 웹 검색을 사용할 경우 [Serper.dev](https://serper.dev/) API 키 준비
 
-이 가이드를 마치면 다음을 할 수 있게 됩니다:
-
-1. **특화된 AI 연구팀 조직**: 각기 다른 역할과 책임을 가진 연구팀을 만듭니다
-2. **여러 AI 에이전트 간의 협업 조율**
-3. **정보 수집, 분석, 보고서 생성을 포함한 복잡한 workflow 자동화**
-4. **더 야심찬 프로젝트에도 적용할 수 있는 기초 역량 구축**
-
-이 가이드에서는 간단한 research crew를 만들지만, 동일한 패턴과 기법을 활용하여 다음과 같은 훨씬 더 정교한 팀도 만들 수 있습니다:
-
-- 전문 writer, editor, fact-checker가 참여하는 다단계 콘텐츠 생성
-- 단계별 지원 에이전트가 있는 복잡한 고객 서비스 시스템
-- 데이터 수집, 시각화, 인사이트 생성까지 하는 자율 business analyst
-- 아이디어 구상, 디자인, 구현 계획까지 진행하는 product development 팀
-
-이제 여러분의 첫 crew를 만들어 봅시다!
-
-### 필수 조건
-
-시작하기 전에 다음을 확인하세요:
-
-1. [설치 가이드](/ko/installation)를 참고하여 CrewAI를 설치했는지 확인하세요.
-2. [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하여 환경에 LLM API 키를 설정했는지 확인하세요.
-3. Python에 대한 기본적인 이해
-
-## 1단계: 새로운 CrewAI 프로젝트 생성
-
-먼저, CLI를 사용하여 새로운 CrewAI 프로젝트를 생성해봅시다. 이 명령어는 필요한 모든 파일을 포함한 전체 프로젝트 구조를 설정해 주어, 보일러플레이트 코드를 설정하는 대신 에이전트와 그들의 작업 정의에 집중할 수 있습니다.
+## 1단계: 새 Crew 만들기
 
 ```bash
 crewai create crew research_crew
 cd research_crew
 ```
 
-이렇게 하면 crew에 필요한 기본 구조를 갖춘 프로젝트가 생성됩니다. CLI는 다음을 자동으로 생성합니다:
+생성되는 구조:
 
-- 필요한 파일이 포함된 프로젝트 디렉터리
-- 에이전트와 작업에 대한 구성 파일
-- 기본 crew 구현
-- crew를 실행하는 메인 스크립트
-
-<Frame caption="CrewAI 프레임워크 개요">
-  <img src="/images/crews.png" alt="CrewAI Framework Overview" />
-</Frame>
-
-## 2단계: 프로젝트 구조 살펴보기
-
-CLI가 생성한 프로젝트 구조를 이해하는 시간을 가져봅시다. CrewAI는 Python 프로젝트의 모범 사례를 따르므로, crew가 더 복잡해질수록 코드를 쉽게 유지 관리하고 확장할 수 있습니다.
-
-```
+```text
 research_crew/
 ├── .gitignore
+├── .env
+├── agents/
+│   └── researcher.jsonc
+├── crew.jsonc
+├── knowledge/
 ├── pyproject.toml
 ├── README.md
-├── .env
-└── src/
-    └── research_crew/
-        ├── __init__.py
-        ├── main.py
-        ├── crew.py
-        ├── tools/
-        │   ├── custom_tool.py
-        │   └── __init__.py
-        └── config/
-            ├── agents.yaml
-            └── tasks.yaml
+├── skills/
+└── tools/
 ```
 
-이 구조는 Python 프로젝트의 모범 사례를 따르며, 코드를 체계적으로 구성할 수 있도록 해줍니다. 설정 파일(YAML)과 구현 코드(Python)의 분리로 인해, 기본 코드를 변경하지 않고도 crew의 동작을 쉽게 수정할 수 있습니다.
+<Tip>
+`crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 쓰는 기존 레이아웃이 필요하면 `crewai create crew research_crew --classic`을 사용하세요.
+</Tip>
 
-## 3단계: 에이전트 구성하기
+## 2단계: 에이전트 정의
 
-이제 재미있는 단계가 시작됩니다 - 여러분의 AI 에이전트를 정의하는 것입니다! CrewAI에서 에이전트는 특정 역할, 목표 및 배경을 가진 전문화된 엔터티로, 이들이 어떻게 행동할지를 결정합니다. 각각 고유한 성격과 목적을 지닌 연극의 등장인물로 생각하면 됩니다.
+생성된 `agents/researcher.jsonc` 파일을 교체하고 `agents/analyst.jsonc`를 추가합니다. 파일 이름이 `crew.jsonc`에서 참조하는 에이전트 이름입니다.
 
-우리의 리서치 crew를 위해 두 명의 에이전트를 만들겠습니다:
-1. 정보를 찾아 정리하는 데 뛰어난 **리서처**
-2. 연구 결과를 해석하고 통찰력 있는 보고서를 작성할 수 있는 **애널리스트**
-
-이러한 전문화된 에이전트를 정의하기 위해 `agents.yaml` 파일을 수정해봅시다. `llm` 항목은 사용 중인 제공업체에 맞게 설정하세요.
-
-```yaml
-# src/research_crew/config/agents.yaml
-researcher:
-  role: >
-    Senior Research Specialist for {topic}
-  goal: >
-    Find comprehensive and accurate information about {topic}
-    with a focus on recent developments and key insights
-  backstory: >
-    You are an experienced research specialist with a talent for
-    finding relevant information from various sources. You excel at
-    organizing information in a clear and structured manner, making
-    complex topics accessible to others.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
-
-analyst:
-  role: >
-    Data Analyst and Report Writer for {topic}
-  goal: >
-    Analyze research findings and create a comprehensive, well-structured
-    report that presents insights in a clear and engaging way
-  backstory: >
-    You are a skilled analyst with a background in data interpretation
-    and technical writing. You have a talent for identifying patterns
-    and extracting meaningful insights from research data, then
-    communicating those insights effectively through well-crafted reports.
-  llm: provider/model-id  # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
+```jsonc agents/researcher.jsonc
+{
+  "role": "Senior Research Specialist for {topic}",
+  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
+  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
+  // 사용하는 모델로 바꾸세요. 예: "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-각 에이전트가 고유한 역할, 목표, 그리고 배경을 가지고 있다는 점에 주목하세요. 이 요소들은 단순한 설명 그 이상으로, 실제로 에이전트가 자신의 과업을 어떻게 접근하는지에 적극적으로 영향을 미칩니다. 이러한 부분을 신중하게 설계함으로써 서로 보완하는 전문적인 역량과 관점을 가진 에이전트를 만들 수 있습니다.
-
-## 4단계: 작업 정의하기
-
-이제 agent들을 정의했으니, 이들에게 수행할 구체적인 작업을 지정해야 합니다. CrewAI의 작업(task)은 agent가 수행할 구체적인 업무를 나타내며, 자세한 지침과 예상 결과물이 포함됩니다.
-
-연구 crew를 위해 두 가지 주요 작업을 정의하겠습니다:
-1. 포괄적인 정보 수집을 위한 **연구 작업**
-2. 인사이트 있는 보고서 생성을 위한 **분석 작업**
-
-`tasks.yaml` 파일을 다음과 같이 수정해 보겠습니다:
-
-```yaml
-# src/research_crew/config/tasks.yaml
-research_task:
-  description: >
-    {topic}에 대해 철저한 연구를 수행하세요. 다음에 중점을 두세요:
-    1. 주요 개념 및 정의
-    2. 역사적 발전과 최근 동향
-    3. 주요 과제와 기회
-    4. 주목할 만한 적용 사례 또는 케이스 스터디
-    5. 향후 전망과 잠재적 발전
-
-    반드시 명확한 섹션으로 구성된 구조화된 형식으로 결과를 정리하세요.
-  expected_output: >
-    {topic}의 모든 요구 사항을 다루는, 잘 구성된 섹션이 포함된 포괄적인 연구 문서.
-    필요에 따라 구체적인 사실, 수치, 예시를 포함하세요.
-  agent: researcher
-
-analysis_task:
-  description: >
-    연구 결과를 분석하고 {topic}에 대한 포괄적인 보고서를 작성하세요.
-    보고서에는 다음 내용이 포함되어야 합니다:
-    1. 간결한 요약(executive summary)으로 시작
-    2. 연구의 모든 주요 정보 포함
-    3. 동향과 패턴에 대한 통찰력 있는 분석 제공
-    4. 추천사항 또는 미래 고려 사항 제시
-    5. 명확한 제목과 함께 전문적이고 읽기 쉬운 형식으로 작성
-
-  expected_output: >
-    연구 결과와 추가 분석, 인사이트를 포함한 {topic}에 대한 정제되고 전문적인 보고서.
-    보고서는 간결한 요약, 본문, 결론 등으로 잘 구조화되어 있어야 합니다.
-  agent: analyst
-  context:
-    - research_task
-  output_file: output/report.md
+```jsonc agents/analyst.jsonc
+{
+  "role": "Report Analyst for {topic}",
+  "goal": "Turn research findings into a clear, well-structured report.",
+  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
+  // 사용하는 모델로 바꾸세요. 예: "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
 ```
 
-분석 작업 내의 `context` 필드에 주목하세요. 이 강력한 기능을 통해 analyst가 연구 작업의 결과물을 참조할 수 있습니다. 이를 통해 정보가 human team에서처럼 agent 간에 자연스럽게 흐르는 워크플로우가 만들어집니다.
+`provider/model-id`를 `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, `gemini/gemini-2.0-flash-001` 같은 모델로 바꾸세요.
 
-## 5단계: 크루 구성 설정하기
+## 3단계: 태스크와 Crew 설정
 
-이제 크루를 구성하여 모든 것을 하나로 모을 시간입니다. 크루는 에이전트들이 함께 작업을 완료하는 방식을 조율하는 컨테이너 역할을 합니다.
+`crew.jsonc`를 다음으로 교체합니다:
 
-`crew.py` 파일을 다음과 같이 수정해보겠습니다:
-
-```python
-# src/research_crew/crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai_tools import SerperDevTool
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
-
-@CrewBase
-class ResearchCrew():
-    """Research crew for comprehensive topic analysis and reporting"""
-
-    agents: List[BaseAgent]
-    tasks: List[Task]
-
-    @agent
-    def researcher(self) -> Agent:
-        return Agent(
-            config=self.agents_config['researcher'], # type: ignore[index]
-            verbose=True,
-            tools=[SerperDevTool()]
-        )
-
-    @agent
-    def analyst(self) -> Agent:
-        return Agent(
-            config=self.agents_config['analyst'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def research_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['research_task'] # type: ignore[index]
-        )
-
-    @task
-    def analysis_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['analysis_task'], # type: ignore[index]
-            output_file='output/report.md'
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the research crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
-
-이 코드에서는 다음을 수행합니다:
-1. researcher 에이전트를 생성하고, SerperDevTool을 장착하여 웹 검색 기능을 추가합니다.
-2. analyst 에이전트를 생성합니다.
-3. research와 analysis 작업(task)을 설정합니다.
-4. 크루가 작업을 순차적으로 수행하도록 설정합니다(analyst가 researcher가 끝날 때까지 대기).
-
-여기서 마법이 일어납니다. 몇 줄의 코드만으로도, 특화된 에이전트들이 조율된 프로세스 내에서 협업하는 협동 AI 시스템을 정의할 수 있습니다.
-
-## 6단계: 메인 스크립트 설정
-
-이제 우리 crew를 실행할 메인 스크립트를 설정해 보겠습니다. 이곳에서 crew가 리서치할 구체적인 주제를 지정합니다.
-
-```python
-#!/usr/bin/env python
-# src/research_crew/main.py
-import os
-from research_crew.crew import ResearchCrew
-
-# Create output directory if it doesn't exist
-os.makedirs('output', exist_ok=True)
-
-def run():
-    """
-    Run the research crew.
-    """
-    inputs = {
-        'topic': 'Artificial Intelligence in Healthcare'
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
+      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis_task",
+      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
+      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
+      "agent": "analyst",
+      "context": ["research_task"],
+      "output_file": "output/report.md",
+      "markdown": true
     }
-
-    # Create and run the crew
-    result = ResearchCrew().crew().kickoff(inputs=inputs)
-
-    # Print the result
-    print("\n\n=== FINAL REPORT ===\n\n")
-    print(result.raw)
-
-    print("\n\nReport has been saved to output/report.md")
-
-if __name__ == "__main__":
-    run()
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "Artificial Intelligence in Healthcare"
+  }
+}
 ```
 
-이 스크립트는 환경을 준비하고, 리서치 주제를 지정하며, crew의 작업을 시작합니다. CrewAI의 강력함은 이 코드가 얼마나 간단한지에서 드러납니다. 여러 AI 에이전트를 관리하는 모든 복잡함이 프레임워크에 의해 처리됩니다.
+`context`는 이전 태스크 이름을 가리키므로 analyst가 research 태스크 출력을 받습니다. `inputs`는 `{topic}`의 기본값을 제공합니다. 기본값이 없으면 `crewai run`이 실행 중에 물어봅니다.
 
-## 7단계: 환경 변수 설정하기
+## 4단계: 환경 변수 설정
 
-프로젝트 루트에 `.env` 파일을 생성하고 API 키를 입력하세요:
+`.env`를 편집합니다:
 
 ```sh
 SERPER_API_KEY=your_serper_api_key
-# Add your provider's API key here too.
+# 모델 제공자 API 키도 추가하세요.
 ```
 
-선택한 provider를 구성하는 방법에 대한 자세한 내용은 [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요. Serper API 키는 [Serper.dev](https://serper.dev/)에서 받을 수 있습니다.
-
-## 8단계: 필수 종속성 설치
-
-CrewAI CLI를 사용하여 필요한 종속성을 설치하세요:
+## 5단계: 설치 및 실행
 
 ```bash
 crewai install
-```
-
-이 명령어는 다음을 수행합니다:
-1. 프로젝트 구성에서 종속성을 읽어옵니다
-2. 필요하다면 가상 환경을 생성합니다
-3. 모든 필수 패키지를 설치합니다
-
-## 9단계: Crew 실행하기
-
-이제 흥미로운 순간입니다 - crew를 실행하여 AI 협업이 어떻게 이루어지는지 직접 확인해보세요!
-
-```bash
 crewai run
 ```
 
-이 명령어를 실행하면 crew가 즉시 작동하는 모습을 볼 수 있습니다. researcher는 지정된 주제에 대한 정보를 수집하고, analyst가 그 연구를 바탕으로 종합 보고서를 작성합니다. 에이전트들의 사고 과정, 행동, 결과물이 실시간으로 표시되며 서로 협력하여 작업을 완수하는 모습을 확인할 수 있습니다.
+실행이 끝나면 `output/report.md`를 확인하세요.
 
-## 10단계: 결과물 검토
-
-crew가 작업을 완료하면, 최종 보고서는 `output/report.md` 파일에서 확인할 수 있습니다. 보고서에는 다음과 같은 내용이 포함됩니다:
-
-1. 요약 보고서
-2. 주제에 대한 상세 정보
-3. 분석 및 인사이트
-4. 권장사항 또는 향후 고려사항
-
-지금까지 달성한 것을 잠시 돌아보세요. 여러분은 여러 AI 에이전트가 협업하여 각자의 전문적인 기술을 발휘함으로써, 단일 에이전트가 혼자서 이루어낼 수 있는 것보다 더 뛰어난 결과를 만들어내는 시스템을 구축한 것입니다.
-
-## 기타 CLI 명령어 탐색
-
-CrewAI는 crew 작업을 위한 몇 가지 유용한 CLI 명령어를 추가로 제공합니다:
-
-```bash
-# 모든 사용 가능한 명령어 보기
-crewai --help
-
-# crew 실행
-crewai run
-
-# crew 테스트
-crewai test
-
-# crew 메모리 초기화
-crewai reset-memories
-
-# 특정 task에서 재실행
-crewai replay -t <task_id>
-```
-
-## 가능한 것의 예술: 당신의 첫 crew를 넘어서
-
-이 가이드에서 구축한 것은 시작에 불과합니다. 여러분이 배운 기술과 패턴은 점점 더 정교한 AI 시스템을 만드는 데 적용할 수 있습니다. 다음은 이 기본 research crew를 확장할 수 있는 몇 가지 방법입니다:
-
-### 팀원 확장하기
-
-더 전문화된 에이전트를 팀원으로 추가할 수 있습니다:
-- 연구 결과를 검증하는 **팩트체커**
-- 차트와 그래프를 만드는 **데이터 시각화 담당자**
-- 특정 분야에 전문 지식을 가진 **도메인 전문가**
-- 분석의 약점을 파악하는 **비평가**
-
-### 도구 및 기능 추가
-
-에이전트에 추가 도구를 통해 기능을 확장할 수 있습니다:
-- 실시간 연구를 위한 웹 브라우징 도구
-- 데이터 분석을 위한 CSV/데이터베이스 도구
-- 데이터 처리를 위한 코드 실행 도구
-- 외부 서비스와의 API 연결
-
-### 더 복잡한 워크플로우 생성
-
-더 정교한 프로세스를 구현할 수 있습니다:
-- 매니저 에이전트가 워커 에이전트에게 위임하는 계층적 프로세스
-- 반복적 피드백 루프로 정제하는 반복 프로세스
-- 여러 에이전트가 동시에 작업하는 병렬 프로세스
-- 중간 결과에 따라 적응하는 동적 프로세스
-
-### 다양한 도메인에 적용하기
-
-동일한 패턴은 다음과 같은 분야에서 crew를 구성하는 데 적용할 수 있습니다:
-- **콘텐츠 제작**: 작가, 에디터, 팩트체커, 디자이너가 함께 협업
-- **고객 서비스**: 분류 담당자, 전문가, 품질 관리자가 함께 협업
-- **제품 개발**: 연구원, 디자이너, 기획자가 협업
-- **데이터 분석**: 데이터 수집가, 분석가, 시각화 전문가
-
-## 다음 단계
-
-이제 첫 crew를 구축했으니, 다음과 같은 작업을 시도해 볼 수 있습니다:
-
-1. 다양한 에이전트 구성 및 성격을 실험해 보세요
-2. 더 복잡한 작업 구조와 워크플로우를 시도해 보세요
-3. 맞춤 도구를 구현하여 에이전트에게 새로운 기능을 제공하세요
-4. crew를 다양한 주제나 문제 도메인에 적용해 보세요
-5. [CrewAI Flows](/ko/guides/flows/first-flow)를 탐색하여 절차적 프로그래밍을 활용한 더 고급 워크플로우를 경험해 보세요
+<Warning>
+신뢰하는 출처의 JSON crew 프로젝트만 실행하세요. `custom:<name>` 도구와 `{"python": "module.attribute"}` 참조는 crew 로드 시 로컬 Python 코드를 실행합니다.
+</Warning>
 
 <Check>
-축하합니다! 이제 주어진 모든 주제를 조사하고 분석할 수 있는 첫 번째 CrewAI crew를 성공적으로 구축하셨습니다. 이 기본적인 경험은 협업 인텔리전스를 통해 복잡하고 다단계의 문제를 해결할 수 있는 점점 더 정교한 AI 시스템을 제작하는 데 필요한 역량을 갖추는 데 도움이 됩니다.
-</Check>
+주제를 조사하고 보고서를 작성하는 JSON-first crew를 만들었습니다.
+</Check>

docs/ko/guides/flows/conversational-flows.mdx

@@ -0,0 +1,474 @@
+---
+title: 대화형 Flow
+description: 턴마다 kickoff, 메시지 기록, 의도 라우팅, 트레이싱, WebSocket 브리지로 멀티턴 채팅 앱을 만듭니다.
+icon: comments
+mode: "wide"
+---
+
+## 개요
+
+대화형 앱은 각 사용자 입력을 **동일한 세션 id**로 **새 flow 실행**으로 처리합니다. CrewAI는 메시지 기록, 선택적 의도 분류, 지연 트레이싱, UI 브리지, 그리고 대화형 flow용 로컬 `flow.chat()` REPL을 제공합니다.
+
+| 개념 | 구현 |
+|------|------|
+| 세션 id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
+| 사용자 입력 | `handle_turn(message)`가 그래프 실행 전 `state.messages`에 추가 |
+| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `handle_turn`로 대화 계속 |
+| 세션 전체 트레이스 | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+
+## 턴 API
+
+REST, WebSocket, 테스트, 커스텀 UI에서 오는 모든 사용자 메시지에는 **`flow.handle_turn(message, session_id=...)`**를 사용하세요. 대화형 `Flow`를 로컬 터미널 채팅 루프로 실행하고 싶을 때는 **`flow.chat()`**을 사용하세요.
+
+`Flow.kickoff()`는 `user_message=` 또는 `session_id=` 키워드 인자를 받지 않습니다. 대화형 flow에서는 `handle_turn()`이 보류 중인 메시지를 저장하고 내부적으로 `kickoff(inputs={"id": session_id})`를 호출합니다.
+
+| API | 용도 |
+|-----|------|
+| `handle_turn(message, session_id=...)` | 대화형 `Flow`용 한 턴 편의 래퍼 |
+| `chat()` | 대화형 `Flow`용 로컬 터미널 REPL |
+| `kickoff(inputs={...})` | 대화형 턴 처리 없이 flow를 직접 실행 |
+| `ask()` | 한 스텝 **내부** 블로킹 프롬프트 (마법사, 확인) |
+| `@human_feedback` | **스텝 출력** 승인/거부 — 다음 채팅 줄이 아님 |
+| `ChatSession.handle_turn(...)` | `handle_turn` 위의 전송 계층 (SSE / WebSocket) |
+
+## 빠른 시작
+
+```python
+from uuid import uuid4
+
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context):
+        message = self.state.current_user_message or ""
+        if "주문" in message or "order" in message.lower():
+            return "order"
+        if "안녕" in message or "goodbye" in message.lower():
+            return "goodbye"
+        return "help"
+
+    @listen("order")
+    def handle_order(self):
+        reply = "주문이 배송 중입니다."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("help")
+    def handle_help(self):
+        reply = "무엇을 도와드릴까요?"
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("goodbye")
+    def handle_goodbye(self):
+        reply = "안녕히 가세요!"
+        self.append_assistant_message(reply)
+        return reply
+
+
+session_id = str(uuid4())
+flow = SupportFlow()
+
+try:
+    flow.handle_turn("주문 어디까지 왔나요?", session_id=session_id)
+    flow.handle_turn("반품은 어떻게 하나요?", session_id=session_id)
+finally:
+    flow.finalize_session_traces()  # 전체 대화에 대한 단일 trace 링크
+```
+
+## 턴 생명주기
+
+각 `handle_turn`은 다음 파이프라인을 실행합니다:
+
+1. **`_configure_conversational_kickoff`** — `session_id` / `user_message`를 `inputs`에 병합, `ConversationalConfig` 적용, 설정 시 지연 트레이싱 활성화.
+2. **상태 복원** — `inputs["id"]`가 있고 `@persist`가 설정되면 최신 스냅샷 로드.
+3. **`FlowStarted`** — 지연 세션의 첫 턴에서만 발생.
+4. **`prepare_conversational_turn`** — 사용자 메시지를 `state.messages`에 추가, `last_user_message` 설정, `last_intent` 초기화, `intents` / `default_intents` + `intent_llm` 설정 시 분류.
+5. **그래프 실행** — `@start` → `@router` → `@listen` 핸들러.
+6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음.
+
+핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.
+
+## `ConversationalConfig` (클래스 수준 기본값)
+
+`Flow` 서브클래스에 `conversational_config: ClassVar[ConversationalConfig | None]`로 설정합니다.
+
+| 필드 | 기본값 | 목적 |
+|------|--------|------|
+| `default_intents` | `None` | kickoff 전 자동 분류용 outcome 라벨 |
+| `intent_llm` | `None` | 분류용 모델 (intent 사용 시 필수) |
+| `interactive_prompt` | `"You: "` | `kickoff(interactive=True)` 프롬프트 |
+| `interactive_timeout` | `None` | 대화형 모드 줄 단위 타임아웃 |
+| `exit_commands` | `exit`, `quit` | 대화형 모드 종료 단어 |
+| `defer_trace_finalization` | `True` | 턴 간 하나의 trace batch 유지 |
+
+`intents=` 및 `intent_llm=` 키워드로 kickoff마다 재정의할 수 있습니다.
+
+## `ChatState` (권장 persist 형태)
+
+```python
+from crewai.flow import ChatState
+
+
+class MyChatState(ChatState):
+    # 상속: id, messages, last_user_message, last_intent, session_ready
+    research_turn_count: int = 0
+    custom_flag: bool = False
+```
+
+| 필드 | 역할 |
+|------|------|
+| `id` | 세션 UUID (`session_id` / `inputs["id"]`와 동일) |
+| `messages` | LLM 기록용 `{role, content}` 리스트 |
+| `last_user_message` | 이번 턴의 최신 사용자 입력 |
+| `last_intent` | 분류 후 라우트 라벨 (사용 시) |
+| `session_ready` | 일회성 bootstrap 플래그 |
+
+`ConversationalInputs`는 `kickoff(inputs={...})`용 `TypedDict`: `id`, `user_message`, `last_intent`.
+
+## `Flow` 대화 API
+
+### `kickoff` / `kickoff_async` 파라미터
+
+| 파라미터 | 목적 |
+|----------|------|
+| `user_message` | 이번 턴 텍스트 (또는 `{"role": "user", "content": "..."}`) |
+| `session_id` | 대화 UUID → `inputs["id"]` / `state.id` |
+| `intents` | kickoff 전 `classify_intent`용 outcome 라벨 |
+| `intent_llm` | 분류 LLM (`intents`와 함께 필수) |
+| `interactive` | `ask()` CLI 루프 (로컬 데모 전용) |
+| `interactive_prompt` | 대화형 모드 프롬프트 |
+| `interactive_timeout` | 줄 단위 `ask()` 타임아웃 |
+| `exit_commands` | 대화형 모드 종료 단어 |
+| `inputs` | 추가 상태 필드 |
+| `restore_from_state_id` | 다른 persist flow에서 fork 복원 |
+
+### 인스턴스 속성
+
+| 속성 | 목적 |
+|------|------|
+| `conversational_config` | 클래스 수준 `ConversationalConfig` |
+| `defer_trace_finalization` | 인스턴스 플래그; kickoff 시 config에서 자동 설정 |
+| `suppress_flow_events` | 콘솔 flow 패널 숨김; **트레이싱은 계속 기록** |
+| `stream` | 스트리밍; `ChatSession.handle_turn(..., stream=True)`와 함께 |
+
+### 메서드 및 프로퍼티
+
+| 이름 | 설명 |
+|------|------|
+| `append_message(role, content, **extra)` | `state.messages`에 추가 |
+| `conversation_messages` | LLM 호출용 읽기 전용 기록 |
+| `classify_intent(text, outcomes, *, llm, context=None)` | outcome 매핑 (`@human_feedback`와 동일 collapse) |
+| `receive_user_message(text, *, outcomes=None, llm=None)` | 사용자 메시지 추가; 선택적 `last_intent` |
+| `finalize_session_traces()` | 지연 `flow_finished` 발생 및 세션 trace batch 종료 |
+| `_should_defer_trace_finalization()` | 턴별 trace 종료 지연 여부 |
+| `input_history` | `ask()` 프롬프트/응답 감사 기록 |
+
+### 모듈 헬퍼 (`crewai.flow.conversation`)
+
+테스트 또는 커스텀 오케스트레이션용:
+
+| 함수 | 설명 |
+|------|------|
+| `normalize_kickoff_inputs(...)` | 대화 kwargs를 `inputs`에 병합 |
+| `get_conversation_messages(flow)` | 상태 또는 내부 버퍼에서 메시지 읽기 |
+| `append_message(flow, ...)` | 인스턴스 메서드와 동일 |
+| `prepare_conversational_turn(flow, ...)` | 턴 수화 (보통 kickoff가 호출) |
+| `receive_user_message(flow, ...)` | 인스턴스 메서드와 동일 |
+| `set_state_field(flow, name, value)` | dict 또는 Pydantic 상태 필드 설정 |
+| `get_conversational_config(flow)` | 클래스 `conversational_config` 읽기 |
+| `input_history_to_messages(entries)` | `input_history`를 LLM 메시지 형식으로 |
+
+## 의도 라우팅 패턴
+
+### A. `ConversationalConfig`로 사전 분류 (가장 단순)
+
+`default_intents`와 `intent_llm` 설정. 각 kickoff가 `@router` 전에 분류; `route()`에서 `self.state.last_intent` 읽기.
+
+### B. `@router` 내부에서 분류 (풍부한 프롬프트)
+
+`default_intents=None`으로 kickoff는 메시지만 추가. `route()`에서 커스텀 프롬프트로 `classify_intent` 호출:
+
+```python
+@router(bootstrap)
+def route(self):
+    intent = self.classify_intent(
+        self._routing_prompt(self.state.last_user_message),
+        ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
+        llm=self.conversational_config.intent_llm or "gpt-4o-mini",
+    )
+    self.state.last_intent = intent
+    return intent
+```
+
+웹 리서치나 다단계 tool이 필요하면 **`@listen("RESEARCH")`** 등에서 `Agent.kickoff()`와 tool 사용 — 단순 `LLM.call()` 대신.
+
+## flow가 끝났지만 사용자는 계속 대화할 때
+
+`FlowFinished`는 **이번 그래프 실행**이 완료됨을 의미합니다. 같은 `session_id`로 또 다른 `kickoff`로 대화가 이어집니다. `@persist`가 `messages`, 플래그, 컨텍스트를 복원합니다.
+
+**Persist 패턴:** 전체 `Flow` 클래스보다 **단일 종료 스텝**(예: `finalize`)에 `@persist`를 두는 것이 좋습니다. 클래스 수준 persist는 매 메서드 후 저장하며, `load_state`는 최신 행을 사용해 같은 턴의 핸들러 업데이트를 놓칠 수 있습니다.
+
+후속 채팅 줄에 `@human_feedback`를 쓰지 마세요. 특정 스텝 출력을 사람이 승인해야 할 때만 사용하세요.
+
+## 대화형 `Flow` (실험적)
+
+<Warning>
+  **실험적 기능입니다.** 대화형 `Flow`의 API 표면(`conversational = True`,
+  `handle_turn`, `ConversationConfig`, `RouterConfig`, `ConversationState`,
+  내장 그래프와 헬퍼)은 `crewai.experimental` 하위에 있으며 정식 출시
+  전까지 변경될 수 있습니다. 특정 동작에 의존한다면 CrewAI 버전을 고정하고
+  변경 사항이 있는지 changelog를 확인하세요. 피드백과 이슈 환영합니다.
+</Warning>
+
+`Flow` 서브클래스에 `conversational = True`를 지정하면 대화형 챗 그래프가 활성화됩니다. 베이스 `Flow`가 `@start` / `@router` / `converse_turn` / `end_conversation` 그래프를 노출하고, `state.messages`를 관리하며, router LLM을 구동하고, 턴 간 trace 배치를 열린 상태로 유지합니다. 여러분은 **커스텀 라우트**만 작성하면 되고, 나머지는 프레임워크가 담당합니다.
+
+LLM 기반 라우터와 라우트별 핸들러로 멀티턴 챗을 만들고 싶지만 라이프사이클을 직접 배선하고 싶지 않을 때 사용하세요. 완전한 제어가 필요하면 위의 `Flow[ChatState]`로 내려가세요.
+
+### 빠른 예제
+
+```python
+from crewai import LLM, Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+    RouterConfig,
+)
+
+
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+
+@ConversationConfig(
+    system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.",
+    llm=ROUTER_LLM,
+    router=RouterConfig(),  # 라우트 + 설명은 @listen 핸들러에서 자동 발견
+)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    @listen("INTERNET_SEARCH")
+    def handle_internet_search(self) -> str:
+        """Fresh web research, current news, real-time lookups."""
+        ...
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("CREWAI_DOCS")
+    def handle_crewai_docs(self) -> str:
+        """Look up the CrewAI documentation for framework/API questions."""
+        ...
+        self.append_assistant_message(reply)
+        return reply
+
+
+flow = SupportFlow()
+try:
+    flow.handle_turn("뭘 할 수 있어?")                # converse(빌트인)로 라우팅
+    flow.handle_turn("AI 뉴스를 웹에서 찾아줘.")        # INTERNET_SEARCH로 라우팅
+    flow.handle_turn("첫 번째 결과를 요약해줘.")        # 다시 converse로 라우팅
+finally:
+    flow.finalize_session_traces()
+```
+
+로컬 터미널 채팅에는 `chat()`을 사용하세요:
+
+```python
+def kickoff() -> None:
+    SupportFlow().chat()
+```
+
+`chat()`은 `handle_turn()`을 REPL로 감싸고, `exit` / `quit`에서 종료하며, 기본적으로 빈 줄을 건너뛰고, 세션이 끝날 때 `finalize_session_traces()`를 호출합니다.
+
+### `ConversationConfig`
+
+클래스 단위의 챗 기본값을 부착하는 클래스 데코레이터입니다.
+
+| 필드 | 기본값 | 목적 |
+|------|--------|------|
+| `system_prompt` | i18n `slices.conversational_system_prompt` | 빌트인 `converse_turn`이 사용하는 system 메시지. 빈 문자열(`""`)을 전달하면 system 메시지를 끕니다. |
+| `llm` | `None` | 대화용 LLM (빌트인 `converse_turn`이 사용하고 router 폴백도 됨). |
+| `router` | `None` | LLM 기반 라우팅을 위한 `RouterConfig`. 없으면 항상 `converse`로 떨어집니다. |
+| `answer_from_history_prompt` | 프레임워크 기본값 | 선택적인 `answer_from_history` 라우트용 system 메시지. |
+| `answer_from_history_llm` | `None` | 설정되면 `answer_from_history` 단축 경로가 활성화됩니다. |
+| `intent_llm` | `None` | 레거시 `intents=`/`default_intents` 사전 분류용 LLM. |
+| `default_intents` | `None` | 레거시 사전 분류용 outcome 레이블. |
+| `visible_agent_outputs` | `None` | `"all"` 또는 `append_agent_result()` 결과를 사용자에게 공개로 승격할 에이전트 이름 목록. |
+| `defer_trace_finalization` | `True` | `handle_turn()` 호출들 사이에서 하나의 trace 배치를 열어 둡니다. |
+
+### `RouterConfig`와 자동 생성되는 라우트 카탈로그
+
+```python
+RouterConfig(
+    prompt="선택적인 도메인 프레이밍 (정책, 톤, 페르소나).",
+    response_format=MyRoute,        # 선택; 없으면 자동 생성
+    llm=ROUTER_LLM,                  # ConversationConfig.llm으로 폴백
+    routes=["INTERNET_SEARCH", "CREWAI_DOCS"],   # 선택; 리스너에서 추론
+    route_descriptions={
+        "INTERNET_SEARCH": "이 라우트만 docstring 대신 사용할 설명.",
+    },
+    default_intent="converse",       # LLM 호출 실패 또는 LLM 없음일 때 사용
+    fallback_intent="converse",      # LLM이 잘못된 라우트를 반환할 때 사용
+    intent_field="intent",
+)
+```
+
+router에 전달되는 프롬프트는 자동으로 만들어집니다. 각 라우트의 설명은 다음 우선순위로 결정됩니다:
+
+1. `RouterConfig.route_descriptions[label]` — 명시적 오버라이드.
+2. `Flow.builtin_route_descriptions[label]` — `converse`, `end`, `answer_from_history`용 프레임워크 캐닝 텍스트 (router LLM용으로 다듬어진 문구).
+3. `@listen(label)` 핸들러 docstring의 첫 줄(비어있지 않은 줄).
+4. 빈 문자열 (라우트만 카탈로그에 등장하고 설명은 없음).
+
+실제 사용에서 **새 라우트를 추가하는 방법은 `@listen("X")` + 한 줄짜리 docstring**입니다:
+
+```python
+@listen("INTERNET_SEARCH")
+def handle_internet_search(self) -> str:
+    """Fresh web research, current news, real-time lookups."""
+    ...
+```
+
+…그러면 router LLM은 다음을 봅니다:
+
+```
+Routes:
+- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions.
+- INTERNET_SEARCH: Fresh web research, current news, real-time lookups.
+- converse: Ordinary chat, follow-ups, summaries, clarifications…
+- end: User signals the conversation is finished (goodbye, exit, done).
+```
+
+`RouterConfig.prompt`는 **도메인 프레이밍** (어시스턴트 페르소나, 비즈니스 규칙, 톤)을 위한 자리입니다. 라우트 카탈로그는 자동 생성되니 `prompt` 안에 라우트 목록을 넣지 마세요. 핸들러를 추가하는 순간 동기화가 깨집니다.
+
+### 빌트인 라우트
+
+| 라우트 | 핸들러 | 목적 |
+|--------|--------|------|
+| `converse` | `converse_turn` | 기본 챗 핸들러. system prompt + 정식 메시지 히스토리와 함께 `ConversationConfig.llm`을 호출합니다. |
+| `end` | `end_conversation` | `state.ended = True`로 설정하고 종료 응답을 보냅니다. |
+| `answer_from_history` | `answer_from_history_turn` | 선택적. `ConversationConfig.answer_from_history_llm`이 설정되어 있고 메시지를 히스토리만으로 답할 수 있을 때 라우팅됩니다. |
+
+서브클래스에 같은 이름의 핸들러를 정의하면 어떤 것이든 오버라이드할 수 있습니다.
+
+### `handle_turn()` 시맨틱
+
+`flow.handle_turn(message)`는 한 턴을 실행합니다:
+
+1. 그래프가 다시 실행되도록 턴 단위 실행 추적(`_completed_methods`, `_method_outputs`)을 초기화합니다 — 이게 없으면 동일 인스턴스에서 반복 `kickoff` 호출 시 `Flow.kickoff_async`가 `inputs={"id": ...}`를 체크포인트 복원으로 간주해 2번째 턴부터 단락 회로가 발생합니다.
+2. 사용자 메시지를 `state.messages`에 추가하고 `current_user_message` / `last_user_message`를 설정합니다. `last_intent`는 **이전 턴 값이 유지**되어 router LLM이 신호로 활용할 수 있습니다.
+3. `conversation_start` → `route_conversation` → 선택된 `@listen` 핸들러 순으로 실행됩니다.
+4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다).
+5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다.
+
+채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다.
+
+### 로컬 REPL용 `chat()`
+
+`flow.chat()`은 `handle_turn()` 위에 얹은 바로 쓸 수 있는 터미널 래퍼입니다:
+
+```python
+flow = SupportFlow()
+flow.chat()
+```
+
+일반적인 로컬 루프를 처리합니다:
+
+1. 사용자 메시지를 입력받습니다.
+2. `exit` / `quit`, `EOFError`, `KeyboardInterrupt`에서 멈춥니다.
+3. `handle_turn(message, session_id=...)`를 호출합니다.
+4. 어시스턴트 결과를 출력합니다.
+5. `finally` 블록에서 지연된 세션 trace를 finalize합니다.
+
+주입 가능한 I/O로 터미널 동작을 커스터마이즈할 수 있습니다:
+
+```python
+flow.chat(
+    session_id="demo-session",
+    prompt="You: ",
+    assistant_prefix="Assistant: ",
+    exit_commands=("exit", "quit", "bye"),
+)
+```
+
+웹 앱, 백그라운드 worker, 테스트, 커스텀 transport에서는 계속 `handle_turn()`을 직접 사용하세요.
+
+### 커스텀 router 동작
+
+매 라우팅 결정마다 사이드 이펙트(이벤트 버스 셋업, 텔레메트리)를 실행하려면 `route_turn`을 오버라이드하세요:
+
+```python
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context: dict[str, Any]) -> str | None:
+        self.event_bus = MyBus(self)
+        return super().route_turn(context)
+```
+
+LLM router를 우회해 프로그램적으로 라우트를 선택하려면 `route_turn`에서 문자열을 반환하세요. `None`을 반환하면 `_route_with_config(...)`로 떨어집니다.
+
+### `append_assistant_message`와 `append_agent_result`
+
+`@listen(label)` 핸들러 안에서 두 가지 중 선택하세요:
+
+- `self.append_assistant_message(text)` — 사용자에게 보이는 어시스턴트 턴을 `state.messages`에 추가합니다. 다음 턴의 `converse_turn`이 이 내용을 보게 됩니다.
+- `self.append_agent_result(agent_name, result, visibility="private")` — 구조화된 이벤트를 `state.events`에, 스레드를 `state.agent_threads[agent_name]`에 기록합니다. public 가시성은 자동으로 `append_assistant_message`도 호출합니다. 정식 히스토리를 더럽히지 말아야 할 임시 작업에는 private을 쓰세요.
+
+`ConversationConfig.visible_agent_outputs`로 특정 에이전트의 private 결과를 전역적으로 public으로 승격할 수 있습니다 (`"all"` 또는 이름 리스트).
+
+## 턴 간 트레이싱
+
+`defer_trace_finalization=True` (`ConversationalConfig` 기본값):
+
+- 채팅 세션 전체에 **하나의 trace batch**.
+- 첫 턴에만 **`flow_started`**; `finalize_session_traces()`에서 **`flow_finished`** 한 번.
+- 턴별 `kickoff`는 “Trace batch finalized”를 출력하지 않음.
+- **중첩 작업** (`Agent.kickoff()`, crew, Exa tool)은 **부모** batch에 추가; 내부 `AgentExecutor` flow가 세션 batch를 조기 종료하지 않음.
+
+```python
+flow.chat(session_id=session_id)
+```
+
+`flow.chat()`이 `finalize_session_traces()`를 대신 호출합니다. `handle_turn()`이나 `kickoff(...)`로 직접 루프를 소유하는 경우, 세션이 끝날 때 `finalize_session_traces()`를 호출하세요.
+
+`suppress_flow_events=True`는 Rich 콘솔 패널만 숨깁니다. trace 및 method 이벤트는 계속 발생합니다.
+
+### 대화형 `Flow` trace 수명 주기
+
+실험적 [대화형 `Flow`](#대화형-flow-실험적)는 동일한 tracing 수명 주기를 따릅니다. `defer_trace_finalization` 기본값이 `True`이므로 각 `handle_turn()`이 세션 trace를 열어 둡니다. 세션 끝에서 항상 finalize하세요 — REPL/루프를 `try/finally`로 감싸고 종료 시 `flow.finalize_session_traces()`를 호출하세요. 호출하지 않으면 batch가 열린 채 남아 마지막 대화가 export되지 않을 수 있습니다.
+
+## 스트리밍
+
+`Flow` 클래스에 `stream = True`. `kickoff(...)`가 표준 이벤트 버스를 통해 `assistant_delta` 등 이벤트를 발생시킵니다.
+
+## import
+
+```python
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+    Flow,
+    listen,
+    persist,
+    router,
+    start,
+)
+```
+
+## 참고
+
+- [Flow 상태 관리 마스터하기](/ko/guides/flows/mastering-flow-state)
+- [첫 Flow 만들기](/ko/guides/flows/first-flow)
+- 데모: `lib/crewai/runner_conversational_flow_simple.py`

docs/ko/guides/flows/first-flow.mdx

@@ -64,7 +64,7 @@ cd guide_creator_flow
 
 ## 2단계: 프로젝트 구조 이해하기
 
-생성된 프로젝트는 다음과 같은 구조를 가지고 있습니다. 잠시 시간을 내어 이 구조에 익숙해지세요. 구조를 이해하면 앞으로 더 복잡한 flow를 만드는 데 도움이 됩니다.
+생성된 프로젝트는 다음과 같은 구조를 가지고 있습니다. 시작용 embedded crew는 클래식 Python/YAML 레이아웃을 사용합니다. Flow 안에서 JSON-first crew를 사용하려면 crew 폴더에 `crew.jsonc`와 `agents/*.jsonc`를 만들고 `crewai.project.load_crew`로 로드하세요. 예시는 [Flows](/ko/concepts/flows#building-your-crews)를 참고하세요.
 
 ```
 guide_creator_flow/
@@ -72,21 +72,24 @@ guide_creator_flow/
 ├── pyproject.toml
 ├── README.md
 ├── .env
-├── main.py
-├── crews/
-│   └── poem_crew/
-│       ├── config/
-│       │   ├── agents.yaml
-│       │   └── tasks.yaml
-│       └── poem_crew.py
-└── tools/
-    └── custom_tool.py
+└── src/
+    └── guide_creator_flow/
+        ├── __init__.py
+        ├── main.py
+        ├── crews/
+        │   └── poem_crew/
+        │       ├── config/
+        │       │   ├── agents.yaml
+        │       │   └── tasks.yaml
+        │       └── poem_crew.py
+        └── tools/
+            └── custom_tool.py
 ```
 
 이 구조는 flow의 다양한 구성 요소를 명확하게 분리해줍니다:
-- `main.py` 파일의 main flow 로직
-- `crews` 디렉터리의 특화된 crew들
-- `tools` 디렉터리의 custom tool들
+- `src/guide_creator_flow/main.py` 파일의 main flow 로직
+- `src/guide_creator_flow/crews` 디렉터리의 특화된 crew들
+- `src/guide_creator_flow/tools` 디렉터리의 custom tool들
 
 이제 이 구조를 수정하여 guide creator flow를 만들 것입니다. 이 flow는 포괄적인 학습 가이드 생성을 조직하는 역할을 합니다.
 
@@ -102,149 +105,82 @@ crewai flow add-crew content-crew
 
 ## 4단계: 콘텐츠 작가 Crew 구성
 
-이제 콘텐츠 작가 crew를 위해 생성된 파일을 수정해보겠습니다. 우리는 가이드의 고품질 콘텐츠를 만들기 위해 협업하는 두 명의 전문 에이전트 - 작가와 리뷰어 - 를 설정할 것입니다.
+이제 콘텐츠 작가 crew를 JSONC로 구성합니다. 가이드의 고품질 콘텐츠를 만들기 위해 협업하는 두 명의 전문 에이전트 - 작가와 리뷰어 - 를 설정합니다.
 
-1. 먼저, 에이전트 구성 파일을 업데이트하여 콘텐츠 제작 팀을 정의합니다:
+1. `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`를 만듭니다:
 
-   `llm`을 사용 중인 공급자로 설정해야 함을 기억하세요.
-
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/agents.yaml
-content_writer:
-  role: >
-    교육 콘텐츠 작가
-  goal: >
-    할당된 주제를 철저히 설명하고 독자에게 소중한 통찰력을 제공하는 흥미롭고 유익한 콘텐츠를 제작합니다
-  backstory: >
-    당신은 명확하고 흥미로운 콘텐츠를 만드는 데 능숙한 교육 전문 작가입니다. 복잡한 개념도 쉽게 설명하며,
-    정보를 독자가 이해하기 쉽게 조직할 수 있습니다.
-  llm: provider/model-id  # 예: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
-
-content_reviewer:
-  role: >
-    교육 콘텐츠 검토자 및 에디터
-  goal: >
-    콘텐츠가 정확하고, 포괄적이며, 잘 구조화되어 있고, 이전에 작성된 섹션과의 일관성을 유지하도록 합니다
-  backstory: >
-    당신은 수년간 교육 콘텐츠를 검토해 온 꼼꼼한 에디터입니다. 세부 사항, 명확성, 일관성에 뛰어나며,
-    원 저자의 목소리를 유지하면서도 콘텐츠의 품질을 향상시키는 데 능숙합니다.
-  llm: provider/model-id  # 예: openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
+```jsonc
+{
+  "role": "Educational Content Writer",
+  "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.",
+  "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-이 에이전트 정의는 AI 에이전트가 콘텐츠 제작을 접근하는 전문화된 역할과 관점을 구성합니다. 각 에이전트가 뚜렷한 목적과 전문성을 지니고 있음을 확인하세요.
+2. `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`를 만듭니다:
 
-2. 다음으로, 작업 구성 파일을 업데이트하여 구체적인 작성 및 검토 작업을 정의합니다:
-
-```yaml
-# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
-write_section_task:
-  description: >
-    주제에 대한 포괄적인 섹션을 작성하세요: "{section_title}"
-
-    섹션 설명: {section_description}
-    대상 독자: {audience_level} 수준 학습자
-
-    작성 시 아래 사항을 반드시 지켜주세요:
-    1. 섹션 주제에 대한 간략한 소개로 시작
-    2. 모든 주요 개념을 예시와 함께 명확하게 설명
-    3. 적절하다면 실용적인 활용 사례나 연습문제 포함
-    4. 주요 포인트 요약으로 마무리
-    5. 대략 500-800단어 분량
-
-    콘텐츠는 적절한 제목, 목록, 강조를 포함해 Markdown 형식으로 작성하세요.
-
-    이전에 작성된 섹션:
-    {previous_sections}
-
-    반드시 콘텐츠가 이전에 쓴 섹션과 일관성을 유지하고 앞에서 설명된 개념을 바탕으로 작성되도록 하세요.
-  expected_output: >
-    주제를 철저히 설명하고 대상 독자에게 적합한, 구조가 잘 잡힌 Markdown 형식의 포괄적 섹션
-  agent: content_writer
-
-review_section_task:
-  description: >
-    아래 "{section_title}" 섹션의 내용을 검토하고 개선하세요:
-
-    {draft_content}
-
-    대상 독자: {audience_level} 수준 학습자
-
-    이전에 작성된 섹션:
-    {previous_sections}
-
-    검토 시 아래 사항을 반드시 지켜주세요:
-    1. 문법/철자 오류 수정
-    2. 명확성 및 가독성 향상
-    3. 내용이 포괄적이고 정확한지 확인
-    4. 이전에 쓴 섹션과 일관성 유지
-    5. 구조와 흐름 강화
-    6. 누락된 핵심 정보 추가
-
-    개선된 버전의 섹션을 Markdown 형식으로 제공하세요.
-  expected_output: >
-    원래의 구조를 유지하면서도 명확성, 정확성, 일관성을 향상시킨 세련된 개선본
-  agent: content_reviewer
-  context:
-    - write_section_task
+```jsonc
+{
+  "role": "Educational Content Reviewer and Editor",
+  "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.",
+  "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
 ```
 
-이 작업 정의는 에이전트에게 세부적인 지침을 제공하여 우리의 품질 기준에 부합하는 콘텐츠를 생산하게 합니다. review 작업의 `context` 파라미터를 통해 리뷰어가 작가의 결과물에 접근할 수 있는 워크플로우가 생성됨에 주의하세요.
+`provider/model-id`를 사용하는 모델로 바꾸세요. 예: `openai/gpt-4o`, `gemini/gemini-2.0-flash-001`, `anthropic/claude-sonnet-4-6`.
 
-3. 이제 crew 구현 파일을 업데이트하여 에이전트와 작업이 어떻게 연동되는지 정의합니다:
+3. `src/guide_creator_flow/crews/content_crew/crew.jsonc`를 만듭니다:
+
+```jsonc
+{
+  "name": "Content Crew",
+  "agents": ["content_writer", "content_reviewer"],
+  "tasks": [
+    {
+      "name": "write_section_task",
+      "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}",
+      "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.",
+      "agent": "content_writer",
+      "markdown": true
+    },
+    {
+      "name": "review_section_task",
+      "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.",
+      "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.",
+      "agent": "content_reviewer",
+      "context": ["write_section_task"],
+      "markdown": true
+    }
+  ],
+  "process": "sequential",
+  "verbose": true
+}
+```
+
+`context` 필드를 통해 리뷰어가 작가의 출력을 사용할 수 있습니다.
+
+4. `src/guide_creator_flow/crews/content_crew/content_crew.py`를 작은 loader로 교체합니다:
 
 ```python
-# src/guide_creator_flow/crews/content_crew/content_crew.py
-from crewai import Agent, Crew, Process, Task
-from crewai.project import CrewBase, agent, crew, task
-from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List
+from pathlib import Path
 
-@CrewBase
-class ContentCrew():
-    """Content writing crew"""
+from crewai.project import load_crew
 
-    agents: List[BaseAgent]
-    tasks: List[Task]
 
-    @agent
-    def content_writer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_writer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @agent
-    def content_reviewer(self) -> Agent:
-        return Agent(
-            config=self.agents_config['content_reviewer'], # type: ignore[index]
-            verbose=True
-        )
-
-    @task
-    def write_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['write_section_task'] # type: ignore[index]
-        )
-
-    @task
-    def review_section_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['review_section_task'], # type: ignore[index]
-            context=[self.write_section_task()]
-        )
-
-    @crew
-    def crew(self) -> Crew:
-        """Creates the content writing crew"""
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
+def kickoff_content_crew(inputs: dict):
+    crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+    return crew.kickoff(inputs={**default_inputs, **inputs})
 ```
 
-이 crew 정의는 에이전트와 작업 간의 관계를 설정하여, 콘텐츠 작가가 초안을 작성하고 리뷰어가 이를 개선하는 순차적 과정을 만듭니다. 이 crew는 독립적으로도 작동할 수 있지만, 우리의 플로우에서 더 큰 시스템의 일부로 오케스트레이션될 예정입니다.
+이 loader는 런타임에 `crew.jsonc`를 `Crew`로 바꿉니다. 이 crew는 독립적으로도 작동할 수 있지만, 우리의 플로우에서는 더 큰 시스템의 일부로 오케스트레이션됩니다.
 
 ## 5단계: 플로우(Flow) 생성
 
@@ -266,7 +202,7 @@ from typing import List, Dict
 from pydantic import BaseModel, Field
 from crewai import LLM
 from crewai.flow.flow import Flow, listen, start
-from guide_creator_flow.crews.content_crew.content_crew import ContentCrew
+from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew
 
 # Define our models for structured data
 class Section(BaseModel):
@@ -371,7 +307,7 @@ class GuideCreatorFlow(Flow[GuideCreatorState]):
                 previous_sections_text = "No previous sections written yet."
 
             # Run the content crew for this section
-            result = ContentCrew().crew().kickoff(inputs={
+            result = kickoff_content_crew(inputs={
                 "section_title": section.title,
                 "section_description": section.description,
                 "audience_level": self.state.audience_level,
@@ -590,7 +526,7 @@ class GuideCreatorState(BaseModel):
 Flow는 복잡한 협업 작업을 위해 crew와 원활하게 통합될 수 있습니다:
 
 ```python
-result = ContentCrew().crew().kickoff(inputs={
+result = kickoff_content_crew(inputs={
     "section_title": section.title,
     # ...
 })
@@ -607,7 +543,8 @@ result = ContentCrew().crew().kickoff(inputs={
 3. 더 복잡한 병렬 실행을 위해 `and_` 및 `or_` 함수를 탐색해 보세요.
 4. flow를 외부 API, 데이터베이스 또는 사용자 인터페이스에 연결해 보세요.
 5. 여러 전문화된 crew를 하나의 flow에서 결합해 보세요.
+6. [대화형 Flow](/ko/guides/flows/conversational-flows)로 멀티턴 채팅 앱 구축 (`kickoff` per message, `ChatSession`, 지연 트레이싱)
 
 <Check>
 축하합니다! 정규 코드, 직접적인 LLM 호출, crew 기반 처리를 결합하여 포괄적인 가이드를 생성하는 첫 번째 CrewAI Flow를 성공적으로 구축하셨습니다. 이러한 기초적인 역량을 바탕으로 절차적 제어와 협업적 인텔리전스를 결합하여 복잡하고 다단계의 문제를 해결할 수 있는 점점 더 정교한 AI 애플리케이션을 만들 수 있습니다.
-</Check>
+</Check>

docs/ko/guides/flows/mastering-flow-state.mdx

@@ -22,6 +22,8 @@ State 관리는 모든 고급 AI 워크플로우의 중추입니다. CrewAI Flow
 5. **애플리케이션 확장** - 적절한 데이터 조직을 통해 복잡한 워크플로를 지원할 수 있습니다.
 6. **대화형 애플리케이션 활성화** - 컨텍스트 기반 AI 상호작용을 위해 대화 내역을 저장하고 접근할 수 있습니다.
 
+멀티턴 채팅(`kickoff` per user line, `ChatState`, 의도 라우팅, 지연 트레이싱, `ChatSession`)은 [대화형 Flow](/ko/guides/flows/conversational-flows)를 참고하세요.
+
 이러한 기능을 효과적으로 활용하는 방법을 살펴보겠습니다.
 
 ## 상태 관리 기본 사항

docs/ko/installation.mdx

@@ -106,7 +106,7 @@ CrewAI는 의존성 관리와 패키지 처리를 위해 `uv`를 사용합니다
 
 # CrewAI 프로젝트 생성하기
 
-에이전트 및 태스크를 정의할 때 구조적인 접근 방식을 위해 `YAML` 템플릿 스캐폴딩을 사용하는 것을 권장합니다. 다음은 시작 방법입니다:
+`crewai create crew`는 이제 JSON-first crew 프로젝트를 생성합니다. 에이전트는 `agents/*.jsonc`에, 태스크와 crew 수준 설정은 `crew.jsonc`에 두며, `crewai run`은 이 JSON 정의를 직접 로드합니다.
 
 <Steps>
   <Step title="프로젝트 스캐폴딩 생성">
@@ -119,21 +119,20 @@ CrewAI는 의존성 관리와 패키지 처리를 위해 `uv`를 사용합니다
       ```
       my_project/
       ├── .gitignore
+      ├── .env
+      ├── agents/
+      │   └── researcher.jsonc
+      ├── crew.jsonc
       ├── knowledge/
       ├── pyproject.toml
       ├── README.md
-      ├── .env
-      └── src/
-          └── my_project/
-              ├── __init__.py
-              ├── main.py
-              ├── crew.py
-              ├── tools/
-              │   ├── custom_tool.py
-              │   └── __init__.py
-              └── config/
-                  ├── agents.yaml
-                  └── tasks.yaml
+      ├── skills/
+      └── tools/
+      ```
+
+    - `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요하다면 다음을 실행하세요:
+      ```shell
+      crewai create crew <your_project_name> --classic
       ```
 
   </Step>
@@ -142,15 +141,15 @@ CrewAI는 의존성 관리와 패키지 처리를 위해 `uv`를 사용합니다
     - 프로젝트에는 다음과 같은 주요 파일들이 포함되어 있습니다:
       | 파일 | 용도 |
       | --- | --- |
-      | `agents.yaml` | AI 에이전트 및 역할 정의 |
-      | `tasks.yaml` | 에이전트 태스크 및 워크플로우 설정 |
+      | `crew.jsonc` | crew, 태스크 순서, 프로세스, 기본 입력값 설정 |
+      | `agents/*.jsonc` | 각 에이전트의 역할, 목표, backstory, LLM, 도구, 동작 정의 |
       | `.env` | API 키 및 환경 변수 저장 |
-      | `main.py` | 프로젝트 진입점 및 실행 흐름 |
-      | `crew.py` | Crew 오케스트레이션 및 코디네이션 |
-      | `tools/` | 커스텀 에이전트 도구 디렉터리 |
-      | `knowledge/` | 지식 베이스 디렉터리 |
+      | `tools/` | `custom:<name>` 도구를 위한 선택적 Python 파일 |
+      | `knowledge/` | 에이전트용 선택적 지식 파일 |
+      | `skills/` | crew에 적용할 선택적 skill 파일 |
 
-    - `agents.yaml` 및 `tasks.yaml`을 편집하여 crew의 동작을 정의하는 것부터 시작하세요.
+    - `crew.jsonc`와 `agents/` 안의 파일을 편집하여 crew 동작을 정의하세요.
+    - 에이전트와 태스크 텍스트에 `{placeholder}`를 사용하고, `crew.jsonc`의 `inputs`에 기본값을 넣으세요. `crewai run` 실행 시 빠진 값은 CLI가 묻습니다.
     - API 키와 같은 민감한 정보는 `.env` 파일에 보관하세요.
 
   </Step>

docs/ko/learn/using-annotations.mdx

@@ -5,11 +5,15 @@ icon: "at"
 mode: "wide"
 ---
 
-이 가이드는 `crew.py` 파일에서 **agent**, **task**, 및 기타 구성 요소를 올바르게 참조하기 위해 주석을 사용하는 방법을 설명합니다.
+이 가이드는 클래식 `crew.py` 파일에서 **agent**, **task**, 및 기타 구성 요소를 올바르게 참조하기 위해 어노테이션을 사용하는 방법을 설명합니다.
+
+<Note>
+`crewai create crew <name>`으로 만든 새 프로젝트는 JSON-first이며 `crew.jsonc`와 `agents/*.jsonc`를 사용합니다. 이 가이드는 `crewai create crew <name> --classic`으로 만든 클래식 프로젝트, 기존 Python/YAML 프로젝트 마이그레이션, 또는 Python 데코레이터 제어가 필요한 경우에 사용하세요.
+</Note>
 
 ## 소개
 
-CrewAI 프레임워크에서 어노테이션은 클래스와 메소드를 데코레이트하는 데 사용되며, crew의 다양한 컴포넌트에 메타데이터와 기능을 제공합니다. 이러한 어노테이션은 코드의 구성과 구조화를 돕고, 코드의 가독성과 유지 관리를 용이하게 만듭니다.
+CrewAI 프레임워크에서 어노테이션은 클래스와 메소드를 데코레이트하는 데 사용되며, crew의 다양한 컴포넌트에 메타데이터와 기능을 제공합니다. 클래식 Python/YAML 프로젝트에서는 `config/agents.yaml`, `config/tasks.yaml`을 로드하고 `Crew` 객체를 반환하는 코드를 구조화합니다.
 
 ## 사용 가능한 어노테이션
 
@@ -113,9 +117,9 @@ def crew(self) -> Crew:
 
 `@crew` 어노테이션은 `Crew` 객체를 생성하고 반환하는 메서드를 데코레이션하는 데 사용됩니다. 이 메서드는 모든 구성 요소(agents와 tasks)를 기능적인 crew로 조합합니다.
 
-## YAML 구성
+## 클래식 YAML 구성
 
-에이전트 구성은 일반적으로 YAML 파일에 저장됩니다. 아래는 연구원 에이전트에 대한 `agents.yaml` 파일 예시입니다.
+클래식 프로젝트에서 에이전트 구성은 일반적으로 YAML 파일에 저장됩니다. 아래는 연구원 에이전트에 대한 `agents.yaml` 파일 예시입니다.
 
 ```yaml
 researcher:
@@ -146,6 +150,6 @@ YAML 파일의 `llm`과 `tools`가 Python 클래스에서 `@llm` 및 `@tool`로
 - **일관성 있는 명명**: 메서드에 대해 명확하고 일관성 있는 명명 규칙을 사용하세요. 예를 들어, agent 메서드는 역할에 따라 이름을 지정할 수 있습니다(예: researcher, reporting_analyst).
 - **환경 변수**: API 키와 같은 민감한 정보를 위해 환경 변수를 사용하세요.
 - **유연성**: agent와 task를 쉽게 추가 및 제거할 수 있도록 crew를 유연하게 설계하세요.
-- **YAML-코드 일치**: YAML 파일의 이름과 구조가 Python 코드의 데코레이터가 적용된 메서드와 정확히 일치하는지 확인하세요.
+- **YAML-코드 일치**: 클래식 프로젝트에서는 YAML 파일의 이름과 구조가 Python 코드의 데코레이터가 적용된 메서드와 정확히 일치하는지 확인하세요.
 
-이 지침을 따르고 주석을 올바르게 사용하면 CrewAI 프레임워크를 이용해 구조적이고 유지보수가 쉬운 crew를 만들 수 있습니다.
+이 지침을 따르고 어노테이션을 올바르게 사용하면 클래식 crew를 구조적이고 유지보수하기 쉽게 유지할 수 있습니다. 새 crew에는 [Crews](/ko/concepts/crews)의 JSON-first 구조를 권장합니다.

docs/ko/quickstart.mdx

@@ -39,84 +39,60 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
   이렇게 하면 `src/latest_ai_flow/` 아래에 Flow 앱이 만들어지고, 다음 단계에서 **단일 에이전트** 연구 crew로 바꿀 시작용 crew가 `crews/content_crew/`에 포함됩니다.
   </Step>
 
-  <Step title="`agents.yaml`에 에이전트 하나 설정">
-  `src/latest_ai_flow/crews/content_crew/config/agents.yaml` 내용을 한 명의 연구원만 남기도록 바꿉니다. `{topic}` 같은 변수는 `crew.kickoff(inputs=...)`로 채워집니다.
+  <Step title="JSONC로 에이전트 하나 설정">
+  `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc`를 만듭니다(`agents/` 디렉터리가 없으면 생성). `{topic}` 같은 변수는 `crew.kickoff(inputs=...)`로 채워집니다.
 
-    ```yaml agents.yaml
-    # src/latest_ai_flow/crews/content_crew/config/agents.yaml
-    researcher:
-      role: >
-        {topic} 시니어 데이터 리서처
-      goal: >
-        {topic} 분야의 최신 동향을 파악한다
-      backstory: >
-        당신은 {topic}의 최신 흐름을 찾아내는 데 능숙한 연구원입니다.
-        가장 관련성 높은 정보를 찾아 명확하게 전달합니다.
+    ```jsonc agents/researcher.jsonc
+    {
+      "role": "{topic} 시니어 데이터 리서처",
+      "goal": "{topic} 분야의 최신 동향을 파악한다",
+      "backstory": "당신은 가장 관련성 높은 정보를 찾아 명확하게 전달하는 연구원입니다.",
+      "tools": ["SerperDevTool"],
+      "settings": {
+        "verbose": true
+      }
+    }
     ```
 
   </Step>
 
-  <Step title="`tasks.yaml`에 작업 하나 설정">
-    ```yaml tasks.yaml
-    # src/latest_ai_flow/crews/content_crew/config/tasks.yaml
-    research_task:
-      description: >
-        {topic}에 대해 철저히 조사하세요. 웹 검색으로 최신이고 신뢰할 수 있는 정보를 찾으세요.
-        현재 연도는 2026년입니다.
-      expected_output: >
-        마크다운 보고서로, 주요 트렌드·주목할 도구나 기업·시사점 등으로 섹션을 나누세요.
-        분량은 약 800~1200단어. 문서 전체를 코드 펜스로 감싸지 마세요.
-      agent: researcher
-      output_file: output/report.md
+  <Step title="`crew.jsonc`에 crew 설정">
+  `src/latest_ai_flow/crews/content_crew/crew.jsonc`를 만듭니다:
+
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "{topic}에 대해 철저히 조사하세요. 웹 검색으로 최신이고 신뢰할 수 있는 정보를 찾으세요.",
+          "expected_output": "마크다운 보고서로, 주요 트렌드·주목할 도구나 기업·시사점 등으로 섹션을 나누세요. 분량은 약 800~1200단어. 문서 전체를 코드 펜스로 감싸지 마세요.",
+          "agent": "researcher",
+          "output_file": "output/report.md",
+          "markdown": true
+        }
+      ],
+      "process": "sequential",
+      "verbose": true
+    }
     ```
 
   </Step>
 
-  <Step title="crew 클래스 연결 (`content_crew.py`)">
-  생성된 crew가 YAML을 읽고 연구원에게 `SerperDevTool`을 붙이도록 합니다.
+  <Step title="JSON crew 로드 (`content_crew.py`)">
+  생성된 `content_crew.py`를 `crew.jsonc`를 `Crew`로 바꾸는 작은 loader로 교체합니다.
 
     ```python content_crew.py
     # src/latest_ai_flow/crews/content_crew/content_crew.py
-    from typing import List
+    from pathlib import Path
 
-    from crewai import Agent, Crew, Process, Task
-    from crewai.agents.agent_builder.base_agent import BaseAgent
-    from crewai.project import CrewBase, agent, crew, task
-    from crewai_tools import SerperDevTool
+    from crewai.project import load_crew
 
 
-    @CrewBase
-    class ResearchCrew:
-      """Flow 안에서 사용하는 단일 에이전트 연구 crew."""
-
-      agents: List[BaseAgent]
-      tasks: List[Task]
-
-      agents_config = "config/agents.yaml"
-      tasks_config = "config/tasks.yaml"
-
-      @agent
-      def researcher(self) -> Agent:
-        return Agent(
-          config=self.agents_config["researcher"],  # type: ignore[index]
-          verbose=True,
-          tools=[SerperDevTool()],
-        )
-
-      @task
-      def research_task(self) -> Task:
-        return Task(
-          config=self.tasks_config["research_task"],  # type: ignore[index]
-        )
-
-      @crew
-      def crew(self) -> Crew:
-        return Crew(
-          agents=self.agents,
-          tasks=self.tasks,
-          process=Process.sequential,
-          verbose=True,
-        )
+    def kickoff_content_crew(inputs: dict):
+      crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+      return crew.kickoff(inputs={**default_inputs, **inputs})
     ```
 
   </Step>
@@ -130,7 +106,7 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
 
     from crewai.flow import Flow, listen, start
 
-    from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew
+    from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew
 
 
     class ResearchFlowState(BaseModel):
@@ -149,7 +125,7 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
 
       @listen(prepare_topic)
       def run_research(self):
-        result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic})
+        result = kickoff_content_crew(inputs={"topic": self.state.topic})
         self.state.report = result.raw
         print("연구 crew 실행 완료.")
 
@@ -171,7 +147,7 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
     ```
 
   <Tip>
-  패키지 이름이 `latest_ai_flow`가 아니면 `ResearchCrew` import 경로를 프로젝트 모듈 경로에 맞게 바꾸세요.
+  패키지 이름이 `latest_ai_flow`가 아니면 `kickoff_content_crew` import 경로를 프로젝트 모듈 경로에 맞게 바꾸세요.
   </Tip>
   </Step>
 
@@ -198,7 +174,7 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
 
   <CodeGroup>
     ```markdown output/report.md
-    # 2026년 AI 에이전트: 동향과 전망
+    # AI 에이전트: 최신 동향과 전망
 
     ## 요약
     …
@@ -219,7 +195,7 @@ CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/install
 ## 한 번에 이해하기
 
 1. **Flow** — `LatestAiFlow`는 `prepare_topic` → `run_research` → `summarize` 순으로 실행됩니다. 상태(`topic`, `report`)는 Flow에 있습니다.
-2. **Crew** — `ResearchCrew`는 에이전트 한 명·작업 하나로 실행됩니다. 연구원이 **Serper**로 웹을 검색하고 구조화된 보고서를 씁니다.
+2. **Crew** — `kickoff_content_crew`가 `crew.jsonc`를 로드하고 에이전트 한 명·작업 하나로 실행합니다. 연구원이 **Serper**로 웹을 검색하고 구조화된 보고서를 씁니다.
 3. **결과물** — 작업의 `output_file`이 `output/report.md`에 보고서를 씁니다.
 
 Flow 패턴(라우팅, 지속성, human-in-the-loop)을 더 보려면 [첫 Flow 만들기](/ko/guides/flows/first-flow)와 [Flows](/ko/concepts/flows)를 참고하세요. Flow 없이 crew만 쓰려면 [Crews](/ko/concepts/crews)를, 작업 없이 단일 `Agent`의 `kickoff()`만 쓰려면 [Agents](/ko/concepts/agents#direct-agent-interaction-with-kickoff)를 참고하세요.
@@ -230,7 +206,10 @@ Flow 패턴(라우팅, 지속성, human-in-the-loop)을 더 보려면 [첫 Flow
 
 ### 이름 일치
 
-YAML 키(`researcher`, `research_task`)는 `@CrewBase` 클래스의 메서드 이름과 같아야 합니다. 전체 데코레이터 패턴은 [Crews](/ko/concepts/crews)를 참고하세요.
+`crew.jsonc`의 이름은 파일과 참조에 맞아야 합니다:
+
+- `agents: ["researcher"]`는 `agents/researcher.jsonc`를 로드합니다.
+- `tasks[].agent: "researcher"`는 해당 태스크를 그 에이전트에 배정합니다.
 
 ## 배포
 

docs/ko/skills.mdx

@@ -20,7 +20,7 @@ npx skills add crewaiinc/skills
 ## 에이전트가 얻는 것
 
 - **Flows** — CrewAI 방식의 상태ful 앱, 단계, crew kickoff
-- **Crew & 에이전트** — YAML 우선 패턴, 역할, 작업, 위임
+- **Crew & 에이전트** — JSON-first 패턴(`crew.jsonc`, `agents/*.jsonc`), 역할, 작업, 위임
 - **도구 & 통합** — 검색, API, 일반적인 CrewAI 도구 연결
 - **프로젝트 구조** — CLI 스캐폴드 및 저장소 관례와 정렬
 - **최신 패턴** — 스킬이 현재 CrewAI 문서 및 권장 사항을 반영

docs/pt-BR/changelog.mdx

@@ -4,6 +4,248 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="11 jun 2026">
+  ## v1.14.7
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar backends padrão plugáveis para memória, conhecimento, rag e fluxo.
+  - Exibir o verdadeiro finish_reason, parâmetros de amostragem e response.id em eventos LLM.
+  - Tipar os gatilhos DSL como decoradores cientes de rotas.
+  - Adicionar API de chat para fluxos de conversa.
+  - Tornar o backend de bloqueio substituível.
+  - Construir FlowDefinition a partir de metadados Flow DSL.
+  - Adicionar provedor nativo Snowflake Cortex LLM.
+  - Adicionar suporte a arquivos de agentes treinados pela equipe.
+
+  ### Correções de Bugs
+  - Corrigir checkpoint para reconstruir BaseLLM personalizado como LLM concreto na restauração.
+  - Controlar a restauração com uma flag para evitar que snapshots ao vivo sejam reproduzidos como retomar.
+  - Escopar o estado de execução por execução para limitar o crescimento e isolar execuções concorrentes.
+  - Corrigir configuração de telemetria no crewai-login.
+  - Respeitar suppress_flow_events para eventos de execução de método.
+  - Restaurar [project.scripts] no pacote crewai para instalação da ferramenta uv.
+  - Resolver CVEs de pip-audit para aiohttp, docling e docling-core.
+  - Corrigir entrada de arquivo que não estava funcionando de forma confiável.
+  - Corrigir histórias de resultados de ferramentas incompletas do Snowflake Claude.
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.14.7.
+  - Atualizar documentação do coletor OpenTelemetry.
+  - Atualizar guia do LLM NVIDIA Nemotron.
+  - Adicionar guia de integração do Databricks.
+  - Adicionar guia de integração do Snowflake.
+
+  ### Desempenho
+  - Melhorar a velocidade de importação do crewai através do carregamento preguiçoso de imports do docling.
+
+  ### Refatoração
+  - Simplificar a avaliação de condições de fluxo para ser sem estado por evento.
+  - Desacoplar a lógica de conversa da execução e adicionar uma conversational_definition.
+  - Dividir `flow.py` em DSL, definição e execução.
+
+  ## Contribuidores
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="10 jun 2026">
+  ## v1.14.7rc2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Restauração de portão em uma flag para evitar que snapshots ao vivo sejam reproduzidos como retomar
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.14.7rc1
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="10 jun 2026">
+  ## v1.14.7rc1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar `reset_runtime_state` para liberar o estado acumulado do barramento
+  - Lidar com suporte a ambos os prompts personalizados
+  - Desacoplar a lógica de conversa do tempo de execução e adicionar uma `conversational_definition`
+
+  ### Correções de Bugs
+  - Corrigir o escopo do estado de tempo de execução por execução para limitar o crescimento e isolar execuções concorrentes
+  - Corrigir a configuração de telemetria em `crewai-login`
+  - Corrigir o respeito a `suppress_flow_events` para eventos de execução de método
+
+  ### Documentação
+  - Atualizar imagens do OpenTelemetry
+  - Atualizar a documentação para refletir o novo estado do coletor OpenTelemetry
+  - Atualizar o changelog e a versão para v1.14.7a4
+
+  ### Refatoração
+  - Simplificar a avaliação da condição de fluxo para ser sem estado por evento
+  - Melhorar o ciclo de roteamento de conversas com uma rota a menos
+
+  ## Contribuidores
+
+  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
+
+</Update>
+
+<Update label="09 jun 2026">
+  ## v1.14.7a4
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
+
+  ## O Que Mudou
+
+  ### Funcionalidades
+  - Migrar a execução @listen/@router para ler a partir de FlowDefinition
+  - Adicionar backends padrão plugáveis para memória, conhecimento, rag e flow
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.14.7a3
+
+  ## Contributors
+
+  @greysonlalonde, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="08 jun 2026">
+  ## v1.14.7a3
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir a exposição de `ask_for_human_input` no `AgentExecutor` experimental
+  - Resolver CVEs do pip-audit para `aiohttp`, `docling`, `docling-core` e `pip`
+
+  ### Refatoração
+  - Migrar `@start` para ler de `FlowDefinition`
+
+  ### Documentação
+  - Atualizar o changelog e a versão para v1.14.7a2
+
+  ## Contribuidores
+
+  @greysonlalonde, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="05 jun 2026">
+  ## v1.14.7a2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar suporte a rastreamentos de fluxo de conversa.
+  - Atualizar a documentação do fluxo de conversa para utilizar `handle_turn`.
+  - Exibir o real `finish_reason`, parâmetros de amostragem e `response.id` em eventos LLM.
+  - Tipar os gatilhos DSL como decoradores cientes de rota.
+  - Implementar API de chat para fluxos de conversa.
+  - Tornar o backend de bloqueio substituível no armazenamento de bloqueios.
+  - Dividir o monólito DSL de fluxo em módulos de decoradores focados.
+  - Achatar os subcontagens de uso de cache/razão do LiteLLM em `_usage_to_dict`.
+  - Construir `FlowDefinition` a partir dos metadados do Flow DSL.
+
+  ### Documentação
+  - Adicionar guia do LLM NVIDIA Nemotron.
+  - Documentar implantações de monorepo.
+  - Atualizar changelog e versão para v1.14.7a1.
+
+  ## Contribuidores
+
+  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="03 jun 2026">
+  ## v1.14.7a1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a1)
+
+  ## O Que Mudou
+
+  ### Funcionalidades
+  - Adicionar suporte a arquivos de agentes treinados da equipe
+  - Adicionar provedor nativo Snowflake Cortex LLM
+  - Adicionar guia de integração com Databricks
+  - Adicionar guia de integração com Snowflake
+
+  ### Correções de Bugs
+  - Corrigir CLI restaurando `[project.scripts]` no pacote crewai para instalação da ferramenta UV
+  - Resolver problemas de confiabilidade na entrada de arquivos
+  - Corrigir históricos de resultados de ferramentas incompletos no Snowflake Claude
+  - Lidar com chamadas de ferramentas em formato de string para Snowflake Claude
+  - Re-armar ouvintes `or_` de múltiplas fontes em ciclos controlados por roteadores
+
+  ### Desempenho
+  - Melhorar a velocidade de importação do crewai através do carregamento preguiçoso de importações do docling
+
+  ### Refatoração
+  - Dividir `flow.py` em DSL, definição e tempo de execução
+
+  ## Contributors
+
+  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @jessemiller, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="28 mai 2026">
+  ## v1.14.6
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Aprimorar StdioTransport para evitar vazamento de variáveis de ambiente
+  - Aprimorar a configuração de planejamento e o manuseio de observações
+  - Declarar env_vars no DatabricksQueryTool
+  - Adicionar documentação do Agente Control Plane
+
+  ### Correções de Bugs
+  - Corrigir vazamentos de saída estruturada em loops de chamada de ferramenta
+  - Remover callbacks e estado de adaptador que não podem ser retornados em checkpoint
+  - Serializar campos type[BaseModel] como esquema JSON em checkpoint
+  - Evitar tarefa órfã task_started na restauração de escopo de retomar
+  - Permitir que AgentExecutor restaure a partir de checkpoint
+  - Corrigir erro de digitação de mongodb para pymongo em package_dependencies
+
+  ### Documentação
+  - Adicionar bloco de navegação de documentação ACP (Beta) às páginas do Agente Control Plane
+  - Remover referências a processos consensuais da página de processos
+  - Reestruturar a página de checkpointing
+  - Documentar passo de instalação do pacote administrativo único
+  - Migrar Secrets Manager / Workload Identity de replicated-config
+  - Remover expressões JSX `{" "}` que quebram a renderização de `<Steps>`
+
+  ### Refatoração
+  - Mover Skills Repository para experimental + CREWAI_EXPERIMENTAL gate
+
+  ## Contribuidores
+
+  @akaKuruma, @alex-clawd, @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="27 mai 2026">
   ## v1.14.6a2
 

docs/pt-BR/concepts/agents.mdx

@@ -71,13 +71,39 @@ O Construtor Visual de Agentes permite:
 
 ## Criando Agentes
 
-Existem duas maneiras de criar agentes no CrewAI: usando **configuração YAML (recomendado)** ou definindo-os **diretamente em código**.
+Existem duas formas comuns de criar agentes no CrewAI: usando **configuração JSONC (recomendado para novas crews)** ou definindo-os **diretamente em código**.
 
-### Configuração em YAML (Recomendado)
+### Configuração JSONC (Recomendado)
 
-Usar configuração em YAML proporciona uma maneira mais limpa e fácil de manter para definir agentes. Recomendamos fortemente esse método em seus projetos CrewAI.
+Novos projetos criados com `crewai create crew <name>` usam configuração JSON-first. Cada agente fica em `agents/<agent_name>.jsonc`, e `crew.jsonc` lista quais agentes fazem parte da crew.
 
-Depois de criar seu projeto CrewAI conforme descrito na seção de [Instalação](/pt-BR/installation), navegue até o arquivo `src/latest_ai_development/config/agents.yaml` e edite o template para atender aos seus requisitos.
+```jsonc agents/researcher.jsonc
+{
+  "role": "{topic} Senior Data Researcher",
+  "goal": "Uncover cutting-edge developments in {topic}",
+  "backstory": "You find the most relevant information and present it clearly.",
+  "llm": "openai/gpt-4o",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
+```
+
+Use `{placeholder}` em `role`, `goal` ou `backstory`. Defina padrões em `crew.jsonc` dentro de `inputs`; `crewai run` pergunta por valores que estiverem faltando. Campos de comportamento como `verbose`, `allow_delegation`, `max_iter`, `memory`, `cache` e `planning_config` podem ficar no topo ou em `settings`.
+
+<Note>
+JSONC aceita comentários e vírgulas finais. Se `agents/<name>.jsonc` e `agents/<name>.json` existirem, CrewAI usa o arquivo JSONC.
+</Note>
+
+### Configuração YAML Clássica
+
+Projetos clássicos criados com `crewai create crew <name> --classic` usam `config/agents.yaml` e uma classe `@CrewBase` em `crew.py`.
+
+A configuração YAML continua suportada para projetos existentes em Python/YAML e para equipes que preferem definir agentes a partir de uma classe `@CrewBase`.
+
+Depois de criar um projeto clássico, navegue até o arquivo `src/<project_name>/config/agents.yaml` e edite o template para atender aos seus requisitos.
 
 <Note>
 Variáveis em seus arquivos YAML (como `{topic}`) serão substituídas pelos valores fornecidos em seus inputs ao executar o crew:
@@ -89,7 +115,7 @@ crew.kickoff(inputs={'topic': 'AI Agents'})
 Veja um exemplo de como configurar agentes usando YAML:
 
 ```yaml agents.yaml
-# src/latest_ai_development/config/agents.yaml
+# src/<project_name>/config/agents.yaml
 researcher:
   role: >
     {topic} Senior Data Researcher
@@ -114,7 +140,7 @@ reporting_analyst:
 Para usar essa configuração YAML no seu código, crie uma classe de crew que herda de `CrewBase`:
 
 ```python Code
-# src/latest_ai_development/crew.py
+# src/<project_name>/crew.py
 from crewai import Agent, Crew, Process
 from crewai.project import CrewBase, agent, crew
 from crewai_tools import SerperDevTool

docs/pt-BR/concepts/cli.mdx

@@ -53,6 +53,8 @@ crewai create crew my_new_crew
 crewai create flow my_new_flow
 ```
 
+Por padrão, `crewai create crew` cria um projeto JSON-first com `crew.jsonc` e `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` somente quando quiser o scaffold antigo em Python/YAML com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`.
+
 ### 2. Version
 
 Mostre a versão instalada do CrewAI.
@@ -203,7 +205,20 @@ crewai chat
 Garanta que você execute estes comandos a partir do diretório raiz do seu projeto CrewAI.
 </Note>
 <Note>
-IMPORTANTE: Defina a propriedade `chat_llm` no seu arquivo `crew.py` para habilitar este comando.
+IMPORTANTE: Defina a propriedade `chat_llm` na definição da sua crew para habilitar este comando.
+
+Para crews JSON-first, adicione em `crew.jsonc`:
+
+```jsonc
+{
+  "name": "My Crew",
+  "agents": ["researcher"],
+  "tasks": [],
+  "chat_llm": "openai/gpt-4o"
+}
+```
+
+Para crews clássicas Python/YAML, defina em `crew.py`:
 
 ```python
 @crew
@@ -334,7 +349,7 @@ Assista ao vídeo tutorial para uma demonstração passo-a-passo de implantaçã
 
 ### 11. Chaves de API
 
-Ao executar o comando `crewai create crew`, o CLI primeiro mostrará os 5 provedores de LLM mais comuns e pedirá para você selecionar um.
+Ao executar o comando `crewai create crew`, o CLI mostrará provedores de LLM disponíveis e depois a seleção de modelo para o provedor escolhido. O modelo selecionado é salvo no `.env` gerado, e cada agente JSONC pode definir seu próprio `llm`.
 
 Após selecionar um provedor de LLM, será solicitado que você informe as chaves de API.