Merge branch 'main' into lorenze/imp/docs-improvements

* supporting parallel tool use

* ensure we respect max_usage_count

* ensure result_as_answer, hooks, and cache parodity

* improve crew agent executor

* address test comments

.github/codeql/codeql-config.yml

@@ -14,13 +14,18 @@ paths-ignore:
   - "lib/crewai/src/crewai/experimental/a2a/**"
 
 paths:
+  # Include GitHub Actions workflows/composite actions for CodeQL actions analysis
+  - ".github/workflows/**"
+  - ".github/actions/**"
   # Include all Python source code from workspace packages
   - "lib/crewai/src/**"
   - "lib/crewai-tools/src/**"
+  - "lib/crewai-files/src/**"
   - "lib/devtools/src/**"
   # Include tests (but exclude cassettes via paths-ignore)
   - "lib/crewai/tests/**"
   - "lib/crewai-tools/tests/**"
+  - "lib/crewai-files/tests/**"
   - "lib/devtools/tests/**"
 
 # Configure specific queries or packs if needed

.github/dependabot.yml

@@ -5,7 +5,12 @@
 
 version: 2
 updates:
-  - package-ecosystem: uv # See documentation for possible values
-    directory: "/" # Location of package manifests
+  - package-ecosystem: uv
+    directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      security-updates:
+        applies-to: security-updates
+        patterns:
+          - "*"

.github/workflows/codeql.yml

@@ -69,7 +69,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
@@ -98,6 +98,6 @@ jobs:
         exit 1
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/generate-tool-specs.yml

@@ -0,0 +1,63 @@
+name: Generate Tool Specifications
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'lib/crewai-tools/src/crewai_tools/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  generate-specs:
+    runs-on: ubuntu-latest
+    env:
+      PYTHONUNBUFFERED: 1
+
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.CREWAI_TOOL_SPECS_APP_ID }}
+          private_key: ${{ secrets.CREWAI_TOOL_SPECS_PRIVATE_KEY }}
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install the project
+        working-directory: lib/crewai-tools
+        run: uv sync --dev --all-extras
+
+      - name: Generate tool specifications
+        working-directory: lib/crewai-tools
+        run: uv run python src/crewai_tools/generate_tool_specs.py
+
+      - name: Check for changes and commit
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add lib/crewai-tools/tool.specs.json
+
+          if git diff --quiet --staged; then
+            echo "No changes detected in tool.specs.json"
+          else
+            echo "Changes detected in tool.specs.json, committing..."
+            git commit -m "chore: update tool specifications"
+            git push
+          fi

.github/workflows/notify-downstream.yml

@@ -1,33 +0,0 @@
-name: Notify Downstream
-
-on:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-
-jobs:
-  notify-downstream:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Generate GitHub App token
-        id: app-token
-        uses: tibdex/github-app-token@v2
-        with:
-          app_id: ${{ secrets.OSS_SYNC_APP_ID }}
-          private_key: ${{ secrets.OSS_SYNC_APP_PRIVATE_KEY }}
-
-      - name: Notify Repo B
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          repository: ${{ secrets.OSS_SYNC_DOWNSTREAM_REPO }}
-          event-type: upstream-commit
-          client-payload: |
-            {
-              "commit_sha": "${{ github.sha }}"
-            }
-

.gitignore

@@ -26,3 +26,7 @@ plan.md
 conceptual_plan.md
 build_image
 chromadb-*.lock
+.claude
+.crewai/memory
+blogs/*
+secrets/*

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
         language: system
         pass_filenames: true
         types: [python]
-        exclude: ^(lib/crewai/src/crewai/cli/templates/|lib/crewai/tests/|lib/crewai-tools/tests/)
+        exclude: ^(lib/crewai/src/crewai/cli/templates/|lib/crewai/tests/|lib/crewai-tools/tests/|lib/crewai-files/tests/)
   - repo: https://github.com/astral-sh/uv-pre-commit
     rev: 0.9.3
     hooks:

.python-version

@@ -0,0 +1 @@
+3.13

conftest.py

@@ -1,6 +1,8 @@
 """Pytest configuration for crewAI workspace."""
 
+import base64
 from collections.abc import Generator
+import gzip
 import os
 from pathlib import Path
 import tempfile
@@ -10,12 +12,36 @@ from dotenv import load_dotenv
 import pytest
 from vcr.request import Request  # type: ignore[import-untyped]
 
+try:
+    import vcr.stubs.httpx_stubs as httpx_stubs  # type: ignore[import-untyped]
+except ModuleNotFoundError:
+    import vcr.stubs.httpcore_stubs as httpx_stubs  # type: ignore[import-untyped]
+
 
 env_test_path = Path(__file__).parent / ".env.test"
 load_dotenv(env_test_path, override=True)
 load_dotenv(override=True)
 
 
+def _patched_make_vcr_request(httpx_request: Any, **kwargs: Any) -> Any:
+    """Patched version of VCR's _make_vcr_request that handles binary content.
+
+    The original implementation fails on binary request bodies (like file uploads)
+    because it assumes all content can be decoded as UTF-8.
+    """
+    raw_body = httpx_request.read()
+    try:
+        body = raw_body.decode("utf-8")
+    except UnicodeDecodeError:
+        body = base64.b64encode(raw_body).decode("ascii")
+    uri = str(httpx_request.url)
+    headers = dict(httpx_request.headers)
+    return Request(httpx_request.method, uri, body, headers)
+
+
+httpx_stubs._make_vcr_request = _patched_make_vcr_request
+
+
 @pytest.fixture(autouse=True, scope="function")
 def cleanup_event_handlers() -> Generator[None, Any, None]:
     """Clean up event bus handlers after each test to prevent test pollution."""
@@ -31,6 +57,21 @@ def cleanup_event_handlers() -> Generator[None, Any, None]:
         pass
 
 
+@pytest.fixture(autouse=True, scope="function")
+def reset_event_state() -> None:
+    """Reset event system state before each test for isolation."""
+    from crewai.events.base_events import reset_emission_counter
+    from crewai.events.event_context import (
+        EventContextConfig,
+        _event_context_config,
+        _event_id_stack,
+    )
+
+    reset_emission_counter()
+    _event_id_stack.set(())
+    _event_context_config.set(EventContextConfig())
+
+
 @pytest.fixture(autouse=True, scope="function")
 def setup_test_environment() -> Generator[None, Any, None]:
     """Setup test environment for crewAI workspace."""
@@ -133,19 +174,42 @@ def _filter_request_headers(request: Request) -> Request:  # type: ignore[no-any
                 request.headers[variant] = [replacement]
 
     request.method = request.method.upper()
+
+    # Normalize Azure OpenAI endpoints to a consistent placeholder for cassette matching.
+    if request.host and request.host.endswith(".openai.azure.com"):
+        original_host = request.host
+        placeholder_host = "fake-azure-endpoint.openai.azure.com"
+        request.uri = request.uri.replace(original_host, placeholder_host)
+
     return request
 
 
-def _filter_response_headers(response: dict[str, Any]) -> dict[str, Any]:
-    """Filter sensitive headers from response before recording."""
-    # Remove Content-Encoding to prevent decompression issues on replay
+def _filter_response_headers(response: dict[str, Any]) -> dict[str, Any] | None:
+    """Filter sensitive headers from response before recording.
+
+    Returns None to skip recording responses with empty bodies. This handles
+    duplicate recordings caused by OpenAI's stainless client using
+    with_raw_response which triggers httpx to re-read the consumed stream.
+    """
+    body = response.get("body", {}).get("string", "")
+    headers = response.get("headers", {})
+    content_length = headers.get("content-length", headers.get("Content-Length", []))
+
+    if body == "" or body == b"" or content_length == ["0"]:
+        return None
+
     for encoding_header in ["Content-Encoding", "content-encoding"]:
-        response["headers"].pop(encoding_header, None)
+        if encoding_header in headers:
+            encoding = headers.pop(encoding_header)
+            if encoding and encoding[0] == "gzip":
+                body = response.get("body", {}).get("string", b"")
+                if isinstance(body, bytes) and body.startswith(b"\x1f\x8b"):
+                    response["body"]["string"] = gzip.decompress(body).decode("utf-8")
 
     for header_name, replacement in HEADERS_TO_FILTER.items():
         for variant in [header_name, header_name.upper(), header_name.title()]:
-            if variant in response["headers"]:
-                response["headers"][variant] = [replacement]
+            if variant in headers:
+                headers[variant] = [replacement]
     return response
 
 
@@ -160,7 +224,10 @@ def vcr_cassette_dir(request: Any) -> str:
     test_file = Path(request.fspath)
 
     for parent in test_file.parents:
-        if parent.name in ("crewai", "crewai-tools") and parent.parent.name == "lib":
+        if (
+            parent.name in ("crewai", "crewai-tools", "crewai-files")
+            and parent.parent.name == "lib"
+        ):
             package_root = parent
             break
     else:

docs/docs.json

@@ -61,7 +61,9 @@
             "groups": [
               {
                 "group": "Welcome",
-                "pages": ["index"]
+                "pages": [
+                  "index"
+                ]
               }
             ]
           },
@@ -71,40 +73,80 @@
             "groups": [
               {
                 "group": "Get Started",
-                "pages": ["en/introduction", "en/installation", "en/quickstart"]
+                "pages": [
+                  "en/introduction",
+                  "en/installation",
+                  "en/quickstart"
+                ]
               },
               {
-                "group": "Guides",
+                "group": "AI Docs",
                 "pages": [
+                  "en/ai/overview",
                   {
-                    "group": "Strategy",
-                    "icon": "compass",
-                    "pages": ["en/guides/concepts/evaluating-use-cases"]
+                    "group": "Flows",
+                    "icon": "arrow-progress",
+                    "pages": [
+                      "en/ai/flows/index",
+                      "en/ai/flows/reference",
+                      "en/ai/flows/patterns",
+                      "en/ai/flows/troubleshooting",
+                      "en/ai/flows/examples"
+                    ]
                   },
                   {
                     "group": "Agents",
                     "icon": "user",
-                    "pages": ["en/guides/agents/crafting-effective-agents"]
+                    "pages": [
+                      "en/ai/agents/index",
+                      "en/ai/agents/reference",
+                      "en/ai/agents/patterns",
+                      "en/ai/agents/troubleshooting",
+                      "en/ai/agents/examples"
+                    ]
                   },
                   {
                     "group": "Crews",
                     "icon": "users",
-                    "pages": ["en/guides/crews/first-crew"]
-                  },
-                  {
-                    "group": "Flows",
-                    "icon": "code-branch",
                     "pages": [
-                      "en/guides/flows/first-flow",
-                      "en/guides/flows/mastering-flow-state"
+                      "en/ai/crews/index",
+                      "en/ai/crews/reference",
+                      "en/ai/crews/patterns",
+                      "en/ai/crews/troubleshooting",
+                      "en/ai/crews/examples"
                     ]
                   },
                   {
-                    "group": "Advanced",
-                    "icon": "gear",
+                    "group": "LLMs",
+                    "icon": "microchip-ai",
                     "pages": [
-                      "en/guides/advanced/customizing-prompts",
-                      "en/guides/advanced/fingerprinting"
+                      "en/ai/llms/index",
+                      "en/ai/llms/reference",
+                      "en/ai/llms/patterns",
+                      "en/ai/llms/troubleshooting",
+                      "en/ai/llms/examples"
+                    ]
+                  },
+                  {
+                    "group": "Memory",
+                    "icon": "database",
+                    "pages": [
+                      "en/ai/memory/index",
+                      "en/ai/memory/reference",
+                      "en/ai/memory/patterns",
+                      "en/ai/memory/troubleshooting",
+                      "en/ai/memory/examples"
+                    ]
+                  },
+                  {
+                    "group": "Tools",
+                    "icon": "wrench",
+                    "pages": [
+                      "en/ai/tools/index",
+                      "en/ai/tools/reference",
+                      "en/ai/tools/patterns",
+                      "en/ai/tools/troubleshooting",
+                      "en/ai/tools/examples"
                     ]
                   }
                 ]
@@ -119,6 +161,7 @@
                   "en/concepts/production-architecture",
                   "en/concepts/knowledge",
                   "en/concepts/llms",
+                  "en/concepts/files",
                   "en/concepts/processes",
                   "en/concepts/collaboration",
                   "en/concepts/training",
@@ -131,6 +174,55 @@
                   "en/concepts/event-listener"
                 ]
               },
+              {
+                "group": "Guides",
+                "pages": [
+                  {
+                    "group": "Strategy",
+                    "icon": "compass",
+                    "pages": [
+                      "en/guides/concepts/evaluating-use-cases"
+                    ]
+                  },
+                  {
+                    "group": "Agents",
+                    "icon": "user",
+                    "pages": [
+                      "en/guides/agents/crafting-effective-agents"
+                    ]
+                  },
+                  {
+                    "group": "Crews",
+                    "icon": "users",
+                    "pages": [
+                      "en/guides/crews/first-crew"
+                    ]
+                  },
+                  {
+                    "group": "Flows",
+                    "icon": "code-branch",
+                    "pages": [
+                      "en/guides/flows/first-flow",
+                      "en/guides/flows/mastering-flow-state"
+                    ]
+                  },
+                  {
+                    "group": "Coding Tools",
+                    "icon": "terminal",
+                    "pages": [
+                      "en/guides/coding-tools/agents-md"
+                    ]
+                  },
+                  {
+                    "group": "Advanced",
+                    "icon": "gear",
+                    "pages": [
+                      "en/guides/advanced/customizing-prompts",
+                      "en/guides/advanced/fingerprinting"
+                    ]
+                  }
+                ]
+              },
               {
                 "group": "MCP Integration",
                 "pages": [
@@ -279,6 +371,7 @@
                   "en/observability/arize-phoenix",
                   "en/observability/braintrust",
                   "en/observability/datadog",
+                  "en/observability/galileo",
                   "en/observability/langdb",
                   "en/observability/langfuse",
                   "en/observability/langtrace",
@@ -310,6 +403,7 @@
                   "en/learn/human-input-on-execution",
                   "en/learn/human-in-the-loop",
                   "en/learn/human-feedback-in-flows",
+                  "en/learn/flowstate-chat-history",
                   "en/learn/kickoff-async",
                   "en/learn/kickoff-for-each",
                   "en/learn/llm-connections",
@@ -324,7 +418,9 @@
               },
               {
                 "group": "Telemetry",
-                "pages": ["en/telemetry"]
+                "pages": [
+                  "en/telemetry"
+                ]
               }
             ]
           },
@@ -334,7 +430,9 @@
             "groups": [
               {
                 "group": "Getting Started",
-                "pages": ["en/enterprise/introduction"]
+                "pages": [
+                  "en/enterprise/introduction"
+                ]
               },
               {
                 "group": "Build",
@@ -343,7 +441,8 @@
                   "en/enterprise/features/crew-studio",
                   "en/enterprise/features/marketplace",
                   "en/enterprise/features/agent-repositories",
-                  "en/enterprise/features/tools-and-integrations"
+                  "en/enterprise/features/tools-and-integrations",
+                  "en/enterprise/features/pii-trace-redactions"
                 ]
               },
               {
@@ -351,7 +450,8 @@
                 "pages": [
                   "en/enterprise/features/traces",
                   "en/enterprise/features/webhook-streaming",
-                  "en/enterprise/features/hallucination-guardrail"
+                  "en/enterprise/features/hallucination-guardrail",
+                  "en/enterprise/features/flow-hitl-management"
                 ]
               },
               {
@@ -411,7 +511,8 @@
                 "group": "How-To Guides",
                 "pages": [
                   "en/enterprise/guides/build-crew",
-                  "en/enterprise/guides/deploy-crew",
+                  "en/enterprise/guides/prepare-for-deployment",
+                  "en/enterprise/guides/deploy-to-amp",
                   "en/enterprise/guides/kickoff-crew",
                   "en/enterprise/guides/update-crew",
                   "en/enterprise/guides/enable-crew-studio",
@@ -426,7 +527,9 @@
               },
               {
                 "group": "Resources",
-                "pages": ["en/enterprise/resources/frequently-asked-questions"]
+                "pages": [
+                  "en/enterprise/resources/frequently-asked-questions"
+                ]
               }
             ]
           },
@@ -452,7 +555,9 @@
             "groups": [
               {
                 "group": "Examples",
-                "pages": ["en/examples/example", "en/examples/cookbooks"]
+                "pages": [
+                  "en/examples/cookbooks"
+                ]
               }
             ]
           },
@@ -462,7 +567,9 @@
             "groups": [
               {
                 "group": "Release Notes",
-                "pages": ["en/changelog"]
+                "pages": [
+                  "en/changelog"
+                ]
               }
             ]
           }
@@ -501,7 +608,9 @@
             "groups": [
               {
                 "group": "Bem-vindo",
-                "pages": ["pt-BR/index"]
+                "pages": [
+                  "pt-BR/index"
+                ]
               }
             ]
           },
@@ -523,17 +632,23 @@
                   {
                     "group": "Estratégia",
                     "icon": "compass",
-                    "pages": ["pt-BR/guides/concepts/evaluating-use-cases"]
+                    "pages": [
+                      "pt-BR/guides/concepts/evaluating-use-cases"
+                    ]
                   },
                   {
                     "group": "Agentes",
                     "icon": "user",
-                    "pages": ["pt-BR/guides/agents/crafting-effective-agents"]
+                    "pages": [
+                      "pt-BR/guides/agents/crafting-effective-agents"
+                    ]
                   },
                   {
                     "group": "Crews",
                     "icon": "users",
-                    "pages": ["pt-BR/guides/crews/first-crew"]
+                    "pages": [
+                      "pt-BR/guides/crews/first-crew"
+                    ]
                   },
                   {
                     "group": "Flows",
@@ -563,6 +678,7 @@
                   "pt-BR/concepts/production-architecture",
                   "pt-BR/concepts/knowledge",
                   "pt-BR/concepts/llms",
+                  "pt-BR/concepts/files",
                   "pt-BR/concepts/processes",
                   "pt-BR/concepts/collaboration",
                   "pt-BR/concepts/training",
@@ -710,6 +826,7 @@
                   "pt-BR/observability/arize-phoenix",
                   "pt-BR/observability/braintrust",
                   "pt-BR/observability/datadog",
+                  "pt-BR/observability/galileo",
                   "pt-BR/observability/langdb",
                   "pt-BR/observability/langfuse",
                   "pt-BR/observability/langtrace",
@@ -754,7 +871,9 @@
               },
               {
                 "group": "Telemetria",
-                "pages": ["pt-BR/telemetry"]
+                "pages": [
+                  "pt-BR/telemetry"
+                ]
               }
             ]
           },
@@ -764,7 +883,9 @@
             "groups": [
               {
                 "group": "Começando",
-                "pages": ["pt-BR/enterprise/introduction"]
+                "pages": [
+                  "pt-BR/enterprise/introduction"
+                ]
               },
               {
                 "group": "Construir",
@@ -773,7 +894,8 @@
                   "pt-BR/enterprise/features/crew-studio",
                   "pt-BR/enterprise/features/marketplace",
                   "pt-BR/enterprise/features/agent-repositories",
-                  "pt-BR/enterprise/features/tools-and-integrations"
+                  "pt-BR/enterprise/features/tools-and-integrations",
+                  "pt-BR/enterprise/features/pii-trace-redactions"
                 ]
               },
               {
@@ -781,7 +903,8 @@
                 "pages": [
                   "pt-BR/enterprise/features/traces",
                   "pt-BR/enterprise/features/webhook-streaming",
-                  "pt-BR/enterprise/features/hallucination-guardrail"
+                  "pt-BR/enterprise/features/hallucination-guardrail",
+                  "pt-BR/enterprise/features/flow-hitl-management"
                 ]
               },
               {
@@ -825,7 +948,8 @@
                 "group": "Guias",
                 "pages": [
                   "pt-BR/enterprise/guides/build-crew",
-                  "pt-BR/enterprise/guides/deploy-crew",
+                  "pt-BR/enterprise/guides/prepare-for-deployment",
+                  "pt-BR/enterprise/guides/deploy-to-amp",
                   "pt-BR/enterprise/guides/kickoff-crew",
                   "pt-BR/enterprise/guides/update-crew",
                   "pt-BR/enterprise/guides/enable-crew-studio",
@@ -883,7 +1007,10 @@
             "groups": [
               {
                 "group": "Exemplos",
-                "pages": ["pt-BR/examples/example", "pt-BR/examples/cookbooks"]
+                "pages": [
+                  "pt-BR/examples/example",
+                  "pt-BR/examples/cookbooks"
+                ]
               }
             ]
           },
@@ -893,7 +1020,9 @@
             "groups": [
               {
                 "group": "Notas de Versão",
-                "pages": ["pt-BR/changelog"]
+                "pages": [
+                  "pt-BR/changelog"
+                ]
               }
             ]
           }
@@ -932,7 +1061,9 @@
             "groups": [
               {
                 "group": "환영합니다",
-                "pages": ["ko/index"]
+                "pages": [
+                  "ko/index"
+                ]
               }
             ]
           },
@@ -942,7 +1073,11 @@
             "groups": [
               {
                 "group": "시작 안내",
-                "pages": ["ko/introduction", "ko/installation", "ko/quickstart"]
+                "pages": [
+                  "ko/introduction",
+                  "ko/installation",
+                  "ko/quickstart"
+                ]
               },
               {
                 "group": "가이드",
@@ -950,17 +1085,23 @@
                   {
                     "group": "전략",
                     "icon": "compass",
-                    "pages": ["ko/guides/concepts/evaluating-use-cases"]
+                    "pages": [
+                      "ko/guides/concepts/evaluating-use-cases"
+                    ]
                   },
                   {
                     "group": "에이전트 (Agents)",
                     "icon": "user",
-                    "pages": ["ko/guides/agents/crafting-effective-agents"]
+                    "pages": [
+                      "ko/guides/agents/crafting-effective-agents"
+                    ]
                   },
                   {
                     "group": "크루 (Crews)",
                     "icon": "users",
-                    "pages": ["ko/guides/crews/first-crew"]
+                    "pages": [
+                      "ko/guides/crews/first-crew"
+                    ]
                   },
                   {
                     "group": "플로우 (Flows)",
@@ -990,6 +1131,7 @@
                   "ko/concepts/production-architecture",
                   "ko/concepts/knowledge",
                   "ko/concepts/llms",
+                  "ko/concepts/files",
                   "ko/concepts/processes",
                   "ko/concepts/collaboration",
                   "ko/concepts/training",
@@ -1149,6 +1291,7 @@
                   "ko/observability/arize-phoenix",
                   "ko/observability/braintrust",
                   "ko/observability/datadog",
+                  "ko/observability/galileo",
                   "ko/observability/langdb",
                   "ko/observability/langfuse",
                   "ko/observability/langtrace",
@@ -1193,7 +1336,9 @@
               },
               {
                 "group": "Telemetry",
-                "pages": ["ko/telemetry"]
+                "pages": [
+                  "ko/telemetry"
+                ]
               }
             ]
           },
@@ -1203,7 +1348,9 @@
             "groups": [
               {
                 "group": "시작 안내",
-                "pages": ["ko/enterprise/introduction"]
+                "pages": [
+                  "ko/enterprise/introduction"
+                ]
               },
               {
                 "group": "빌드",
@@ -1212,7 +1359,8 @@
                   "ko/enterprise/features/crew-studio",
                   "ko/enterprise/features/marketplace",
                   "ko/enterprise/features/agent-repositories",
-                  "ko/enterprise/features/tools-and-integrations"
+                  "ko/enterprise/features/tools-and-integrations",
+                  "ko/enterprise/features/pii-trace-redactions"
                 ]
               },
               {
@@ -1220,7 +1368,8 @@
                 "pages": [
                   "ko/enterprise/features/traces",
                   "ko/enterprise/features/webhook-streaming",
-                  "ko/enterprise/features/hallucination-guardrail"
+                  "ko/enterprise/features/hallucination-guardrail",
+                  "ko/enterprise/features/flow-hitl-management"
                 ]
               },
               {
@@ -1264,7 +1413,8 @@
                 "group": "How-To Guides",
                 "pages": [
                   "ko/enterprise/guides/build-crew",
-                  "ko/enterprise/guides/deploy-crew",
+                  "ko/enterprise/guides/prepare-for-deployment",
+                  "ko/enterprise/guides/deploy-to-amp",
                   "ko/enterprise/guides/kickoff-crew",
                   "ko/enterprise/guides/update-crew",
                   "ko/enterprise/guides/enable-crew-studio",
@@ -1294,7 +1444,9 @@
               },
               {
                 "group": "학습 자원",
-                "pages": ["ko/enterprise/resources/frequently-asked-questions"]
+                "pages": [
+                  "ko/enterprise/resources/frequently-asked-questions"
+                ]
               }
             ]
           },
@@ -1320,7 +1472,10 @@
             "groups": [
               {
                 "group": "예시",
-                "pages": ["ko/examples/example", "ko/examples/cookbooks"]
+                "pages": [
+                  "ko/examples/example",
+                  "ko/examples/cookbooks"
+                ]
               }
             ]
           },
@@ -1330,7 +1485,9 @@
             "groups": [
               {
                 "group": "릴리스 노트",
-                "pages": ["ko/changelog"]
+                "pages": [
+                  "ko/changelog"
+                ]
               }
             ]
           }
@@ -1397,6 +1554,18 @@
       "source": "/api-reference",
       "destination": "/en/api-reference/introduction"
     },
+    {
+      "source": "/",
+      "destination": "/en/introduction"
+    },
+    {
+      "source": "/en",
+      "destination": "/en/introduction"
+    },
+    {
+      "source": "/en/examples/example",
+      "destination": "/en/examples/cookbooks"
+    },
     {
       "source": "/introduction",
       "destination": "/en/introduction"
@@ -1445,6 +1614,18 @@
       "source": "/enterprise/:path*",
       "destination": "/en/enterprise/:path*"
     },
+    {
+      "source": "/en/enterprise/guides/deploy-crew",
+      "destination": "/en/enterprise/guides/deploy-to-amp"
+    },
+    {
+      "source": "/ko/enterprise/guides/deploy-crew",
+      "destination": "/ko/enterprise/guides/deploy-to-amp"
+    },
+    {
+      "source": "/pt-BR/enterprise/guides/deploy-crew",
+      "destination": "/pt-BR/enterprise/guides/deploy-to-amp"
+    },
     {
       "source": "/api-reference/:path*",
       "destination": "/en/api-reference/:path*"

docs/en/ai/agents/examples.mdx

@@ -0,0 +1,12 @@
+---
+title: "Agents: Examples"
+description: "Runnable examples for robust agent configuration and execution."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Example links
+
+- [/en/guides/agents/crafting-effective-agents](/en/guides/agents/crafting-effective-agents)
+- [/en/learn/customizing-agents](/en/learn/customizing-agents)
+- [/en/learn/coding-agents](/en/learn/coding-agents)

docs/en/ai/agents/index.mdx

@@ -0,0 +1,32 @@
+---
+title: "Agents: Concepts"
+description: "Agent role contracts, task boundaries, and decision criteria for robust agent behavior."
+icon: "user"
+mode: "wide"
+---
+
+## When to use
+
+- You need specialized behavior with explicit role and goal.
+- You need tool-enabled execution under constraints.
+
+## When not to use
+
+- Static transformations are enough without model reasoning.
+- Task can be solved by deterministic code only.
+
+## Core decisions
+
+| Decision | Choose this when |
+|---|---|
+| Single agent | Narrow scope, low coordination needs |
+| Multi-agent crew | Distinct expertise and review loops needed |
+| Tool-enabled agent | Model needs external actions or data |
+
+## Canonical links
+
+- Reference: [/en/ai/agents/reference](/en/ai/agents/reference)
+- Patterns: [/en/ai/agents/patterns](/en/ai/agents/patterns)
+- Troubleshooting: [/en/ai/agents/troubleshooting](/en/ai/agents/troubleshooting)
+- Examples: [/en/ai/agents/examples](/en/ai/agents/examples)
+- Existing docs: [/en/concepts/agents](/en/concepts/agents)

docs/en/ai/agents/patterns.mdx

@@ -0,0 +1,17 @@
+---
+title: "Agents: Patterns"
+description: "Practical agent patterns for role design, tool boundaries, and reliable outputs."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Patterns
+
+1. Role + reviewer pair
+- One agent drafts, one agent validates.
+
+2. Tool-bounded agent
+- Restrict tool list to minimal action set.
+
+3. Structured output agent
+- Force JSON or schema output for automation pipelines.

docs/en/ai/agents/reference.mdx

@@ -0,0 +1,22 @@
+---
+title: "Agents: Reference"
+description: "Reference for agent fields, prompt contracts, tool usage, and output constraints."
+icon: "book"
+mode: "wide"
+---
+
+## Agent contract
+
+- `role`: stable operating identity
+- `goal`: measurable completion objective
+- `backstory`: bounded style and context
+- `tools`: allowed action surface
+
+## Output contract
+
+- Prefer structured outputs for machine workflows.
+- Define failure behavior for missing tool data.
+
+## Canonical source
+
+Primary API details live in [/en/concepts/agents](/en/concepts/agents).

docs/en/ai/agents/troubleshooting.mdx

@@ -0,0 +1,12 @@
+---
+title: "Agents: Troubleshooting"
+description: "Diagnose and fix common agent reliability and instruction-following failures."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+- Hallucinated tool results: require tool-call evidence in output.
+- Prompt drift: tighten role and success criteria.
+- Verbose but low-signal output: enforce concise schema output.

docs/en/ai/crews/examples.mdx

@@ -0,0 +1,12 @@
+---
+title: "Crews: Examples"
+description: "Runnable crew examples for sequential and hierarchical execution."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Example links
+
+- [/en/guides/crews/first-crew](/en/guides/crews/first-crew)
+- [/en/learn/sequential-process](/en/learn/sequential-process)
+- [/en/learn/hierarchical-process](/en/learn/hierarchical-process)

docs/en/ai/crews/index.mdx

@@ -0,0 +1,26 @@
+---
+title: "Crews: Concepts"
+description: "When to use crews, process selection, delegation boundaries, and collaboration strategy."
+icon: "users"
+mode: "wide"
+---
+
+## When to use
+
+- You need multiple agents with specialized roles.
+- You need staged execution and reviewer loops.
+
+## Process decision table
+
+| Process | Best for |
+|---|---|
+| Sequential | Linear pipelines and deterministic ordering |
+| Hierarchical | Manager-controlled planning and delegation |
+
+## Canonical links
+
+- Reference: [/en/ai/crews/reference](/en/ai/crews/reference)
+- Patterns: [/en/ai/crews/patterns](/en/ai/crews/patterns)
+- Troubleshooting: [/en/ai/crews/troubleshooting](/en/ai/crews/troubleshooting)
+- Examples: [/en/ai/crews/examples](/en/ai/crews/examples)
+- Existing docs: [/en/concepts/crews](/en/concepts/crews)

docs/en/ai/crews/patterns.mdx

@@ -0,0 +1,12 @@
+---
+title: "Crews: Patterns"
+description: "Production crew patterns for decomposition, review loops, and hybrid orchestration with Flows."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Patterns
+
+1. Researcher + writer + reviewer
+2. Manager-directed hierarchical crew
+3. Flow-orchestrated multi-crew pipeline

docs/en/ai/crews/reference.mdx

@@ -0,0 +1,21 @@
+---
+title: "Crews: Reference"
+description: "Reference for crew composition, process semantics, task context passing, and execution modes."
+icon: "book"
+mode: "wide"
+---
+
+## Crew contract
+
+- `agents`: available executors
+- `tasks`: work units with expected output
+- `process`: ordering and delegation semantics
+
+## Runtime
+
+- `kickoff()` for synchronous runs
+- `kickoff_async()` for async execution
+
+## Canonical source
+
+Primary API details live in [/en/concepts/crews](/en/concepts/crews).

docs/en/ai/crews/troubleshooting.mdx

@@ -0,0 +1,12 @@
+---
+title: "Crews: Troubleshooting"
+description: "Common multi-agent coordination failures and practical fixes."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+- Agents overlap on responsibilities: tighten role boundaries.
+- Output inconsistency: standardize expected outputs per task.
+- Slow runs: reduce unnecessary handoffs and model size.

docs/en/ai/flows/examples.mdx

@@ -0,0 +1,17 @@
+---
+title: "Flows: Examples"
+description: "Runnable end-to-end examples for production flow orchestration."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Canonical examples
+
+<CardGroup cols={2}>
+  <Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
+    Persistent chat history with summary compaction and memory scope.
+  </Card>
+  <Card title="Flows Concepts Example" icon="arrow-progress" href="/en/concepts/flows">
+    Full API and feature-oriented flow examples, including routers and persistence.
+  </Card>
+</CardGroup>

docs/en/ai/flows/index.mdx

@@ -0,0 +1,39 @@
+---
+title: "Flows: Concepts"
+description: "When to use Flows, when not to use them, and key design constraints for production orchestration."
+icon: "arrow-progress"
+mode: "wide"
+---
+
+## When to use
+
+- You need deterministic orchestration, branching, and resumable execution.
+- You need explicit state transitions across steps.
+- You need persistence, routing, and event-driven control.
+
+## When not to use
+
+- A single prompt/response interaction is enough.
+- You only need one agent call without orchestration logic.
+
+## Core decisions
+
+| Decision | Choose this when |
+|---|---|
+| Unstructured state | Fast prototyping, highly dynamic fields |
+| Structured state | Stable contracts, team development, type safety |
+| `@persist()` | Long-running workflows and recovery requirements |
+| Router labels | Deterministic branch handling |
+
+## Canonical links
+
+- Reference: [/en/ai/flows/reference](/en/ai/flows/reference)
+- Patterns: [/en/ai/flows/patterns](/en/ai/flows/patterns)
+- Troubleshooting: [/en/ai/flows/troubleshooting](/en/ai/flows/troubleshooting)
+- Examples: [/en/ai/flows/examples](/en/ai/flows/examples)
+
+## Existing docs
+
+- [/en/concepts/flows](/en/concepts/flows)
+- [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)
+- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)

docs/en/ai/flows/patterns.mdx

@@ -0,0 +1,29 @@
+---
+title: "Flows: Patterns"
+description: "Production flow patterns: triage routing, flowstate chat history, and human-in-the-loop checkpoints."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Recommended patterns
+
+1. Triage router flow
+- Inputs: normalized request payload
+- Output: deterministic route label + action
+- Reference: [/en/concepts/flows](/en/concepts/flows)
+
+2. Flowstate chat history
+- Inputs: `session_id`, `last_user_message`
+- Output: assistant reply + compact context state
+- Reference: [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
+
+3. Human feedback gates
+- Inputs: generated artifact + reviewer feedback
+- Output: approved/rejected/revision path
+- Reference: [/en/learn/human-feedback-in-flows](/en/learn/human-feedback-in-flows)
+
+## Pattern requirements
+
+- declare explicit input schema
+- define expected output shape
+- list failure modes and retries

docs/en/ai/flows/reference.mdx

@@ -0,0 +1,34 @@
+---
+title: "Flows: Reference"
+description: "API-oriented reference for Flow decorators, lifecycle semantics, state, routing, and persistence."
+icon: "book"
+mode: "wide"
+---
+
+## Decorators
+
+- `@start()` entrypoint, optional conditional trigger
+- `@listen(...)` downstream method subscription
+- `@router(...)` label-based deterministic routing
+- `@persist()` automatic state persistence checkpoints
+
+## Runtime contracts
+
+- `kickoff(inputs=...)` initializes or updates run inputs.
+- final output is the value from the last completed method.
+- `self.state` always has an auto-generated `id`.
+
+## State contracts
+
+- Use typed state for durable workflows.
+- Keep control fields explicit (`route`, `status`, `retry_count`).
+- Avoid storing unbounded raw transcripts in state.
+
+## Resume and recovery
+
+- Use persistence for recoverable runs.
+- Keep idempotent step logic for safe retries.
+
+## Canonical source
+
+Primary API details live in [/en/concepts/flows](/en/concepts/flows).

docs/en/ai/flows/troubleshooting.mdx

@@ -0,0 +1,28 @@
+---
+title: "Flows: Troubleshooting"
+description: "Common flow failures, causes, and fixes for state, routing, persistence, and resumption."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+### Branch did not trigger
+
+- Cause: router label mismatch.
+- Fix: align returned label with `@listen("label")` exactly.
+
+### State fields missing
+
+- Cause: untyped dynamic writes or missing inputs.
+- Fix: switch to typed state and validate required fields at `@start()`.
+
+### Context window blow-up
+
+- Cause: raw message accumulation.
+- Fix: use sliding window + summary compaction pattern.
+
+### Resume behavior inconsistent
+
+- Cause: non-idempotent side effects in retried steps.
+- Fix: make side-effecting calls idempotent and record execution markers in state.

docs/en/ai/llms/examples.mdx

@@ -0,0 +1,12 @@
+---
+title: "LLMs: Examples"
+description: "Concrete examples for model setup, routing, and output-control patterns."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Example links
+
+- [/en/concepts/llms](/en/concepts/llms)
+- [/en/learn/llm-connections](/en/learn/llm-connections)
+- [/en/learn/custom-llm](/en/learn/custom-llm)

docs/en/ai/llms/index.mdx

@@ -0,0 +1,27 @@
+---
+title: "LLMs: Concepts"
+description: "Model selection strategy, cost-quality tradeoffs, and reliability posture for CrewAI systems."
+icon: "microchip-ai"
+mode: "wide"
+---
+
+## When to use advanced LLM configuration
+
+- You need predictable quality, latency, and cost control.
+- You need model routing by task type.
+
+## Core decisions
+
+| Decision | Choose this when |
+|---|---|
+| Single model | Small systems with uniform task profile |
+| Routed models | Mixed workloads with different quality/cost needs |
+| Structured output | Automation pipelines and strict parsing needs |
+
+## Canonical links
+
+- Reference: [/en/ai/llms/reference](/en/ai/llms/reference)
+- Patterns: [/en/ai/llms/patterns](/en/ai/llms/patterns)
+- Troubleshooting: [/en/ai/llms/troubleshooting](/en/ai/llms/troubleshooting)
+- Examples: [/en/ai/llms/examples](/en/ai/llms/examples)
+- Existing docs: [/en/concepts/llms](/en/concepts/llms)

docs/en/ai/llms/patterns.mdx

@@ -0,0 +1,17 @@
+---
+title: "LLMs: Patterns"
+description: "Model routing, reliability defaults, and structured outputs for production AI workflows."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Patterns
+
+1. Role-based model routing
+2. Reliability defaults (`timeout`, `max_retries`, low temperature)
+3. JSON-first outputs for machine consumption
+4. Responses API for multi-turn reasoning flows
+
+## Reference
+
+- [/en/concepts/llms#production-llm-patterns](/en/concepts/llms#production-llm-patterns)

docs/en/ai/llms/reference.mdx

@@ -0,0 +1,25 @@
+---
+title: "LLMs: Reference"
+description: "Provider-agnostic LLM configuration reference for CrewAI projects."
+icon: "book"
+mode: "wide"
+---
+
+## Common parameters
+
+- `model`
+- `temperature`
+- `max_tokens`
+- `timeout`
+- `max_retries`
+- `response_format`
+
+## Contract guidance
+
+- Set low temperature for extraction/classification.
+- Use structured outputs for downstream automation.
+- Set explicit timeout and retry policy for production.
+
+## Canonical source
+
+Primary API details live in [/en/concepts/llms](/en/concepts/llms).

docs/en/ai/llms/troubleshooting.mdx

@@ -0,0 +1,12 @@
+---
+title: "LLMs: Troubleshooting"
+description: "Fix common model behavior failures: drift, latency spikes, malformed output, and cost overruns."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+- Malformed JSON: enforce `response_format` and validate at boundary.
+- Latency spikes: route heavy tasks to smaller models when acceptable.
+- Cost growth: add budget-aware model routing and truncation rules.

docs/en/ai/memory/examples.mdx

@@ -0,0 +1,11 @@
+---
+title: "Memory: Examples"
+description: "Runnable examples for scoped storage and semantic retrieval in CrewAI."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Example links
+
+- [/en/concepts/memory](/en/concepts/memory)
+- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)

docs/en/ai/memory/index.mdx

@@ -0,0 +1,24 @@
+---
+title: "Memory: Concepts"
+description: "Designing recall systems with scope boundaries and state-vs-memory separation."
+icon: "database"
+mode: "wide"
+---
+
+## When to use memory
+
+- You need semantic recall across runs.
+- You need long-term context outside immediate flow state.
+
+## When to use state instead
+
+- Data is only needed for current control flow.
+- Data must remain deterministic and explicit per step.
+
+## Canonical links
+
+- Reference: [/en/ai/memory/reference](/en/ai/memory/reference)
+- Patterns: [/en/ai/memory/patterns](/en/ai/memory/patterns)
+- Troubleshooting: [/en/ai/memory/troubleshooting](/en/ai/memory/troubleshooting)
+- Examples: [/en/ai/memory/examples](/en/ai/memory/examples)
+- Existing docs: [/en/concepts/memory](/en/concepts/memory)

docs/en/ai/memory/patterns.mdx

@@ -0,0 +1,17 @@
+---
+title: "Memory: Patterns"
+description: "Practical memory patterns for session recall, scoped retrieval, and hybrid flow-state designs."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Patterns
+
+1. Session-scoped recall (`/chat/{session_id}`)
+2. Project-scoped knowledge (`/project/{project_id}`)
+3. Hybrid pattern: flow state for control, memory for long-tail context
+
+## Reference
+
+- [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
+- [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)

docs/en/ai/memory/reference.mdx

@@ -0,0 +1,23 @@
+---
+title: "Memory: Reference"
+description: "Reference for remember/recall contracts, scopes, and retrieval tuning."
+icon: "book"
+mode: "wide"
+---
+
+## API surface
+
+- `remember(content, scope=...)`
+- `recall(query, limit=...)`
+- `extract_memories(text)`
+- `scope(path)` and `subscope(name)`
+
+## Scope rules
+
+- use `/{entity_type}/{identifier}` paths
+- keep hierarchy shallow
+- isolate sessions by stable identifiers
+
+## Canonical source
+
+Primary API details live in [/en/concepts/memory](/en/concepts/memory).

docs/en/ai/memory/troubleshooting.mdx

@@ -0,0 +1,12 @@
+---
+title: "Memory: Troubleshooting"
+description: "Diagnose poor recall quality, scope leakage, and stale memory retrieval."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+- Irrelevant recall: tighten scopes and query wording.
+- Missing recall: check scope path and recency weighting.
+- Scope leakage: avoid shared broad scopes for unrelated workflows.

docs/en/ai/overview.mdx

@@ -0,0 +1,54 @@
+---
+title: "AI-First Documentation"
+description: "Canonical, agent-optimized documentation map for Flows, Agents, Crews, LLMs, Memory, and Tools."
+icon: "sitemap"
+mode: "wide"
+---
+
+## Purpose
+
+This section is the canonical map for AI agents and developers.
+
+Use it when you need:
+- one source of truth per domain
+- predictable page structure
+- runnable patterns with explicit inputs and outputs
+
+## Domain Packs
+
+<CardGroup cols={3}>
+  <Card title="Flows" icon="arrow-progress" href="/en/ai/flows/index">
+    State, routing, persistence, resume, and orchestration lifecycle.
+  </Card>
+  <Card title="Agents" icon="user" href="/en/ai/agents/index">
+    Agent contracts, tool boundaries, prompt roles, and output discipline.
+  </Card>
+  <Card title="Crews" icon="users" href="/en/ai/crews/index">
+    Multi-agent execution, process choice, delegation, and coordination.
+  </Card>
+  <Card title="LLMs" icon="microchip-ai" href="/en/ai/llms/index">
+    Model configuration contracts, routing, reliability defaults, and providers.
+  </Card>
+  <Card title="Memory" icon="database" href="/en/ai/memory/index">
+    Retrieval semantics, scope design, and state-vs-memory architecture.
+  </Card>
+  <Card title="Tools" icon="wrench" href="/en/ai/tools/index">
+    Tool safety, schema contracts, retries, and integration patterns.
+  </Card>
+</CardGroup>
+
+## Writing Contract
+
+Every domain follows the same structure:
+1. Concepts (`index`)
+2. Reference (`reference`)
+3. Patterns (`patterns`)
+4. Troubleshooting (`troubleshooting`)
+5. Examples (`examples`)
+
+## Deprecation Policy
+
+When a page is replaced:
+- keep a redirect for the old URL
+- keep one canonical destination
+- avoid duplicated conceptual prose

docs/en/ai/tools/examples.mdx

@@ -0,0 +1,12 @@
+---
+title: "Tools: Examples"
+description: "Practical examples for tool-driven agents and crews."
+icon: "rocket-launch"
+mode: "wide"
+---
+
+## Example links
+
+- [/en/tools/overview](/en/tools/overview)
+- [/en/learn/create-custom-tools](/en/learn/create-custom-tools)
+- [/en/learn/tool-hooks](/en/learn/tool-hooks)

docs/en/ai/tools/index.mdx

@@ -0,0 +1,25 @@
+---
+title: "Tools: Concepts"
+description: "Tool selection strategy, safety boundaries, and reliability rules for agentic execution."
+icon: "wrench"
+mode: "wide"
+---
+
+## When to use tools
+
+- Agents need external data or side effects.
+- Deterministic systems must be integrated into agent workflows.
+
+## Tool safety rules
+
+- define clear input schemas
+- validate outputs before downstream use
+- isolate privileged tools behind policy checks
+
+## Canonical links
+
+- Reference: [/en/ai/tools/reference](/en/ai/tools/reference)
+- Patterns: [/en/ai/tools/patterns](/en/ai/tools/patterns)
+- Troubleshooting: [/en/ai/tools/troubleshooting](/en/ai/tools/troubleshooting)
+- Examples: [/en/ai/tools/examples](/en/ai/tools/examples)
+- Existing docs: [/en/concepts/tools](/en/concepts/tools)

docs/en/ai/tools/patterns.mdx

@@ -0,0 +1,12 @@
+---
+title: "Tools: Patterns"
+description: "Tool execution patterns for retrieval, action safety, and response grounding."
+icon: "diagram-project"
+mode: "wide"
+---
+
+## Patterns
+
+1. Read-first then write pattern
+2. Validation gate before side effects
+3. Fallback tool chains for degraded mode

docs/en/ai/tools/reference.mdx

@@ -0,0 +1,22 @@
+---
+title: "Tools: Reference"
+description: "Reference for tool invocation contracts, argument schemas, and runtime safeguards."
+icon: "book"
+mode: "wide"
+---
+
+## Tool contract
+
+- deterministic input schema
+- stable output schema
+- explicit error behavior
+
+## Runtime safeguards
+
+- timeout and retry policy
+- idempotency for side effects
+- validation before commit
+
+## Canonical source
+
+Primary API details live in [/en/concepts/tools](/en/concepts/tools).

docs/en/ai/tools/troubleshooting.mdx

@@ -0,0 +1,12 @@
+---
+title: "Tools: Troubleshooting"
+description: "Common tool-call failures and fixes for schema mismatch, retries, and side effects."
+icon: "circle-exclamation"
+mode: "wide"
+---
+
+## Common issues
+
+- Schema mismatch: align tool args with declared model output schema.
+- Repeated side effects: add idempotency keys.
+- Tool timeouts: define retries with bounded backoff.

docs/en/changelog.mdx

@@ -4,6 +4,584 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Jan 26, 2026">
+  ## v1.9.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.9.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add structured outputs and response_format support across providers
+  - Add response ID to streaming responses
+  - Add event ordering with parent-child hierarchies
+  - Add Keycloak SSO authentication support
+  - Add multimodal file handling capabilities
+  - Add native OpenAI responses API support
+  - Add A2A task execution utilities
+  - Add A2A server configuration and agent card generation
+  - Enhance event system and expand transport options
+  - Improve tool calling mechanisms
+
+  ### Bug Fixes
+  - Enhance file store with fallback memory cache when aiocache is not available
+  - Ensure document list is not empty
+  - Handle Bedrock stop sequences properly
+  - Add Google Vertex API key support
+  - Enhance Azure model stop word detection
+  - Improve error handling for HumanFeedbackPending in flow execution
+  - Fix execution span task unlinking
+
+  ### Documentation
+  - Add native file handling documentation
+  - Add OpenAI responses API documentation
+  - Add agent card implementation guidance
+  - Refine A2A documentation
+  - Update changelog for v1.8.0
+
+  ### Contributors
+  @Anaisdg, @GininDenis, @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @koushiv777, @lorenzejay, @nicoferdi96, @vinibrsl
+
+</Update>
+
+<Update label="Jan 15, 2026">
+  ## v1.8.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.8.1)
+
+  ## What's Changed
+
+  ### Features
+  - Add A2A task execution utilities
+  - Add A2A server configuration and agent card generation
+  - Add additional transport mechanisms
+  - Add Galileo integration support
+
+  ### Bug Fixes
+  - Improve Azure model compatibility
+  - Expand frame inspection depth to detect parent_flow
+  - Resolve task execution span management issues
+  - Enhance error handling for human feedback scenarios during flow execution
+
+  ### Documentation
+  - Add A2A agent card documentation
+  - Add PII redaction feature documentation
+
+  ### Contributors
+  @Anaisdg, @GininDenis, @greysonlalonde, @joaomdmoura, @koushiv777, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="Jan 08, 2026">
+  ## v1.8.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.8.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add native async chain for a2a
+  - Add a2a update mechanisms (poll/stream/push) with handlers and config
+  - Introduce global flow configuration for human-in-the-loop feedback
+  - Add streaming tool call events and fix provider ID tracking
+  - Introduce production-ready Flows and Crews architecture
+  - Add HITL for Flows
+  - Improve EventListener and TraceCollectionListener for enhanced event handling
+
+  ### Bug Fixes
+  - Handle missing a2a dependency as optional
+  - Correct error fetching for WorkOS login polling
+  - Fix wrong trigger name in sample documentation
+
+  ### Documentation
+  - Update webhook-streaming documentation
+  - Adjust AOP to AMP documentation language
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta
+
+</Update>
+
+<Update label="Dec 19, 2025">
+  ## v1.7.2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.7.2)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Resolve connection issues
+
+  ### Documentation
+  - Update api-reference/status docs page
+
+  ### Contributors
+  @greysonlalonde, @heitorado, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="Dec 16, 2025">
+  ## v1.7.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.7.1)
+
+  ## What's Changed
+
+  ### Improvements
+  - Add `--no-commit` flag to bump command
+  - Use JSON schema for tool argument serialization
+
+  ### Bug Fixes
+  - Fix error message display from response when tool repository login fails
+  - Fix graceful termination of future when executing a task asynchronously
+  - Fix task ordering by adding index
+  - Fix platform compatibility checks for Windows signals
+  - Fix RPM controller timer to prevent process hang
+  - Fix token usage recording and validate response model on stream
+
+  ### Documentation
+  - Add translated documentation for async
+  - Add documentation for AOP Deploy API
+  - Add documentation for the agent handler connector
+  - Add documentation on native async
+
+  ### Contributors
+  @Llamrei, @dragosmc, @gilfeig, @greysonlalonde, @heitorado, @lorenzejay, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="Dec 09, 2025">
+  ## v1.7.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.7.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add async flow kickoff
+  - Add async crew support
+  - Add async task support
+  - Add async knowledge support
+  - Add async memory support
+  - Add async support for tools and agent executor; improve typing and docs
+  - Implement a2a extensions API and async agent card caching; fix task propagation & streaming
+  - Add native async tool support
+  - Add async llm support
+  - Create sys event types and handler
+
+  ### Bug Fixes
+  - Fix issue to ensure nonetypes are not passed to otel
+  - Fix deadlock in token store file operations
+  - Fix to ensure otel span is closed
+  - Use HuggingFaceEmbeddingFunction for embeddings, update keys and add tests
+  - Fix to ensure supports_tools is true for all supported anthropic models
+  - Ensure hooks work with lite agents flows
+
+  ### Contributors
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="Nov 29, 2025">
+  ## v1.6.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.6.1)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix ChatCompletionsClient call to ensure proper functionality
+  - Ensure async methods are executable for annotations
+  - Fix parameters in RagTool.add, add typing, and tests
+  - Remove invalid parameter from SSE client
+  - Erase 'oauth2_extra' setting on 'crewai config reset' command
+
+  ### Refactoring
+  - Enhance model validation and provider inference in LLM class
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @lorenzejay
+
+</Update>
+
+<Update label="Nov 25, 2025">
+  ## v1.6.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.6.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add streaming result support to flows and crews
+  - Add gemini-3-pro-preview
+  - Support CLI login with Entra ID
+  - Add Merge Agent Handler tool
+  - Enhance flow event state management
+
+  ### Bug Fixes
+  - Ensure custom rag store persist path is set if passed
+  - Ensure fuzzy returns are more strict and show type warning
+  - Re-add openai response_format parameter and add test
+  - Fix rag tool embeddings configuration
+  - Ensure flow execution start panel is not shown on plot
+
+  ### Documentation
+  - Update references from AMP to AOP in documentation
+  - Update AMP to AOP
+
+  ### Contributors
+  @Vidit-Ostwal, @gilfeig, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @markmcd
+
+</Update>
+
+<Update label="Nov 22, 2025">
+  ## v0.203.2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.203.2)
+
+  ## What's Changed
+
+  - Hotfix version bump from 0.203.1 to 0.203.2
+
+</Update>
+
+<Update label="Nov 16, 2025">
+  ## v1.5.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.5.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add a2a trust remote completion status flag
+  - Fetch and store more data about Okta authorization server
+  - Implement before and after LLM call hooks in CrewAgentExecutor
+  - Expose messages to TaskOutput and LiteAgentOutputs
+  - Enhance schema description of QdrantVectorSearchTool
+
+  ### Bug Fixes
+  - Ensure tracing instrumentation flags are correctly applied
+  - Fix custom tool documentation links and add Mintlify broken links action
+
+  ### Documentation
+  - Enhance task guardrail documentation with LLM-based validation support
+
+  ### Contributors
+  @danielfsbarreto, @greysonlalonde, @heitorado, @lorenzejay, @theCyberTech
+
+</Update>
+
+<Update label="Nov 07, 2025">
+  ## v1.4.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.4.1)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix handling of agent max iterations
+  - Resolve routing issues for LLM model syntax to respected providers
+
+  ### Contributors
+  @greysonlalonde
+
+</Update>
+
+<Update label="Nov 07, 2025">
+  ## v1.4.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.4.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add support for non-AST plot routes
+  - Implement first-class support for MCP
+  - Add Pydantic validation dunder to BaseInterceptor
+  - Add support for LLM message interceptor hooks
+  - Cache i18n prompts for efficient use
+  - Enhance QdrantVectorSearchTool
+
+  ### Bug Fixes
+  - Fix issues with keeping stopwords updated
+  - Resolve unpickleable values in flow state
+  - Ensure lite agents course-correct on validation errors
+  - Fix callback argument hashing to ensure caching works
+  - Allow adding RAG source content from valid URLs
+  - Make plot node selection smoother
+  - Fix duplicating document IDs for knowledge
+
+  ### Refactoring
+  - Improve MCP tool execution handling with concurrent futures
+  - Simplify flow handling, typing, and logging; update UI and tests
+  - Refactor stop word management to a property
+
+  ### Documentation
+  - Migrate embedder to embedding_model and require vectordb across tool docs; add provider examples (en/ko/pt-BR)
+
+  ### Contributors
+  @danielfsbarreto, @greysonlalonde, @lorenzejay, @lucasgomide, @tonykipkemboi
+
+</Update>
+
+<Update label="Nov 01, 2025">
+  ## v1.3.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.3.0)
+
+  ## What's Changed
+
+  ### Features
+  - Refactor flow handling, typing, and logging
+  - Enhance QdrantVectorSearchTool
+
+  ### Bug Fixes
+  - Fix Firecrawl tools and add tests
+  - Refactor use_stop_words to property and add check for stop words
+
+  ### Documentation
+  - Migrate embedder to embedding_model and require vectordb across tool docs
+  - Add provider examples in English, Korean, and Portuguese
+
+  ### Refactoring
+  - Improve flow handling and UI updates
+
+  ### Contributors
+  @danielfsbarreto, @greysonlalonde, @lorenzejay, @lucasgomide, @tonykipkemboi
+
+</Update>
+
+<Update label="Oct 27, 2025">
+  ## v1.2.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.2.1)
+
+  ## What's Changed
+
+  ### Features
+  - Add support for Datadog integration
+  - Support apps and mcps in liteagent
+
+  ### Documentation
+  - Describe mandatory environment variable for calling Platform tools for each integration
+  - Add Datadog integration documentation
+
+  ### Contributors
+  @barieom, @lorenzejay, @lucasgomide, @sabrenner
+
+</Update>
+
+<Update label="Oct 24, 2025">
+  ## v1.2.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.2.0)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Update default LLM model and improve error logging in LLM utilities
+  - Change flow visualization directory and method inspection
+
+  ### Dropping Unused
+  - Remove aisuite
+
+  ### Contributors
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="Oct 21, 2025">
+  ## v1.1.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.1.0)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance InternalInstructor to support multiple LLM providers
+  - Implement mypy plugin base
+  - Improve QdrantVectorSearchTool
+
+  ### Bug Fixes
+  - Correct broken integration documentation links
+  - Fix double trace call and add types
+  - Pin template versions to latest
+
+  ### Documentation
+  - Update LLM integration details and examples
+
+  ### Refactoring
+  - Improve CrewBase typing
+
+  ### Contributors
+  @cwarre33, @danielfsbarreto, @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="Oct 20, 2025">
+  ## v1.0.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0)
+
+  ## What's Changed
+
+  ### Features
+  - Bump versions to 1.0.0
+  - Enhance knowledge and guardrail event handling in Agent class
+  - Inject tool repository credentials in crewai run command
+
+  ### Bug Fixes
+  - Preserve nested condition structure in Flow decorators
+  - Add standard print parameters to Printer.print method
+  - Fix errors when there is no input() available
+  - Add a leeway of 10s when decoding JWT
+  - Revert bad cron schedule
+  - Correct cron schedule to run every 5 days at specific dates
+  - Use system PATH for Docker binary instead of hardcoded path
+  - Add CodeQL configuration to properly exclude template directories
+
+  ### Documentation
+  - Update security policy for vulnerability reporting
+  - Add guide for capturing telemetry logs in CrewAI AMP
+  - Add missing /resume files
+  - Clarify webhook URL parameter in HITL workflows
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta, @theCyberTech
+
+</Update>
+
+<Update label="Oct 18, 2025">
+  ## v1.0.0b3 (Pre-release)
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b3)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance task guardrail functionality and validation
+  - Improve support for importing native SDK
+  - Add Azure native tests
+  - Enhance BedrockCompletion class with advanced features
+  - Enhance GeminiCompletion class with client parameter support
+  - Enhance AnthropicCompletion class with additional client parameters
+
+  ### Bug Fixes
+  - Preserve nested condition structure in Flow decorators
+  - Add standard print parameters to Printer.print method
+  - Remove stdout prints and improve test determinism
+
+  ### Refactoring
+  - Convert project module to metaclass with full typing
+
+  ### Contributors
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="Oct 16, 2025">
+  ## v1.0.0b2 (Pre-release)
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b2)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance OpenAICompletion class with additional client parameters
+  - Improve event bus thread safety and async support
+  - Inject tool repository credentials in crewai run command
+
+  ### Bug Fixes
+  - Fix issue where it errors out if there is no input() available
+  - Add a leeway of 10s when decoding JWT
+  - Fix copying and adding NOT_SPECIFIED check in task.py
+
+  ### Documentation
+  - Ensure CREWAI_PLATFORM_INTEGRATION_TOKEN is mentioned in documentation
+  - Update triggers documentation
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="Oct 14, 2025">
+  ## v1.0.0b1 (Pre-release)
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b1)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance OpenAICompletion class with additional client parameters
+  - Improve event bus thread safety and async support
+  - Implement Bedrock LLM integration
+
+  ### Bug Fixes
+  - Fix issue with missing input() availability
+  - Resolve JWT decoding error by adding a leeway of 10 seconds
+  - Inject tool repository credentials in crewai run command
+  - Fix copy and add NOT_SPECIFIED check in task.py
+
+  ### Documentation
+  - Ensure CREWAI_PLATFORM_INTEGRATION_TOKEN is mentioned in documentation
+  - Update triggers documentation
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="Oct 13, 2025">
+  ## v0.203.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/0.203.1)
+
+  ## What's Changed
+
+  ### Core Improvements & Fixes
+  - Fixed injection of tool repository credentials into the `crewai run` command
+  - Added a 10-second leeway when decoding JWTs to reduce token validation errors
+  - Corrected (then reverted) cron schedule fix intended to run jobs every 5 days at specific dates
+
+  ### Documentation & Guides
+  - Updated security policy to clarify the process for vulnerability reporting
+
+</Update>
+
+<Update label="Oct 09, 2025">
+  ## v1.0.0a4 (Pre-release)
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0a4)
+
+  ## What's Changed
+
+  ### Features
+  - Enhance knowledge and guardrail event handling in Agent class
+  - Introduce trigger listing and execution commands for local development
+  - Update documentation with new approach to consume Platform Actions
+  - Add guide for capturing telemetry logs in CrewAI AMP
+
+  ### Bug Fixes
+  - Revert bad cron schedule
+  - Correct cron schedule to run every 5 days at specific dates
+  - Remove duplicate line and add explicit environment variable
+  - Resolve linting errors across the codebase
+  - Replace print statements with logger in agent and memory handling
+  - Use system PATH for Docker binary instead of hardcoded path
+  - Allow failed PyPI publish
+  - Match tag and release title, ignore devtools build for PyPI
+
+  ### Documentation
+  - Update security policy for vulnerability reporting
+  - Add missing /resume files
+  - Clarify webhook URL parameter in HITL workflows
+
+  ### Contributors
+  @Vidit-Ostwal, @greysonlalonde, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
 <Update label="Sep 30, 2025">
   ## v1.0.0a1
 

docs/en/concepts/agents.mdx

@@ -23,6 +23,17 @@ In the CrewAI framework, an `Agent` is an autonomous unit that can:
   at creating content.
 </Tip>
 
+## When to Use Agents
+
+- You need role-specific reasoning and decision-making.
+- You need tool-enabled execution with delegated responsibilities.
+- You need reusable behavioral units across tasks and crews.
+
+## When Not to Use Agents
+
+- Deterministic business logic in plain code is sufficient.
+- A static transformation without reasoning is sufficient.
+
 <Note type="info" title="Enterprise Enhancement: Visual Agent Builder">
 CrewAI AMP includes a Visual Agent Builder that simplifies agent creation and configuration without writing code. Design your agents visually and test them in real-time.
 

docs/en/concepts/crews.mdx

@@ -9,6 +9,17 @@ mode: "wide"
 
 A crew in crewAI represents a collaborative group of agents working together to achieve a set of tasks. Each crew defines the strategy for task execution, agent collaboration, and the overall workflow.
 
+## When to Use Crews
+
+- You need multiple specialized agents collaborating on a shared outcome.
+- You need process-level orchestration (`sequential` or `hierarchical`).
+- You need task-level handoffs and context propagation.
+
+## When Not to Use Crews
+
+- A single agent can complete the work end-to-end.
+- You do not need multi-step task decomposition.
+
 ## Crew Attributes
 
 | Attribute                             | Parameters             | Description                                                                                                                                                                                                                                               |
@@ -417,3 +428,17 @@ crewai replay -t <task_id>
 ```
 
 These commands let you replay from your latest kickoff tasks, still retaining context from previously executed tasks.
+
+## Common Failure Modes
+
+### Agents overlap responsibilities
+- Cause: role/goal definitions are too broad.
+- Fix: tighten role boundaries and task ownership.
+
+### Hierarchical runs stall or degrade
+- Cause: weak manager configuration or unclear delegation criteria.
+- Fix: define a stronger manager objective and explicit completion criteria.
+
+### Crew outputs are inconsistent
+- Cause: expected outputs are underspecified across tasks.
+- Fix: enforce structured outputs and stronger task contracts.

docs/en/concepts/files.mdx

@@ -0,0 +1,267 @@
+---
+title: Files
+description: Pass images, PDFs, audio, video, and text files to your agents for multimodal processing.
+icon: file-image
+---
+
+## Overview
+
+CrewAI supports native multimodal file inputs, allowing you to pass images, PDFs, audio, video, and text files directly to your agents. Files are automatically formatted for each LLM provider's API requirements.
+
+<Note type="info" title="Optional Dependency">
+File support requires the optional `crewai-files` package. Install it with:
+
+```bash
+uv add 'crewai[file-processing]'
+```
+</Note>
+
+<Note type="warning" title="Early Access">
+The file processing API is currently in early access.
+</Note>
+
+## File Types
+
+CrewAI supports five specific file types plus a generic `File` class that auto-detects the type:
+
+| Type | Class | Use Cases |
+|:-----|:------|:----------|
+| **Image** | `ImageFile` | Photos, screenshots, diagrams, charts |
+| **PDF** | `PDFFile` | Documents, reports, papers |
+| **Audio** | `AudioFile` | Voice recordings, podcasts, meetings |
+| **Video** | `VideoFile` | Screen recordings, presentations |
+| **Text** | `TextFile` | Code files, logs, data files |
+| **Generic** | `File` | Auto-detect type from content |
+
+```python
+from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile
+
+image = ImageFile(source="screenshot.png")
+pdf = PDFFile(source="report.pdf")
+audio = AudioFile(source="meeting.mp3")
+video = VideoFile(source="demo.mp4")
+text = TextFile(source="data.csv")
+
+file = File(source="document.pdf")
+```
+
+## File Sources
+
+The `source` parameter accepts multiple input types and auto-detects the appropriate handler:
+
+### From Path
+
+```python
+from crewai_files import ImageFile
+
+image = ImageFile(source="./images/chart.png")
+```
+
+### From URL
+
+```python
+from crewai_files import ImageFile
+
+image = ImageFile(source="https://example.com/image.png")
+```
+
+### From Bytes
+
+```python
+from crewai_files import ImageFile, FileBytes
+
+image_bytes = download_image_from_api()
+image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
+image = ImageFile(source=image_bytes)
+```
+
+## Using Files
+
+Files can be passed at multiple levels, with more specific levels taking precedence.
+
+### With Crews
+
+Pass files when kicking off a crew:
+
+```python
+from crewai import Crew
+from crewai_files import ImageFile
+
+crew = Crew(agents=[analyst], tasks=[analysis_task])
+
+result = crew.kickoff(
+    inputs={"topic": "Q4 Sales"},
+    input_files={
+        "chart": ImageFile(source="sales_chart.png"),
+        "report": PDFFile(source="quarterly_report.pdf"),
+    }
+)
+```
+
+### With Tasks
+
+Attach files to specific tasks:
+
+```python
+from crewai import Task
+from crewai_files import ImageFile
+
+task = Task(
+    description="Analyze the sales chart and identify trends in {chart}",
+    expected_output="A summary of key trends",
+    input_files={
+        "chart": ImageFile(source="sales_chart.png"),
+    }
+)
+```
+
+### With Flows
+
+Pass files to flows, which automatically inherit to crews:
+
+```python
+from crewai.flow.flow import Flow, start
+from crewai_files import ImageFile
+
+class AnalysisFlow(Flow):
+    @start()
+    def analyze(self):
+        return self.analysis_crew.kickoff()
+
+flow = AnalysisFlow()
+result = flow.kickoff(
+    input_files={"image": ImageFile(source="data.png")}
+)
+```
+
+### With Standalone Agents
+
+Pass files directly to agent kickoff:
+
+```python
+from crewai import Agent
+from crewai_files import ImageFile
+
+agent = Agent(
+    role="Image Analyst",
+    goal="Analyze images",
+    backstory="Expert at visual analysis",
+    llm="gpt-4o",
+)
+
+result = agent.kickoff(
+    messages="What's in this image?",
+    input_files={"photo": ImageFile(source="photo.jpg")},
+)
+```
+
+## File Precedence
+
+When files are passed at multiple levels, more specific levels override broader ones:
+
+```
+Flow input_files < Crew input_files < Task input_files
+```
+
+For example, if both Flow and Task define a file named `"chart"`, the Task's version is used.
+
+## Provider Support
+
+Different providers support different file types. CrewAI automatically formats files for each provider's API.
+
+| Provider | Image | PDF | Audio | Video | Text |
+|:---------|:-----:|:---:|:-----:|:-----:|:----:|
+| **OpenAI** (completions API) | ✓ | | | | |
+| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | |
+| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
+| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
+| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |
+
+<Note type="info" title="Gemini for Maximum File Support">
+Google Gemini models support all file types including video (up to 1 hour, 2GB). Use Gemini when you need to process video content.
+</Note>
+
+<Note type="warning" title="Unsupported File Types">
+If you pass a file type that the provider doesn't support (e.g., video to OpenAI), you'll receive an `UnsupportedFileTypeError`. Choose your provider based on the file types you need to process.
+</Note>
+
+## How Files Are Sent
+
+CrewAI automatically chooses the optimal method to send files to each provider:
+
+| Method | Description | Used When |
+|:-------|:------------|:----------|
+| **Inline Base64** | File embedded directly in the request | Small files (< 5MB typically) |
+| **File Upload API** | File uploaded separately, referenced by ID | Large files that exceed threshold |
+| **URL Reference** | Direct URL passed to the model | File source is already a URL |
+
+### Provider Transmission Methods
+
+| Provider | Inline Base64 | File Upload API | URL References |
+|:---------|:-------------:|:---------------:|:--------------:|
+| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
+| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
+| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
+| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) |
+| **Azure OpenAI** | ✓ | | ✓ |
+
+<Note type="info" title="Automatic Optimization">
+You don't need to manage this yourself. CrewAI automatically uses the most efficient method based on file size and provider capabilities. Providers without file upload APIs use inline base64 for all files.
+</Note>
+
+## File Handling Modes
+
+Control how files are processed when they exceed provider limits:
+
+```python
+from crewai_files import ImageFile, PDFFile
+
+image = ImageFile(source="large.png", mode="strict")
+image = ImageFile(source="large.png", mode="auto")
+image = ImageFile(source="large.png", mode="warn")
+pdf = PDFFile(source="large.pdf", mode="chunk")
+```
+
+## Provider Constraints
+
+Each provider has specific limits for file sizes and dimensions:
+
+### OpenAI
+- **Images**: Max 20 MB, up to 10 images per request
+- **PDFs**: Max 32 MB, up to 100 pages
+- **Audio**: Max 25 MB, up to 25 minutes
+
+### Anthropic
+- **Images**: Max 5 MB, max 8000x8000 pixels, up to 100 images
+- **PDFs**: Max 32 MB, up to 100 pages
+
+### Google Gemini
+- **Images**: Max 100 MB
+- **PDFs**: Max 50 MB
+- **Audio**: Max 100 MB, up to 9.5 hours
+- **Video**: Max 2 GB, up to 1 hour
+
+### AWS Bedrock
+- **Images**: Max 4.5 MB, max 8000x8000 pixels
+- **PDFs**: Max 3.75 MB, up to 100 pages
+
+## Referencing Files in Prompts
+
+Use the file's key name in your task descriptions to reference files:
+
+```python
+task = Task(
+    description="""
+    Analyze the provided materials:
+    1. Review the chart in {sales_chart}
+    2. Cross-reference with data in {quarterly_report}
+    3. Summarize key findings
+    """,
+    expected_output="Analysis summary with key insights",
+    input_files={
+        "sales_chart": ImageFile(source="chart.png"),
+        "quarterly_report": PDFFile(source="report.pdf"),
+    }
+)
+```

docs/en/concepts/flows.mdx

@@ -19,82 +19,121 @@ Flows allow you to create structured, event-driven workflows. They provide a sea
 
 4. **Flexible Control Flow**: Implement conditional logic, loops, and branching within your workflows.
 
+## When to Use Flows
+
+- You need deterministic orchestration and branching logic.
+- You need explicit state transitions across multiple steps.
+- You need resumable workflows with persistence.
+- You need to combine crews, direct model calls, and Python logic in one runtime.
+
+## When Not to Use Flows
+
+- A single prompt/response call is sufficient.
+- A single crew kickoff with no orchestration logic is sufficient.
+- You do not need stateful multi-step execution.
+
 ## Getting Started
 
-Let's create a simple Flow where you will use OpenAI to generate a random city in one task and then use that city to generate a fun fact in another task.
+The example below shows a realistic Flow for support-ticket triage. It demonstrates features teams use in production: typed state, routing, memory access, and persistence.
 
 ```python Code
-
-from crewai.flow.flow import Flow, listen, start
-from dotenv import load_dotenv
-from litellm import completion
+from crewai.flow.flow import Flow, listen, router, start
+from crewai.flow.persistence import persist
+from pydantic import BaseModel, Field
 
 
-class ExampleFlow(Flow):
-    model = "gpt-4o-mini"
+class SupportTriageState(BaseModel):
+    ticket_id: str = ""
+    customer_tier: str = "standard"  # standard | enterprise
+    issue: str = ""
+    urgency: str = "normal"
+    route: str = ""
+    draft_reply: str = ""
+    internal_notes: list[str] = Field(default_factory=list)
 
+
+@persist()
+class SupportTriageFlow(Flow[SupportTriageState]):
     @start()
-    def generate_city(self):
-        print("Starting flow")
-        # Each flow state automatically gets a unique ID
-        print(f"Flow State ID: {self.state['id']}")
+    def ingest_ticket(self):
+        # kickoff(inputs={...}) is merged into typed state fields
+        print(f"Flow State ID: {self.state.id}")
 
-        response = completion(
-            model=self.model,
-            messages=[
-                {
-                    "role": "user",
-                    "content": "Return the name of a random city in the world.",
-                },
-            ],
+        self.remember(
+            f"Ticket {self.state.ticket_id}: {self.state.issue}",
+            scope=f"/support/{self.state.ticket_id}",
         )
 
-        random_city = response["choices"][0]["message"]["content"]
-        # Store the city in our state
-        self.state["city"] = random_city
-        print(f"Random City: {random_city}")
+        issue = self.state.issue.lower()
+        if "security" in issue or "breach" in issue:
+            self.state.urgency = "critical"
+        elif self.state.customer_tier == "enterprise":
+            self.state.urgency = "high"
+        else:
+            self.state.urgency = "normal"
 
-        return random_city
+        return self.state.issue
 
-    @listen(generate_city)
-    def generate_fun_fact(self, random_city):
-        response = completion(
-            model=self.model,
-            messages=[
-                {
-                    "role": "user",
-                    "content": f"Tell me a fun fact about {random_city}",
-                },
-            ],
+    @router(ingest_ticket)
+    def route_ticket(self):
+        issue = self.state.issue.lower()
+        if "security" in issue or "breach" in issue:
+            self.state.route = "security"
+            return "security_review"
+        if self.state.customer_tier == "enterprise" or self.state.urgency == "high":
+            self.state.route = "priority"
+            return "priority_queue"
+        self.state.route = "standard"
+        return "standard_queue"
+
+    @listen("security_review")
+    def handle_security(self):
+        self.state.internal_notes.append("Escalated to Security Incident Response")
+        self.state.draft_reply = (
+            "We have escalated your case to our security team and will update you shortly."
         )
+        return self.state.draft_reply
 
-        fun_fact = response["choices"][0]["message"]["content"]
-        # Store the fun fact in our state
-        self.state["fun_fact"] = fun_fact
-        return fun_fact
+    @listen("priority_queue")
+    def handle_priority(self):
+        history = self.recall("SLA commitments for enterprise support", limit=2)
+        self.state.internal_notes.append(
+            f"Loaded {len(history)} memory hits for priority handling"
+        )
+        self.state.draft_reply = (
+            "Your ticket has been prioritized and assigned to a senior support engineer."
+        )
+        return self.state.draft_reply
+
+    @listen("standard_queue")
+    def handle_standard(self):
+        self.state.internal_notes.append("Routed to standard support queue")
+        self.state.draft_reply = "Thanks for reporting this. Our team will follow up soon."
+        return self.state.draft_reply
 
 
-
-flow = ExampleFlow()
-flow.plot()
-result = flow.kickoff()
-
-print(f"Generated fun fact: {result}")
+flow = SupportTriageFlow()
+flow.plot("support_triage_flow")
+result = flow.kickoff(
+    inputs={
+        "ticket_id": "TCK-1024",
+        "customer_tier": "enterprise",
+        "issue": "Cannot access SSO after enabling new policy",
+    }
+)
+print("Final reply:", result)
+print("Route:", flow.state.route)
+print("Notes:", flow.state.internal_notes)
 ```
 ![Flow Visual image](/images/crewai-flow-1.png)
-In the above example, we have created a simple Flow that generates a random city using OpenAI and then generates a fun fact about that city. The Flow consists of two tasks: `generate_city` and `generate_fun_fact`. The `generate_city` task is the starting point of the Flow, and the `generate_fun_fact` task listens for the output of the `generate_city` task.
+In this example, one flow demonstrates several core features together:
+1. `@start()` initializes and normalizes state for downstream steps.
+2. `@router()` performs deterministic branching into labeled routes.
+3. Route listeners implement lane-specific behavior (`security`, `priority`, `standard`).
+4. `@persist()` keeps the flow state recoverable between runs.
+5. Built-in memory methods (`remember`, `recall`) add durable context beyond a single method call.
 
-Each Flow instance automatically receives a unique identifier (UUID) in its state, which helps track and manage flow executions. The state can also store additional data (like the generated city and fun fact) that persists throughout the flow's execution.
-
-When you run the Flow, it will:
-1. Generate a unique ID for the flow state
-2. Generate a random city and store it in the state
-3. Generate a fun fact about that city and store it in the state
-4. Print the results to the console
-
-The state's unique ID and stored data can be useful for tracking flow executions and maintaining context between tasks.
-
-**Note:** Ensure you have set up your `.env` file to store your `OPENAI_API_KEY`. This key is necessary for authenticating requests to the OpenAI API.
+This pattern mirrors typical production workflows where request classification, policy-aware routing, and auditable state all happen in one orchestrated flow.
 
 ### @start()
 
@@ -117,15 +156,15 @@ The `@listen()` decorator can be used in several ways:
 1. **Listening to a Method by Name**: You can pass the name of the method you want to listen to as a string. When that method completes, the listener method will be triggered.
 
    ```python Code
-   @listen("generate_city")
-   def generate_fun_fact(self, random_city):
+   @listen("upstream_method")
+   def downstream_method(self, upstream_result):
        # Implementation
    ```
 
 2. **Listening to a Method Directly**: You can pass the method itself. When that method completes, the listener method will be triggered.
    ```python Code
-   @listen(generate_city)
-   def generate_fun_fact(self, random_city):
+   @listen(upstream_method)
+   def downstream_method(self, upstream_result):
        # Implementation
    ```
 
@@ -574,6 +613,10 @@ When you run this Flow, the output will change based on the random boolean value
 
 ### Human in the Loop (human feedback)
 
+<Note>
+The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**.
+</Note>
+
 The `@human_feedback` decorator enables human-in-the-loop workflows by pausing flow execution to collect feedback from a human. This is useful for approval gates, quality review, and decision points that require human judgment.
 
 ```python Code
@@ -737,201 +780,17 @@ This example demonstrates several key features of using Agents in flows:
 
 3. **Tool Integration**: Agents can use tools (like `WebsiteSearchTool`) to enhance their capabilities.
 
-## Adding Crews to Flows
+## Multi-Crew Flows and Plotting
 
-Creating a flow with multiple crews in CrewAI is straightforward.
+Detailed build walkthroughs and project scaffolding are documented in guide pages to keep this concepts page focused.
 
-You can generate a new CrewAI project that includes all the scaffolding needed to create a flow with multiple crews by running the following command:
+- Build your first flow: [/en/guides/flows/first-flow](/en/guides/flows/first-flow)
+- Master state and persistence: [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)
+- Real-world chat-state pattern: [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
 
-```bash
-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.
-
-### Folder Structure
-
-After running the `crewai create flow name_of_flow` command, you will see a folder structure similar to the following:
-
-| Directory/File         | Description                                                        |
-| :--------------------- | :----------------------------------------------------------------- |
-| `name_of_flow/`        | Root directory for the flow.                                       |
-| ├── `crews/`           | Contains directories for specific crews.                           |
-| │ └── `poem_crew/`     | Directory for the "poem_crew" with its configurations and scripts. |
-| │ ├── `config/`        | Configuration files directory for the "poem_crew".                 |
-| │ │ ├── `agents.yaml`  | YAML file defining the agents for "poem_crew".                     |
-| │ │ └── `tasks.yaml`   | YAML file defining the tasks for "poem_crew".                      |
-| │ ├── `poem_crew.py`   | Script for "poem_crew" functionality.                              |
-| ├── `tools/`           | Directory for additional tools used in the flow.                   |
-| │ └── `custom_tool.py` | Custom tool implementation.                                        |
-| ├── `main.py`          | Main script for running the flow.                                  |
-| ├── `README.md`        | Project description and instructions.                              |
-| ├── `pyproject.toml`   | Configuration file for project dependencies and settings.          |
-| └── `.gitignore`       | Specifies files and directories to ignore in version control.      |
-
-### 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:
-
-- `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.
-
-### Connecting Crews in `main.py`
-
-The `main.py` file is where you create your flow and connect the crews together. You can define your flow by using the `Flow` class and the decorators `@start` and `@listen` to specify the flow of execution.
-
-Here's an example of how you can connect the `poem_crew` in the `main.py` file:
-
-```python Code
-#!/usr/bin/env python
-from random import randint
-
-from pydantic import BaseModel
-from crewai.flow.flow import Flow, listen, start
-from .crews.poem_crew.poem_crew import PoemCrew
-
-class PoemState(BaseModel):
-    sentence_count: int = 1
-    poem: str = ""
-
-class PoemFlow(Flow[PoemState]):
-
-    @start()
-    def generate_sentence_count(self):
-        print("Generating sentence count")
-        self.state.sentence_count = randint(1, 5)
-
-    @listen(generate_sentence_count)
-    def generate_poem(self):
-        print("Generating poem")
-        result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count})
-
-        print("Poem generated", result.raw)
-        self.state.poem = result.raw
-
-    @listen(generate_poem)
-    def save_poem(self):
-        print("Saving poem")
-        with open("poem.txt", "w") as f:
-            f.write(self.state.poem)
-
-def kickoff():
-    poem_flow = PoemFlow()
-    poem_flow.kickoff()
-
-
-def plot():
-    poem_flow = PoemFlow()
-    poem_flow.plot("PoemFlowPlot")
-
-if __name__ == "__main__":
-    kickoff()
-    plot()
-```
-
-In this example, the `PoemFlow` class defines a flow that generates a sentence count, uses the `PoemCrew` to generate a poem, and then saves the poem to a file. The flow is kicked off by calling the `kickoff()` method. The PoemFlowPlot will be generated by `plot()` method.
-
-![Flow Visual image](/images/crewai-flow-8.png)
-
-### Running the Flow
-
-(Optional) Before running the flow, you can install the dependencies by running:
-
-```bash
-crewai install
-```
-
-Once all of the dependencies are installed, you need to activate the virtual environment by running:
-
-```bash
-source .venv/bin/activate
-```
-
-After activating the virtual environment, you can run the flow by executing one of the following commands:
-
-```bash
-crewai flow kickoff
-```
-
-or
-
-```bash
-uv run kickoff
-```
-
-The flow will execute, and you should see the output in the console.
-
-## Plot Flows
-
-Visualizing your AI workflows can provide valuable insights into the structure and execution paths of your flows. CrewAI offers a powerful visualization tool that allows you to generate interactive plots of your flows, making it easier to understand and optimize your AI workflows.
-
-### What are Plots?
-
-Plots in CrewAI are graphical representations of your AI workflows. They display the various tasks, their connections, and the flow of data between them. This visualization helps in understanding the sequence of operations, identifying bottlenecks, and ensuring that the workflow logic aligns with your expectations.
-
-### How to Generate a Plot
-
-CrewAI provides two convenient methods to generate plots of your flows:
-
-#### Option 1: Using the `plot()` Method
-
-If you are working directly with a flow instance, you can generate a plot by calling the `plot()` method on your flow object. This method will create an HTML file containing the interactive plot of your flow.
-
-```python Code
-# Assuming you have a flow instance
-flow.plot("my_flow_plot")
-```
-
-This will generate a file named `my_flow_plot.html` in your current directory. You can open this file in a web browser to view the interactive plot.
-
-#### Option 2: Using the Command Line
-
-If you are working within a structured CrewAI project, you can generate a plot using the command line. This is particularly useful for larger projects where you want to visualize the entire flow setup.
-
-```bash
-crewai flow plot
-```
-
-This command will generate an HTML file with the plot of your flow, similar to the `plot()` method. The file will be saved in your project directory, and you can open it in a web browser to explore the flow.
-
-### Understanding the Plot
-
-The generated plot will display nodes representing the tasks in your flow, with directed edges indicating the flow of execution. The plot is interactive, allowing you to zoom in and out, and hover over nodes to see additional details.
-
-By visualizing your flows, you can gain a clearer understanding of the workflow's structure, making it easier to debug, optimize, and communicate your AI processes to others.
-
-### Conclusion
-
-Plotting your flows is a powerful feature of CrewAI that enhances your ability to design and manage complex AI workflows. Whether you choose to use the `plot()` method or the command line, generating plots will provide you with a visual representation of your workflows, aiding in both development and presentation.
-
-## Next Steps
-
-If you're interested in exploring additional examples of flows, we have a variety of recommendations in our examples repository. Here are four specific flow examples, each showcasing unique use cases to help you match your current problem type to a specific example:
-
-1. **Email Auto Responder Flow**: This example demonstrates an infinite loop where a background job continually runs to automate email responses. It's a great use case for tasks that need to be performed repeatedly without manual intervention. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
-
-2. **Lead Score Flow**: This flow showcases adding human-in-the-loop feedback and handling different conditional branches using the router. It's an excellent example of how to incorporate dynamic decision-making and human oversight into your workflows. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
-
-3. **Write a Book Flow**: This example excels at chaining multiple crews together, where the output of one crew is used by another. Specifically, one crew outlines an entire book, and another crew generates chapters based on the outline. Eventually, everything is connected to produce a complete book. This flow is perfect for complex, multi-step processes that require coordination between different tasks. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
-
-4. **Meeting Assistant Flow**: This flow demonstrates how to broadcast one event to trigger multiple follow-up actions. For instance, after a meeting is completed, the flow can update a Trello board, send a Slack message, and save the results. It's a great example of handling multiple outcomes from a single event, making it ideal for comprehensive task management and notification systems. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
-
-By exploring these examples, you can gain insights into how to leverage CrewAI Flows for various use cases, from automating repetitive tasks to managing complex, multi-step processes with dynamic decision-making and human feedback.
-
-Also, check out our YouTube video on how to use flows in CrewAI below!
-
-<iframe
-  className="w-full aspect-video rounded-xl"
-  src="https://www.youtube.com/embed/MTb5my6VOT8"
-  title="CrewAI Flows overview"
-  frameBorder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-  referrerPolicy="strict-origin-when-cross-origin"
-  allowFullScreen
-></iframe>
+For visualization:
+- Use `flow.plot("my_flow_plot")` in code, or
+- Use `crewai flow plot` in CLI projects.
 
 ## Running Flows
 
@@ -942,7 +801,7 @@ There are two ways to run a flow:
 You can run a flow programmatically by creating an instance of your flow class and calling the `kickoff()` method:
 
 ```python
-flow = ExampleFlow()
+flow = SupportTriageFlow()
 result = flow.kickoff()
 ```
 
@@ -971,6 +830,79 @@ result = streaming.result
 
 Learn more about streaming in the [Streaming Flow Execution](/en/learn/streaming-flow-execution) guide.
 
+## Memory in Flows
+
+Every Flow automatically has access to CrewAI's unified [Memory](/concepts/memory) system. You can store, recall, and extract memories directly inside any flow method using three built-in convenience methods.
+
+### Built-in Methods
+
+| Method | Description |
+| :--- | :--- |
+| `self.remember(content, **kwargs)` | Store content in memory. Accepts optional `scope`, `categories`, `metadata`, `importance`. |
+| `self.recall(query, **kwargs)` | Retrieve relevant memories. Accepts optional `scope`, `categories`, `limit`, `depth`. |
+| `self.extract_memories(content)` | Break raw text into discrete, self-contained memory statements. |
+
+A default `Memory()` instance is created automatically when the Flow initializes. You can also pass a custom one:
+
+```python
+from crewai.flow.flow import Flow
+from crewai import Memory
+
+custom_memory = Memory(
+    recency_weight=0.5,
+    recency_half_life_days=7,
+    embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
+)
+
+flow = MyFlow(memory=custom_memory)
+```
+
+### Example: Research and Analyze Flow
+
+```python
+from crewai.flow.flow import Flow, listen, start
+
+
+class ResearchAnalysisFlow(Flow):
+    @start()
+    def gather_data(self):
+        # Simulate research findings
+        findings = (
+            "PostgreSQL handles 10k concurrent connections with connection pooling. "
+            "MySQL caps at around 5k. MongoDB scales horizontally but adds complexity."
+        )
+
+        # Extract atomic facts and remember each one
+        memories = self.extract_memories(findings)
+        for mem in memories:
+            self.remember(mem, scope="/research/databases")
+
+        return findings
+
+    @listen(gather_data)
+    def analyze(self, raw_findings):
+        # Recall relevant past research (from this run or previous runs)
+        past = self.recall("database performance and scaling", limit=10, depth="shallow")
+
+        context_lines = [f"- {m.record.content}" for m in past]
+        context = "\n".join(context_lines) if context_lines else "No prior context."
+
+        return {
+            "new_findings": raw_findings,
+            "prior_context": context,
+            "total_memories": len(past),
+        }
+
+
+flow = ResearchAnalysisFlow()
+result = flow.kickoff()
+print(result)
+```
+
+Because memory persists across runs (backed by LanceDB on disk), the `analyze` step will recall findings from previous executions too -- enabling flows that learn and accumulate knowledge over time.
+
+See the [Memory documentation](/concepts/memory) for details on scopes, slices, composite scoring, embedder configuration, and more.
+
 ### Using the CLI
 
 Starting from version 0.103.0, you can run flows using the `crewai run` command:
@@ -988,3 +920,21 @@ crewai flow kickoff
 ```
 
 However, the `crewai run` command is now the preferred method as it works for both crews and flows.
+
+## Common Failure Modes
+
+### Router branch not firing
+- Cause: returned label does not match a `@listen("label")` value.
+- Fix: align router return strings with listener labels exactly.
+
+### State fields missing at runtime
+- Cause: untyped dynamic fields or missing kickoff inputs.
+- Fix: use typed state and validate required fields in `@start()`.
+
+### Prompt/token growth over time
+- Cause: appending unbounded message history in state.
+- Fix: apply sliding-window state and summary compaction patterns.
+
+### Non-idempotent retries
+- Cause: side effects executed on retried steps.
+- Fix: add idempotency keys/markers to state and guard external writes.

docs/en/concepts/planning.mdx

@@ -10,6 +10,17 @@ mode: "wide"
 The planning feature in CrewAI allows you to add planning capability to your crew. When enabled, before each Crew iteration, 
 all Crew information is sent to an AgentPlanner that will plan the tasks step by step, and this plan will be added to each task description.
 
+## When to Use Planning
+
+- Tasks require multi-step decomposition before execution.
+- You need more consistent execution quality on complex tasks.
+- You want transparent planning traces in crew runs.
+
+## When Not to Use Planning
+
+- Tasks are simple and deterministic.
+- Latency and token budget are strict and planning overhead is not justified.
+
 ### Using the Planning Feature
 
 Getting started with the planning feature is very easy, the only step required is to add `planning=True` to your Crew:
@@ -31,7 +42,7 @@ my_crew = Crew(
 From this point on, your crew will have planning enabled, and the tasks will be planned before each iteration.
 
 <Warning>
-When planning is enabled, crewAI will use `gpt-4o-mini` as the default LLM for planning, which requires a valid OpenAI API key. Since your agents might be using different LLMs, this could cause confusion if you don't have an OpenAI API key configured or if you're experiencing unexpected behavior related to LLM API calls.
+Planning model defaults can vary by version and environment. To avoid implicit provider dependencies, set `planning_llm` explicitly in your crew configuration.
 </Warning>
 
 #### Planning LLM
@@ -152,4 +163,14 @@ A list with 10 bullet points of the most relevant information about AI LLMs.
 **Expected Output:**
 A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'.
 ```
-</CodeGroup>
+</CodeGroup>
+
+## Common Failure Modes
+
+### Planning adds cost/latency without quality gains
+- Cause: planning enabled for simple tasks.
+- Fix: disable `planning` for straightforward pipelines.
+
+### Unexpected provider authentication errors
+- Cause: implicit planner model/provider assumptions.
+- Fix: set `planning_llm` explicitly and ensure matching credentials are configured.

docs/en/concepts/processes.mdx

@@ -12,11 +12,20 @@ mode: "wide"
   These processes ensure tasks are distributed and executed efficiently, in alignment with a predefined strategy.
 </Tip>
 
+## When to Use Each Process
+
+- Use `sequential` when task order is fixed and outputs feed directly into the next task.
+- Use `hierarchical` when you need a manager to delegate and validate work dynamically.
+
+## When Not to Use Hierarchical
+
+- You do not need dynamic delegation.
+- You cannot provide a reliable `manager_llm` or `manager_agent`.
+
 ## Process Implementations
 
 - **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 +68,17 @@ 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.
+## Common Failure Modes
+
+### Hierarchical process fails at startup
+- Cause: missing `manager_llm` or `manager_agent`.
+- Fix: provide one of them explicitly in crew configuration.
+
+### Sequential process produces weak outputs
+- Cause: task boundaries/context are underspecified.
+- Fix: improve task descriptions, expected outputs, and task context chaining.

docs/en/concepts/tasks.mdx

@@ -46,7 +46,7 @@ crew = Crew(
 ## Task Attributes
 
 | Attribute                              | Parameters              | Type                        | Description                                                                                                     |
-| :------------------------------------- | :---------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| :------------------------------------- | :---------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------- |
 | **Description**                        | `description`           | `str`                       | A clear, concise statement of what the task entails.                                                            |
 | **Expected Output**                    | `expected_output`       | `str`                       | A detailed description of what the task's completion looks like.                                                |
 | **Name** _(optional)_                  | `name`                  | `Optional[str]`             | A name identifier for the task.                                                                                 |
@@ -63,7 +63,7 @@ crew = Crew(
 | **Output Pydantic** _(optional)_       | `output_pydantic`       | `Optional[Type[BaseModel]]` | A Pydantic model for task output.                                                                               |
 | **Callback** _(optional)_              | `callback`              | `Optional[Any]`             | Function/object to be executed after task completion.                                                           |
 | **Guardrail** _(optional)_             | `guardrail`             | `Optional[Callable]`        | Function to validate task output before proceeding to next task.                                                |
-| **Guardrails** _(optional)_            | `guardrails`            | `Optional[List[Callable]    | List[str]]`                                                                                                     | List of guardrails to validate task output before proceeding to next task. |
+| **Guardrails** _(optional)_            | `guardrails`            | `Optional[List[Callable]]`  | List of guardrails to validate task output before proceeding to next task.                                      |
 | **Guardrail Max Retries** _(optional)_ | `guardrail_max_retries` | `Optional[int]`             | Maximum number of retries when guardrail validation fails. Defaults to 3.                                       |
 
 <Note type="warning" title="Deprecated: max_retries">

docs/en/concepts/testing.mdx

@@ -9,9 +9,20 @@ mode: "wide"
 
 Testing is a crucial part of the development process, and it is essential to ensure that your crew is performing as expected. With crewAI, you can easily test your crew and evaluate its performance using the built-in testing capabilities.
 
+## When to Use Testing
+
+- Before promoting a crew to production.
+- After changing prompts, tools, or model configurations.
+- When benchmarking quality/cost/latency tradeoffs.
+
+## When Not to Rely on Testing Alone
+
+- For safety-critical deployments without human review gates.
+- When test datasets are too small or unrepresentative.
+
 ### Using the Testing Feature
 
-We added the CLI command `crewai test` to make it easy to test your crew. This command will run your crew for a specified number of iterations and provide detailed performance metrics. The parameters are `n_iterations` and `model`, which are optional and default to 2 and `gpt-4o-mini` respectively. For now, the only provider available is OpenAI.
+Use the CLI command `crewai test` to run repeated crew executions and compare outputs across iterations. The parameters are `n_iterations` and `model`, which are optional and default to `2` and `gpt-4o-mini`.
 
 ```bash
 crewai test
@@ -47,3 +58,13 @@ A table of scores at the end will show the performance of the crew in terms of t
 | Execution Time (s) |  126  |  145  |    **135**     |                                |                                  |
 
 The example above shows the test results for two runs of the crew with two tasks, with the average total score for each task and the crew as a whole.
+
+## Common Failure Modes
+
+### Scores fluctuate too much between runs
+- Cause: high sampling randomness or unstable prompts.
+- Fix: lower temperature and tighten output constraints.
+
+### Good test scores but poor production quality
+- Cause: test prompts do not match real workload.
+- Fix: build a representative test set from real production inputs.

docs/en/concepts/tools.mdx

@@ -10,6 +10,17 @@ mode: "wide"
 CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers.
 This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools.
 
+## When to Use Tools
+
+- Agents need external data or side effects.
+- You need deterministic actions wrapped in reusable interfaces.
+- You need to connect APIs, files, databases, or browser actions into agent workflows.
+
+## When Not to Use Tools
+
+- The task can be solved entirely from prompt context.
+- The external side effect cannot be made safe or idempotent.
+
 ## What is a Tool?
 
 A tool in CrewAI is a skill or function that agents can utilize to perform various actions.
@@ -285,3 +296,17 @@ writer1 = Agent(
 Tools are pivotal in extending the capabilities of CrewAI agents, enabling them to undertake a broad spectrum of tasks and collaborate effectively.
 When building solutions with CrewAI, leverage both custom and existing tools to empower your agents and enhance the AI ecosystem. Consider utilizing error handling,
 caching mechanisms, and the flexibility of tool arguments to optimize your agents' performance and capabilities.
+
+## Common Failure Modes
+
+### Tool schema mismatch
+- Cause: model-generated arguments do not match tool signature.
+- Fix: tighten tool descriptions and validate input schemas.
+
+### Repeated side effects
+- Cause: retries trigger duplicate writes/actions.
+- Fix: add idempotency keys and deduplication checks in tool logic.
+
+### Tool timeouts under load
+- Cause: unbounded retries or slow external services.
+- Fix: set explicit timeout/retry policy and graceful fallbacks.

docs/en/enterprise/features/flow-hitl-management.mdx

@@ -0,0 +1,558 @@
+---
+title: "Flow HITL Management"
+description: "Enterprise-grade human review for Flows with email-first notifications, routing rules, and auto-response capabilities"
+icon: "users-gear"
+mode: "wide"
+---
+
+<Note>
+Flow HITL Management features require the `@human_feedback` decorator, available in **CrewAI version 1.8.0 or higher**. These features apply specifically to **Flows**, not Crews.
+</Note>
+
+CrewAI Enterprise provides a comprehensive Human-in-the-Loop (HITL) management system for Flows that transforms AI workflows into collaborative human-AI processes. The platform uses an **email-first architecture** that enables anyone with an email address to respond to review requests—no platform account required.
+
+## Overview
+
+<CardGroup cols={3}>
+  <Card title="Email-First Design" icon="envelope">
+    Responders can reply directly to notification emails to provide feedback
+  </Card>
+  <Card title="Flexible Routing" icon="route">
+    Route requests to specific emails based on method patterns or flow state
+  </Card>
+  <Card title="Auto-Response" icon="clock">
+    Configure automatic fallback responses when no human replies in time
+  </Card>
+</CardGroup>
+
+### Key Benefits
+
+- **Simple mental model**: Email addresses are universal; no need to manage platform users or roles
+- **External responders**: Anyone with an email can respond, even non-platform users
+- **Dynamic assignment**: Pull assignee email directly from flow state (e.g., `sales_rep_email`)
+- **Reduced configuration**: Fewer settings to configure, faster time to value
+- **Email as primary channel**: Most users prefer responding via email over logging into a dashboard
+
+## Setting Up Human Review Points in Flows
+
+Configure human review checkpoints within your Flows using the `@human_feedback` decorator. When execution reaches a review point, the system pauses, notifies the assignee via email, and waits for a response.
+
+```python
+from crewai.flow.flow import Flow, start, listen, or_
+from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
+
+class ContentApprovalFlow(Flow):
+    @start()
+    def generate_content(self):
+        return "Generated marketing copy for Q1 campaign..."
+
+    @human_feedback(
+        message="Please review this content for brand compliance:",
+        emit=["approved", "rejected", "needs_revision"],
+    )
+    @listen(or_("generate_content", "needs_revision"))
+    def review_content(self):
+        return "Marketing copy for review..."
+
+    @listen("approved")
+    def publish_content(self, result: HumanFeedbackResult):
+        print(f"Publishing approved content. Reviewer notes: {result.feedback}")
+
+    @listen("rejected")
+    def archive_content(self, result: HumanFeedbackResult):
+        print(f"Content rejected. Reason: {result.feedback}")
+```
+
+For complete implementation details, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide.
+
+### Decorator Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | `str` | The message displayed to the human reviewer |
+| `emit` | `list[str]` | Valid response options (displayed as buttons in UI) |
+
+## Platform Configuration
+
+Access HITL configuration from: **Deployment → Settings → Human in the Loop Configuration**
+
+<Frame>
+  <img src="/images/enterprise/hitl-settings-overview.png" alt="HITL Configuration Settings" />
+</Frame>
+
+### Email Notifications
+
+Toggle to enable or disable email notifications for HITL requests.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Email Notifications | Enabled | Send emails when feedback is requested |
+
+<Note>
+When disabled, responders must use the dashboard UI or you must configure webhooks for custom notification systems.
+</Note>
+
+### SLA Target
+
+Set a target response time for tracking and metrics purposes.
+
+| Setting | Description |
+|---------|-------------|
+| SLA Target (minutes) | Target response time. Used for dashboard metrics and SLA tracking |
+
+Leave empty to disable SLA tracking.
+
+## Email Notifications & Responses
+
+The HITL system uses an email-first architecture where responders can reply directly to notification emails.
+
+### How Email Responses Work
+
+<Steps>
+  <Step title="Notification Sent">
+    When a HITL request is created, an email is sent to the assigned responder with the review content and context.
+  </Step>
+  <Step title="Reply-To Address">
+    The email includes a special reply-to address with a signed token for authentication.
+  </Step>
+  <Step title="User Replies">
+    The responder simply replies to the email with their feedback—no login required.
+  </Step>
+  <Step title="Token Validation">
+    The platform receives the reply, verifies the signed token, and matches the sender email.
+  </Step>
+  <Step title="Flow Resumes">
+    The feedback is recorded and the flow continues with the human's input.
+  </Step>
+</Steps>
+
+### Response Format
+
+Responders can reply with:
+
+- **Emit option**: If the reply matches an `emit` option (e.g., "approved"), it's used directly
+- **Free-form text**: Any text response is passed to the flow as feedback
+- **Plain text**: The first line of the reply body is used as feedback
+
+### Confirmation Emails
+
+After processing a reply, the responder receives a confirmation email indicating whether the feedback was successfully submitted or if an error occurred.
+
+### Email Token Security
+
+- Tokens are cryptographically signed for security
+- Tokens expire after 7 days
+- Sender email must match the token's authorized email
+- Confirmation/error emails are sent after processing
+
+## Routing Rules
+
+Route HITL requests to specific email addresses based on method patterns.
+
+<Frame>
+  <img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL Routing Rules Configuration" />
+</Frame>
+
+### Rule Structure
+
+```json
+{
+  "name": "Approvals to Finance",
+  "match": {
+    "method_name": "approve_*"
+  },
+  "assign_to_email": "finance@company.com",
+  "assign_from_input": "manager_email"
+}
+```
+
+### Matching Patterns
+
+| Pattern | Description | Example Match |
+|---------|-------------|---------------|
+| `approve_*` | Wildcard (any chars) | `approve_payment`, `approve_vendor` |
+| `review_?` | Single char | `review_a`, `review_1` |
+| `validate_payment` | Exact match | `validate_payment` only |
+
+### Assignment Priority
+
+1. **Dynamic assignment** (`assign_from_input`): If configured, pulls email from flow state
+2. **Static email** (`assign_to_email`): Falls back to configured email
+3. **Deployment creator**: If no rule matches, the deployment creator's email is used
+
+### Dynamic Assignment Example
+
+If your flow state contains `{"sales_rep_email": "alice@company.com"}`, configure:
+
+```json
+{
+  "name": "Route to Sales Rep",
+  "match": {
+    "method_name": "review_*"
+  },
+  "assign_from_input": "sales_rep_email"
+}
+```
+
+The request will be assigned to `alice@company.com` automatically.
+
+<Tip>
+**Use Case**: Pull the assignee from your CRM, database, or previous flow step to dynamically route reviews to the right person.
+</Tip>
+
+## Auto-Response
+
+Automatically respond to HITL requests if no human responds within a timeout. This ensures flows don't hang indefinitely.
+
+### Configuration
+
+| Setting | Description |
+|---------|-------------|
+| Enabled | Toggle to enable auto-response |
+| Timeout (minutes) | Time to wait before auto-responding |
+| Default Outcome | The response value (must match an `emit` option) |
+
+<Frame>
+  <img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL Auto-Response Configuration" />
+</Frame>
+
+### Use Cases
+
+- **SLA compliance**: Ensure flows don't hang indefinitely
+- **Default approval**: Auto-approve low-risk requests after timeout
+- **Graceful degradation**: Continue with a safe default when reviewers are unavailable
+
+<Warning>
+Use auto-response carefully. Only enable it for non-critical reviews where a default response is acceptable.
+</Warning>
+
+## Review Process
+
+### Dashboard Interface
+
+The HITL review interface provides a clean, focused experience for reviewers:
+
+- **Markdown Rendering**: Rich formatting for review content with syntax highlighting
+- **Context Panel**: View flow state, execution history, and related information
+- **Feedback Input**: Provide detailed feedback and comments with your decision
+- **Quick Actions**: One-click emit option buttons with optional comments
+
+<Frame>
+  <img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL Pending Requests List" />
+</Frame>
+
+### Response Methods
+
+Reviewers can respond via three channels:
+
+| Method | Description |
+|--------|-------------|
+| **Email Reply** | Reply directly to the notification email |
+| **Dashboard** | Use the Enterprise dashboard UI |
+| **API/Webhook** | Programmatic response via API |
+
+### History & Audit Trail
+
+Every HITL interaction is tracked with a complete timeline:
+
+- Decision history (approve/reject/revise)
+- Reviewer identity and timestamp
+- Feedback and comments provided
+- Response method (email/dashboard/API)
+- Response time metrics
+
+## Analytics & Monitoring
+
+Track HITL performance with comprehensive analytics.
+
+### Performance Dashboard
+
+<Frame>
+  <img src="/images/enterprise/hitl-metrics.png" alt="HITL Metrics Dashboard" />
+</Frame>
+
+<CardGroup cols={2}>
+  <Card title="Response Times" icon="stopwatch">
+    Monitor average and median response times by reviewer or flow.
+  </Card>
+  <Card title="Volume Trends" icon="chart-bar">
+    Analyze review volume patterns to optimize team capacity.
+  </Card>
+  <Card title="Decision Distribution" icon="chart-pie">
+    View approval/rejection rates across different review types.
+  </Card>
+  <Card title="SLA Tracking" icon="chart-line">
+    Track percentage of reviews completed within SLA targets.
+  </Card>
+</CardGroup>
+
+### Audit & Compliance
+
+Enterprise-ready audit capabilities for regulatory requirements:
+
+- Complete decision history with timestamps
+- Reviewer identity verification
+- Immutable audit logs
+- Export capabilities for compliance reporting
+
+## Common Use Cases
+
+<AccordionGroup>
+  <Accordion title="Security Reviews" icon="shield-halved">
+    **Use Case**: Internal security questionnaire automation with human validation
+
+    - AI generates responses to security questionnaires
+    - Security team reviews and validates accuracy via email
+    - Approved responses are compiled into final submission
+    - Full audit trail for compliance
+  </Accordion>
+
+  <Accordion title="Content Approval" icon="file-lines">
+    **Use Case**: Marketing content requiring legal/brand review
+
+    - AI generates marketing copy or social media content
+    - Route to brand team email for voice/tone review
+    - Automatic publishing upon approval
+  </Accordion>
+
+  <Accordion title="Financial Approvals" icon="money-bill">
+    **Use Case**: Expense reports, contract terms, budget allocations
+
+    - AI pre-processes and categorizes financial requests
+    - Route based on amount thresholds using dynamic assignment
+    - Maintain complete audit trail for financial compliance
+  </Accordion>
+
+  <Accordion title="Dynamic Assignment from CRM" icon="database">
+    **Use Case**: Route reviews to account owners from your CRM
+
+    - Flow fetches account owner email from CRM
+    - Store email in flow state (e.g., `account_owner_email`)
+    - Use `assign_from_input` to route to the right person automatically
+  </Accordion>
+
+  <Accordion title="Quality Assurance" icon="magnifying-glass">
+    **Use Case**: AI output validation before customer delivery
+
+    - AI generates customer-facing content or responses
+    - QA team reviews via email notification
+    - Feedback loops improve AI performance over time
+  </Accordion>
+</AccordionGroup>
+
+## Webhooks API
+
+When your Flows pause for human feedback, you can configure webhooks to send request data to your own application. This enables:
+
+- Building custom approval UIs
+- Integrating with internal tools (Jira, ServiceNow, custom dashboards)
+- Routing approvals to third-party systems
+- Mobile app notifications
+- Automated decision systems
+
+<Frame>
+  <img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook Configuration" />
+</Frame>
+
+### Configuring Webhooks
+
+<Steps>
+  <Step title="Navigate to Settings">
+    Go to your **Deployment** → **Settings** → **Human in the Loop**
+  </Step>
+  <Step title="Expand Webhooks Section">
+    Click to expand the **Webhooks** configuration
+  </Step>
+  <Step title="Add Your Webhook URL">
+    Enter your webhook URL (must be HTTPS in production)
+  </Step>
+  <Step title="Save Configuration">
+    Click **Save Configuration** to activate
+  </Step>
+</Steps>
+
+You can configure multiple webhooks. Each active webhook receives all HITL events.
+
+### Webhook Events
+
+Your endpoint will receive HTTP POST requests for these events:
+
+| Event Type | When Triggered |
+|------------|----------------|
+| `new_request` | A flow pauses and requests human feedback |
+
+### Webhook Payload
+
+All webhooks receive a JSON payload with this structure:
+
+```json
+{
+  "event": "new_request",
+  "request": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "flow_id": "flow_abc123",
+    "method_name": "review_article",
+    "message": "Please review this article for publication.",
+    "emit_options": ["approved", "rejected", "request_changes"],
+    "state": {
+      "article_id": 12345,
+      "author": "john@example.com",
+      "category": "technology"
+    },
+    "metadata": {},
+    "created_at": "2026-01-14T12:00:00Z"
+  },
+  "deployment": {
+    "id": 456,
+    "name": "Content Review Flow",
+    "organization_id": 789
+  },
+  "callback_url": "https://api.crewai.com/...",
+  "assigned_to_email": "reviewer@company.com"
+}
+```
+
+### Responding to Requests
+
+To submit feedback, **POST to the `callback_url`** included in the webhook payload.
+
+```http
+POST {callback_url}
+Content-Type: application/json
+
+{
+  "feedback": "Approved. Great article!",
+  "source": "my_custom_app"
+}
+```
+
+### Security
+
+<Info>
+All webhook requests are cryptographically signed using HMAC-SHA256 to ensure authenticity and prevent tampering.
+</Info>
+
+#### Webhook Security
+
+- **HMAC-SHA256 signatures**: Every webhook includes a cryptographic signature
+- **Per-webhook secrets**: Each webhook has its own unique signing secret
+- **Encrypted at rest**: Signing secrets are encrypted in our database
+- **Timestamp verification**: Prevents replay attacks
+
+#### Signature Headers
+
+Each webhook request includes these headers:
+
+| Header | Description |
+|--------|-------------|
+| `X-Signature` | HMAC-SHA256 signature: `sha256=<hex_digest>` |
+| `X-Timestamp` | Unix timestamp when the request was signed |
+
+#### Verification
+
+Verify by computing:
+
+```python
+import hmac
+import hashlib
+
+expected = hmac.new(
+    signing_secret.encode(),
+    f"{timestamp}.{payload}".encode(),
+    hashlib.sha256
+).hexdigest()
+
+if hmac.compare_digest(expected, signature):
+    # Valid signature
+```
+
+### Error Handling
+
+Your webhook endpoint should return a 2xx status code to acknowledge receipt:
+
+| Your Response | Our Behavior |
+|---------------|--------------|
+| 2xx | Webhook delivered successfully |
+| 4xx/5xx | Logged as failed, no retry |
+| Timeout (30s) | Logged as failed, no retry |
+
+## Security & RBAC
+
+### Dashboard Access
+
+HITL access is controlled at the deployment level:
+
+| Permission | Capability |
+|------------|------------|
+| `manage_human_feedback` | Configure HITL settings, view all requests |
+| `respond_to_human_feedback` | Respond to requests, view assigned requests |
+
+### Email Response Authorization
+
+For email replies:
+1. The reply-to token encodes the authorized email
+2. Sender email must match the token's email
+3. Token must not be expired (7-day default)
+4. Request must still be pending
+
+### Audit Trail
+
+All HITL actions are logged:
+- Request creation
+- Assignment changes
+- Response submission (with source: dashboard/email/API)
+- Flow resume status
+
+## Troubleshooting
+
+### Emails Not Sending
+
+1. Check "Email Notifications" is enabled in configuration
+2. Verify routing rules match the method name
+3. Verify assignee email is valid
+4. Check deployment creator fallback if no routing rules match
+
+### Email Replies Not Processing
+
+1. Check token hasn't expired (7-day default)
+2. Verify sender email matches assigned email
+3. Ensure request is still pending (not already responded)
+
+### Flow Not Resuming
+
+1. Check request status in dashboard
+2. Verify callback URL is accessible
+3. Ensure deployment is still running
+
+## Best Practices
+
+<Tip>
+**Start Simple**: Begin with email notifications to deployment creator, then add routing rules as your workflows mature.
+</Tip>
+
+1. **Use Dynamic Assignment**: Pull assignee emails from your flow state for flexible routing.
+
+2. **Configure Auto-Response**: Set up a fallback for non-critical reviews to prevent flows from hanging.
+
+3. **Monitor Response Times**: Use analytics to identify bottlenecks and optimize your review process.
+
+4. **Keep Review Messages Clear**: Write clear, actionable messages in the `@human_feedback` decorator.
+
+5. **Test Email Flow**: Send test requests to verify email delivery before going to production.
+
+## Related Resources
+
+<CardGroup cols={2}>
+  <Card title="Human Feedback in Flows" icon="code" href="/en/learn/human-feedback-in-flows">
+    Implementation guide for the `@human_feedback` decorator
+  </Card>
+  <Card title="Flow HITL Workflow Guide" icon="route" href="/en/enterprise/guides/human-in-the-loop">
+    Step-by-step guide for setting up HITL workflows
+  </Card>
+  <Card title="RBAC Configuration" icon="shield-check" href="/en/enterprise/features/rbac">
+    Configure role-based access control for your organization
+  </Card>
+  <Card title="Webhook Streaming" icon="bolt" href="/en/enterprise/features/webhook-streaming">
+    Set up real-time event notifications
+  </Card>
+</CardGroup>

docs/en/enterprise/features/pii-trace-redactions.mdx

@@ -0,0 +1,342 @@
+---
+title: PII Redaction for Traces
+description: "Automatically redact sensitive data from crew and flow execution traces"
+icon: "lock"
+mode: "wide"
+---
+
+## Overview
+
+PII Redaction is a CrewAI AMP feature that automatically detects and masks Personally Identifiable Information (PII) in your crew and flow execution traces. This ensures sensitive data like credit card numbers, social security numbers, email addresses, and names are not exposed in your CrewAI AMP traces. You can also create custom recognizers to protect organization-specific data.
+
+
+<Info>
+  PII Redaction is available on the Enterprise plan.
+  Deployment must be version 1.8.0 or higher.
+</Info>
+
+
+<Frame>
+  ![PII Redaction Overview](/images/enterprise/pii_mask_recognizer_trace_example.png)
+</Frame>
+
+
+## Why PII Redaction Matters
+
+When running AI agents in production, sensitive information often flows through your crews:
+
+- Customer data from CRM integrations
+- Financial information from payment processors
+- Personal details from form submissions
+- Internal employee data
+
+Without proper redaction, this data appears in traces, making compliance with regulations like GDPR, HIPAA, and PCI-DSS challenging. PII Redaction solves this by automatically masking sensitive data before it's stored in traces.
+
+## How It Works
+
+1. **Detect** - Scan trace event data for known PII patterns
+2. **Classify** - Identify the type of sensitive data (credit card, SSN, email, etc.)
+3. **Mask/Redact** - Replace the sensitive data with masked values based on your configuration
+
+```
+Original: "Contact john.doe@company.com or call 555-123-4567"
+Redacted: "Contact <EMAIL_ADDRESS> or call <PHONE_NUMBER>"
+```
+
+## Enabling PII Redaction
+
+<Info>
+  You must be on the Enterprise plan and your deployment must be version 1.8.0 or higher to use this feature.
+</Info>
+
+<Steps>
+  <Step title="Navigate to Crew Settings">
+    In the CrewAI AMP dashboard, select your deployed crew and go to one of your deployments/automations, then navigate to **Settings** → **PII Protection**.
+  </Step>
+
+  <Step title="Enable PII Protection">
+    Toggle on **PII Redaction for Traces**. This will enable automatic scanning and redaction of trace data.
+
+    <Info>
+      You need to manually enable PII Redaction for each deployment.
+    </Info>
+
+    <Frame>
+      ![Enable PII Redaction](/images/enterprise/pii_mask_recognizer_enable.png)
+    </Frame>
+  </Step>
+
+  <Step title="Configure Entity Types">
+    Select which types of PII to detect and redact. Each entity can be individually enabled or disabled.
+
+    <Frame>
+      ![Configure Entities](/images/enterprise/pii_mask_recognizer_supported_entities.png)
+    </Frame>
+  </Step>
+
+  <Step title="Save">
+    Save your configuration. PII redaction will be active on all subsequent crew executions, no redeployment is needed.
+  </Step>
+</Steps>
+
+## Supported Entity Types
+
+CrewAI supports the following PII entity types, organized by category.
+
+### Global Entities
+
+| Entity | Description | Example |
+|--------|-------------|---------|
+| `CREDIT_CARD` | Credit/debit card numbers | "4111-1111-1111-1111" |
+| `CRYPTO` | Cryptocurrency wallet addresses | "bc1qxy2kgd..." |
+| `DATE_TIME` | Dates and times | "January 15, 2024" |
+| `EMAIL_ADDRESS` | Email addresses | "john@example.com" |
+| `IBAN_CODE` | International bank account numbers | "DE89 3704 0044 0532 0130 00" |
+| `IP_ADDRESS` | IPv4 and IPv6 addresses | "192.168.1.1" |
+| `LOCATION` | Geographic locations | "New York City" |
+| `MEDICAL_LICENSE` | Medical license numbers | "MD12345" |
+| `NRP` | Nationalities, religious, or political groups | - |
+| `PERSON` | Personal names | "John Doe" |
+| `PHONE_NUMBER` | Phone numbers in various formats | "+1 (555) 123-4567" |
+| `URL` | Web URLs | "https://example.com" |
+
+### US-Specific Entities
+
+| Entity | Description | Example |
+|--------|-------------|---------|
+| `US_BANK_NUMBER` | US Bank account numbers | "1234567890" |
+| `US_DRIVER_LICENSE` | US Driver's license numbers | "D1234567" |
+| `US_ITIN` | Individual Taxpayer ID | "900-70-0000" |
+| `US_PASSPORT` | US Passport numbers | "123456789" |
+| `US_SSN` | Social Security Numbers | "123-45-6789" |
+
+## Redaction Actions
+
+For each enabled entity, you can configure how the data is redacted:
+
+| Action | Description | Example Output |
+|--------|-------------|----------------|
+| `mask` | Replace with the entity type label | `<CREDIT_CARD>` |
+| `redact` | Completely remove the text | *(empty)* |
+
+## Custom Recognizers
+
+In addition to built-in entities, you can create **custom recognizers** to detect organization-specific PII patterns.
+
+<Frame>
+  ![Custom Recognizers](/images/enterprise/pii_mask_recognizer.png)
+</Frame>
+
+### Recognizer Types
+
+You have two options for custom recognizers:
+
+| Type | Best For | Example Use Case |
+|------|----------|------------------|
+| **Pattern-based (Regex)** | Structured data with predictable formats | Salary amounts, employee IDs, project codes |
+| **Deny-list** | Exact string matches | Company names, internal codenames, specific terms |
+
+### Creating a Custom Recognizer
+
+<Steps>
+  <Step title="Navigate to Custom Recognizers">
+    Go to your Organization **Settings** → **Organization** → **Add Recognizer**.
+  </Step>
+
+  <Step title="Configure the Recognizer">
+    <Frame>
+      ![Configure Recognizer](/images/enterprise/pii_mask_recognizer_create.png)
+    </Frame>
+
+    Configure the following fields:
+    - **Name**: A descriptive name for the recognizer
+    - **Entity Type**: The entity label that will appear in redacted output (e.g., `EMPLOYEE_ID`, `SALARY`)
+    - **Type**: Choose between Regex Pattern or Deny List
+    - **Pattern/Values**: Regex pattern or list of strings to match
+    - **Confidence Threshold**: Minimum score (0.0-1.0) required for a match to trigger redaction. Higher values (e.g., 0.8) reduce false positives but may miss some matches. Lower values (e.g., 0.5) catch more matches but may over-redact. Default is 0.8.
+    - **Context Words** (optional): Words that increase detection confidence when found nearby
+  </Step>
+
+  <Step title="Save">
+    Save the recognizer. It will be available to enable on your deployments.
+  </Step>
+</Steps>
+
+### Understanding Entity Types
+
+The **Entity Type** determines how matched content appears in redacted traces:
+
+```
+Entity Type: SALARY
+Pattern: salary:\s*\$\s*\d+
+Input: "Employee salary: $50,000"
+Output: "Employee <SALARY>"
+```
+
+### Using Context Words
+
+Context words improve accuracy by increasing confidence when specific terms appear near the matched pattern:
+
+```
+Context Words: "project", "code", "internal"
+Entity Type: PROJECT_CODE
+Pattern: PRJ-\d{4}
+```
+
+When "project" or "code" appears near "PRJ-1234", the recognizer has higher confidence it's a true match, reducing false positives.
+
+
+## Viewing Redacted Traces
+
+Once PII redaction is enabled, your traces will show redacted values in place of sensitive data:
+
+```
+Task Output: "Customer <PERSON> placed order #12345.
+Contact email: <EMAIL_ADDRESS>, phone: <PHONE_NUMBER>.
+Payment processed for card ending in <CREDIT_CARD>."
+```
+
+Redacted values are clearly marked with angle brackets and the entity type label (e.g., `<EMAIL_ADDRESS>`), making it easy to understand what data was protected while still allowing you to debug and monitor crew behavior.
+
+
+
+## Best Practices
+
+### Performance Considerations
+
+<Steps>
+  <Step title="Enable Only Needed Entities">
+    Each enabled entity adds processing overhead. Only enable entities relevant to your data.
+  </Step>
+
+  <Step title="Use Specific Patterns">
+    For custom recognizers, use specific patterns to reduce false positives and improve performance. Regex patterns are best when identifying specific patterns in the traces such as salary, employee id, project code, etc. Deny-list recognizers are best when identifying exact strings in the traces such as company names, internal codenames, etc.
+  </Step>
+
+  <Step title="Leverage Context Words">
+    Context words improve accuracy by only triggering detection when surrounding text matches.
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+<Accordion title="PII Not Being Redacted">
+  **Possible Causes:**
+  - Entity type not enabled in configuration
+  - Pattern doesn't match the data format
+  - Custom recognizer has syntax errors
+
+  **Solutions:**
+  - Verify entity is enabled in Settings → Security
+  - Test regex patterns with sample data
+  - Check logs for configuration errors
+</Accordion>
+
+<Accordion title="Too Much Data Being Redacted">
+  **Possible Causes:**
+  - Overly broad entity types enabled (e.g., `DATE_TIME` catches dates everywhere)
+  - Custom recognizer patterns are too general
+
+  **Solutions:**
+  - Disable entities that cause false positives
+  - Make custom patterns more specific
+  - Add context words to improve accuracy
+</Accordion>
+
+<Accordion title="Performance Issues">
+  **Possible Causes:**
+  - Too many entities enabled
+  - NLP-based entities (`PERSON`, `LOCATION`, `NRP`) are computationally expensive as they use machine learning models
+
+  **Solutions:**
+  - Only enable entities you actually need
+  - Consider using pattern-based alternatives where possible
+  - Monitor trace processing times in the dashboard
+</Accordion>
+
+---
+
+## Practical Example: Salary Pattern Matching
+
+This example demonstrates how to create a custom recognizer to detect and mask salary information in your traces.
+
+### Use Case
+
+Your crew processes employee or financial data that includes salary information in formats like:
+- `salary: $50,000`
+- `salary: $125,000.00`
+- `salary:$1,500.50`
+
+You want to automatically mask these values to protect sensitive compensation data.
+
+### Configuration
+
+<Frame>
+  ![Salary Recognizer Configuration](/images/enterprise/pii_mask_custom_recognizer_salary.png)
+</Frame>
+
+| Field | Value |
+|-------|-------|
+| **Name** | `SALARY` |
+| **Entity Type** | `SALARY` |
+| **Type** | Regex Pattern |
+| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
+| **Action** | Mask |
+| **Confidence Threshold** | `0.8` |
+| **Context Words** | `salary, compensation, pay, wage, income` |
+
+### Regex Pattern Breakdown
+
+| Pattern Component | Meaning |
+|-------------------|---------|
+| `salary:` | Matches the literal text "salary:" |
+| `\s*` | Matches zero or more whitespace characters |
+| `\$` | Matches the dollar sign (escaped) |
+| `\s*` | Matches zero or more whitespace characters after $ |
+| `\d{1,3}` | Matches 1-3 digits (e.g., "1", "50", "125") |
+| `(,\d{3})*` | Matches comma-separated thousands (e.g., ",000", ",500,000") |
+| `(\.\d{2})?` | Optionally matches cents (e.g., ".00", ".50") |
+
+### Example Results
+
+```
+Original: "Employee record shows salary: $125,000.00 annually"
+Redacted: "Employee record shows <SALARY> annually"
+
+Original: "Base salary:$50,000 with bonus potential"
+Redacted: "Base <SALARY> with bonus potential"
+```
+
+<Tip>
+  Adding context words like "salary", "compensation", "pay", "wage", and "income" helps increase detection confidence when these terms appear near the matched pattern, reducing false positives.
+</Tip>
+
+### Enable the Recognizer for Your Deployments
+
+<Warning>
+  Creating a custom recognizer at the organization level does not automatically enable it for your deployments. You must manually enable each recognizer for every deployment where you want it applied.
+</Warning>
+
+After creating your custom recognizer, enable it for each deployment:
+
+<Steps>
+  <Step title="Navigate to Your Deployment">
+    Go to your deployment/automation and open **Settings** → **PII Protection**.
+  </Step>
+
+  <Step title="Select Custom Recognizers">
+    Under **Mask Recognizers**, you'll see your organization-defined recognizers. Check the box next to the recognizers you want to enable.
+
+    <Frame>
+      ![Enable Custom Recognizer](/images/enterprise/pii_mask_recognizers_options.png)
+    </Frame>
+  </Step>
+
+  <Step title="Save Configuration">
+    Save your changes. The recognizer will be active on all subsequent executions for this deployment.
+  </Step>
+</Steps>
+
+<Info>
+  Repeat this process for each deployment where you need the custom recognizer. This gives you granular control over which recognizers are active in different environments (e.g., development vs. production).
+</Info>

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

@@ -1,12 +1,12 @@
 ---
-title: "Deploy Crew"
-description: "Deploying a Crew on CrewAI AMP"
+title: "Deploy to AMP"
+description: "Deploy your Crew or Flow to CrewAI AMP"
 icon: "rocket"
 mode: "wide"
 ---
 
 <Note>
-  After creating a crew locally or through Crew Studio, the next step is
+  After creating a Crew or Flow locally (or through Crew Studio), the next step is
   deploying it to the CrewAI AMP platform. This guide covers multiple deployment
   methods to help you choose the best approach for your workflow.
 </Note>
@@ -14,19 +14,26 @@ mode: "wide"
 ## Prerequisites
 
 <CardGroup cols={2}>
-  <Card title="Crew Ready for Deployment" icon="users">
-    You should have a working crew either built locally or created through Crew
-    Studio
+  <Card title="Project Ready for Deployment" icon="check-circle">
+    You should have a working Crew or Flow that runs successfully locally.
+    Follow our [preparation guide](/en/enterprise/guides/prepare-for-deployment) to verify your project structure.
   </Card>
   <Card title="GitHub Repository" icon="github">
-    Your crew code should be in a GitHub repository (for GitHub integration
+    Your code should be in a GitHub repository (for GitHub integration
     method)
   </Card>
 </CardGroup>
 
+<Info>
+  **Crews vs Flows**: Both project types can be deployed as "automations" on CrewAI AMP.
+  The deployment process is the same, but they have different project structures.
+  See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for details.
+</Info>
+
 ## Option 1: Deploy Using CrewAI CLI
 
-The CLI provides the fastest way to deploy locally developed crews to the Enterprise platform.
+The CLI provides the fastest way to deploy locally developed Crews or Flows to the AMP platform.
+The CLI automatically detects your project type from `pyproject.toml` and builds accordingly.
 
 <Steps>
   <Step title="Install CrewAI CLI">
@@ -128,7 +135,7 @@ crewai deploy remove <deployment_id>
 
 ## Option 2: Deploy Directly via Web Interface
 
-You can also deploy your crews directly through the CrewAI AMP web interface by connecting your GitHub account. This approach doesn't require using the CLI on your local machine.
+You can also deploy your Crews or Flows directly through the CrewAI AMP web interface by connecting your GitHub account. This approach doesn't require using the CLI on your local machine. The platform automatically detects your project type and handles the build appropriately.
 
 <Steps>
 
@@ -282,68 +289,7 @@ For automated deployments in CI/CD pipelines, you can use the CrewAI API to trig
 
   </Steps>
 
-## ⚠️ Environment Variable Security Requirements
-
-<Warning>
-  **Important**: CrewAI AMP has security restrictions on environment variable
-  names that can cause deployment failures if not followed.
-</Warning>
-
-### Blocked Environment Variable Patterns
-
-For security reasons, the following environment variable naming patterns are **automatically filtered** and will cause deployment issues:
-
-**Blocked Patterns:**
-
-- Variables ending with `_TOKEN` (e.g., `MY_API_TOKEN`)
-- Variables ending with `_PASSWORD` (e.g., `DB_PASSWORD`)
-- Variables ending with `_SECRET` (e.g., `API_SECRET`)
-- Variables ending with `_KEY` in certain contexts
-
-**Specific Blocked Variables:**
-
-- `GITHUB_USER`, `GITHUB_TOKEN`
-- `AWS_REGION`, `AWS_DEFAULT_REGION`
-- Various internal CrewAI system variables
-
-### Allowed Exceptions
-
-Some variables are explicitly allowed despite matching blocked patterns:
-
-- `AZURE_AD_TOKEN`
-- `AZURE_OPENAI_AD_TOKEN`
-- `ENTERPRISE_ACTION_TOKEN`
-- `CREWAI_ENTEPRISE_TOOLS_TOKEN`
-
-### How to Fix Naming Issues
-
-If your deployment fails due to environment variable restrictions:
-
-```bash
-# ❌ These will cause deployment failures
-OPENAI_TOKEN=sk-...
-DATABASE_PASSWORD=mypassword
-API_SECRET=secret123
-
-# ✅ Use these naming patterns instead
-OPENAI_API_KEY=sk-...
-DATABASE_CREDENTIALS=mypassword
-API_CONFIG=secret123
-```
-
-### Best Practices
-
-1. **Use standard naming conventions**: `PROVIDER_API_KEY` instead of `PROVIDER_TOKEN`
-2. **Test locally first**: Ensure your crew works with the renamed variables
-3. **Update your code**: Change any references to the old variable names
-4. **Document changes**: Keep track of renamed variables for your team
-
-<Tip>
-  If you encounter deployment failures with cryptic environment variable errors,
-  check your variable names against these patterns first.
-</Tip>
-
-### Interact with Your Deployed Crew
+## Interact with Your Deployed Automation
 
 Once deployment is complete, you can access your crew through:
 
@@ -387,7 +333,108 @@ The Enterprise platform also offers:
 - **Custom Tools Repository**: Create, share, and install tools
 - **Crew Studio**: Build crews through a chat interface without writing code
 
+## Troubleshooting Deployment Failures
+
+If your deployment fails, check these common issues:
+
+### Build Failures
+
+#### Missing uv.lock File
+
+**Symptom**: Build fails early with dependency resolution errors
+
+**Solution**: Generate and commit the lock file:
+
+```bash
+uv lock
+git add uv.lock
+git commit -m "Add uv.lock for deployment"
+git push
+```
+
+<Warning>
+  The `uv.lock` file is required for all deployments. Without it, the platform
+  cannot reliably install your dependencies.
+</Warning>
+
+#### Wrong Project Structure
+
+**Symptom**: "Could not find entry point" or "Module not found" errors
+
+**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
+
+See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams.
+
+#### Missing CrewBase Decorator
+
+**Symptom**: "Crew not found", "Config not found", or agent/task configuration errors
+
+**Solution**: Ensure **all** crew classes use the `@CrewBase` decorator:
+
+```python
+from crewai.project import CrewBase, agent, crew, task
+
+@CrewBase  # This decorator is REQUIRED
+class YourCrew():
+    """Your crew description"""
+
+    @agent
+    def my_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['my_agent'],  # type: ignore[index]
+            verbose=True
+        )
+
+    # ... rest of crew definition
+```
+
+<Info>
+  This applies to standalone Crews AND crews embedded inside Flow projects.
+  Every crew class needs the decorator.
+</Info>
+
+#### Incorrect pyproject.toml Type
+
+**Symptom**: Build succeeds but runtime fails, or unexpected behavior
+
+**Solution**: Verify the `[tool.crewai]` section matches your project type:
+
+```toml
+# For Crew projects:
+[tool.crewai]
+type = "crew"
+
+# For Flow projects:
+[tool.crewai]
+type = "flow"
+```
+
+### Runtime Failures
+
+#### LLM Connection Failures
+
+**Symptom**: API key errors, "model not found", or authentication failures
+
+**Solution**:
+1. Verify your LLM provider's API key is correctly set in environment variables
+2. Ensure the environment variable names match what your code expects
+3. Test locally with the exact same environment variables before deploying
+
+#### Crew Execution Errors
+
+**Symptom**: Crew starts but fails during execution
+
+**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
+
 <Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
   Contact our support team for assistance with deployment issues or questions
-  about the Enterprise platform.
+  about the AMP platform.
 </Card>

docs/en/enterprise/guides/human-in-the-loop.mdx

@@ -5,9 +5,54 @@ icon: "user-check"
 mode: "wide"
 ---
 
-Human-In-The-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. This guide shows you how to implement HITL within CrewAI.
+Human-In-The-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. This guide shows you how to implement HITL within CrewAI Enterprise.
 
-## Setting Up HITL Workflows
+## HITL Approaches in CrewAI
+
+CrewAI offers two approaches for implementing human-in-the-loop workflows:
+
+| Approach | Best For | Version |
+|----------|----------|---------|
+| **Flow-based** (`@human_feedback` decorator) | Production with Enterprise UI, email-first workflows, full platform features | **1.8.0+** |
+| **Webhook-based** | Custom integrations, external systems (Slack, Teams, etc.), legacy setups | All versions |
+
+## Flow-Based HITL with Enterprise Platform
+
+<Note>
+The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**.
+</Note>
+
+When using the `@human_feedback` decorator in your Flows, CrewAI Enterprise provides an **email-first HITL system** that enables anyone with an email address to respond to review requests:
+
+<CardGroup cols={2}>
+  <Card title="Email-First Design" icon="envelope">
+    Responders receive email notifications and can reply directly—no login required.
+  </Card>
+  <Card title="Dashboard Review" icon="desktop">
+    Review and respond to HITL requests in the Enterprise dashboard when preferred.
+  </Card>
+  <Card title="Flexible Routing" icon="route">
+    Route requests to specific emails based on method patterns or pull from flow state.
+  </Card>
+  <Card title="Auto-Response" icon="clock">
+    Configure automatic fallback responses when no human replies within the timeout.
+  </Card>
+</CardGroup>
+
+### Key Benefits
+
+- **External responders**: Anyone with an email can respond, even non-platform users
+- **Dynamic assignment**: Pull assignee email from flow state (e.g., `account_owner_email`)
+- **Simple configuration**: Email-based routing is easier to set up than user/role management
+- **Deployment creator fallback**: If no routing rule matches, the deployment creator is notified
+
+<Tip>
+For implementation details on the `@human_feedback` decorator, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide.
+</Tip>
+
+## Setting Up Webhook-Based HITL Workflows
+
+For custom integrations with external systems like Slack, Microsoft Teams, or your own applications, you can use the webhook-based approach:
 
 <Steps>
     <Step title="Configure Your Task">
@@ -99,3 +144,14 @@ HITL workflows are particularly valuable for:
 - Sensitive or high-stakes operations
 - Creative tasks requiring human judgment
 - Compliance and regulatory reviews
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card title="Flow HITL Management" icon="users-gear" href="/en/enterprise/features/flow-hitl-management">
+    Explore the full Enterprise Flow HITL platform capabilities including email notifications, routing rules, auto-response, and analytics.
+  </Card>
+  <Card title="Human Feedback in Flows" icon="code" href="/en/learn/human-feedback-in-flows">
+    Implementation guide for the `@human_feedback` decorator in your Flows.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,305 @@
+---
+title: "Prepare for Deployment"
+description: "Ensure your Crew or Flow is ready for deployment to CrewAI AMP"
+icon: "clipboard-check"
+mode: "wide"
+---
+
+<Note>
+  Before deploying to CrewAI AMP, it's crucial to verify your project is correctly structured.
+  Both Crews and Flows can be deployed as "automations," but they have different project structures
+  and requirements that must be met for successful deployment.
+</Note>
+
+## Understanding Automations
+
+In CrewAI AMP, **automations** is the umbrella term for deployable Agentic AI projects. An automation can be either:
+
+- **A Crew**: A standalone team of AI agents working together on tasks
+- **A Flow**: An orchestrated workflow that can combine multiple crews, direct LLM calls, and procedural logic
+
+Understanding which type you're deploying is essential because they have different project structures and entry points.
+
+## Crews vs Flows: Key Differences
+
+<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.
+  </Card>
+  <Card title="Flow Projects" icon="diagram-project">
+    Orchestrated workflows with embedded crews in a `crews/` folder. Best for complex, multi-stage processes.
+  </Card>
+</CardGroup>
+
+| 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` |
+| **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/` |
+| **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:
+
+```
+my_crew/
+├── .gitignore
+├── pyproject.toml          # Must have type = "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
+```
+
+<Warning>
+  The nested `src/project_name/` structure is critical for Crews.
+  Placing files at the wrong level will cause deployment failures.
+</Warning>
+
+### Flow Project Structure
+
+When you run `crewai create flow my_flow`, you get this structure:
+
+```
+my_flow/
+├── .gitignore
+├── pyproject.toml          # Must have type = "flow"
+├── README.md
+├── .env
+├── uv.lock                  # REQUIRED for deployment
+└── src/
+    └── my_flow/
+        ├── __init__.py
+        ├── main.py          # Entry point with kickoff() function + Flow class
+        ├── crews/           # Embedded crews folder
+        │   └── poem_crew/
+        │       ├── __init__.py
+        │       ├── poem_crew.py  # Crew with @CrewBase decorator
+        │       └── config/
+        │           ├── agents.yaml
+        │           └── tasks.yaml
+        └── tools/
+            ├── __init__.py
+            └── custom_tool.py
+```
+
+<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.
+</Info>
+
+## Pre-Deployment Checklist
+
+Use this checklist to verify your project is ready for deployment.
+
+### 1. Verify pyproject.toml Configuration
+
+Your `pyproject.toml` must include the correct `[tool.crewai]` section:
+
+<Tabs>
+  <Tab title="For Crews">
+    ```toml
+    [tool.crewai]
+    type = "crew"
+    ```
+  </Tab>
+  <Tab title="For Flows">
+    ```toml
+    [tool.crewai]
+    type = "flow"
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  If the `type` doesn't match your project structure, the build will fail or
+  the automation won't run correctly.
+</Warning>
+
+### 2. Ensure uv.lock File Exists
+
+CrewAI uses `uv` for dependency management. The `uv.lock` file ensures reproducible builds and is **required** for deployment.
+
+```bash
+# Generate or update the lock file
+uv lock
+
+# Verify it exists
+ls -la uv.lock
+```
+
+If the file doesn't exist, run `uv lock` and commit it to your repository:
+
+```bash
+uv lock
+git add uv.lock
+git commit -m "Add uv.lock for deployment"
+git push
+```
+
+### 3. Validate CrewBase Decorator Usage
+
+**Every crew class must use the `@CrewBase` decorator.** This applies to:
+
+- Standalone crew projects
+- Crews embedded inside Flow projects
+
+```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
+
+@CrewBase  # This decorator is REQUIRED
+class MyCrew():
+    """My crew description"""
+
+    agents: List[BaseAgent]
+    tasks: List[Task]
+
+    @agent
+    def my_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['my_agent'],  # type: ignore[index]
+            verbose=True
+        )
+
+    @task
+    def my_task(self) -> Task:
+        return Task(
+            config=self.tasks_config['my_task']  # type: ignore[index]
+        )
+
+    @crew
+    def crew(self) -> Crew:
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            process=Process.sequential,
+            verbose=True,
+        )
+```
+
+<Warning>
+  If you forget the `@CrewBase` decorator, your deployment will fail with
+  errors about missing agents or tasks configurations.
+</Warning>
+
+### 4. Check Project Entry Points
+
+Both Crews and Flows have their entry point in `src/project_name/main.py`:
+
+<Tabs>
+  <Tab title="For Crews">
+    The entry point uses a `run()` function:
+
+    ```python
+    # src/my_crew/main.py
+    from my_crew.crew import MyCrew
+
+    def run():
+        """Run the crew."""
+        inputs = {'topic': 'AI in Healthcare'}
+        result = MyCrew().crew().kickoff(inputs=inputs)
+        return result
+
+    if __name__ == "__main__":
+        run()
+    ```
+  </Tab>
+  <Tab title="For Flows">
+    The entry point uses a `kickoff()` function with a Flow class:
+
+    ```python
+    # src/my_flow/main.py
+    from crewai.flow import Flow, listen, start
+    from my_flow.crews.poem_crew.poem_crew import PoemCrew
+
+    class MyFlow(Flow):
+        @start()
+        def begin(self):
+            # Flow logic here
+            result = PoemCrew().crew().kickoff(inputs={...})
+            return result
+
+    def kickoff():
+        """Run the flow."""
+        MyFlow().kickoff()
+
+    if __name__ == "__main__":
+        kickoff()
+    ```
+  </Tab>
+</Tabs>
+
+### 5. Prepare Environment Variables
+
+Before deployment, ensure you have:
+
+1. **LLM API keys** ready (OpenAI, Anthropic, Google, etc.)
+2. **Tool API keys** if using external tools (Serper, etc.)
+
+<Tip>
+  Test your project locally with the same environment variables before deploying
+  to catch configuration issues early.
+</Tip>
+
+## Quick Validation Commands
+
+Run these commands from your project root to quickly verify your setup:
+
+```bash
+# 1. Check project type in pyproject.toml
+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/"
+
+# 4. For 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
+grep -r "@CrewBase" . --include="*.py"
+```
+
+## Common Setup Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| 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 `run()` or `kickoff()` | Cannot start automation | Add correct entry function |
+
+## Next Steps
+
+Once your project passes all checklist items, you're ready to deploy:
+
+<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
+  Follow the deployment guide to deploy your Crew or Flow to CrewAI AMP using
+  the CLI, web interface, or CI/CD integration.
+</Card>

docs/en/enterprise/integrations/google_contacts.mdx

@@ -224,6 +224,60 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `groupFields` (string, optional): Fields to include (e.g., 'name,memberCount,clientData'). Default: name,memberCount
 
   </Accordion>
+
+  <Accordion title="google_contacts/get_contact_group">
+    **Description:** Get a specific contact group by resource name.
+
+    **Parameters:**
+    - `resourceName` (string, required): The resource name of the contact group (e.g., 'contactGroups/myContactGroup')
+    - `maxMembers` (integer, optional): Maximum number of members to include. Minimum: 0, Maximum: 20000
+    - `groupFields` (string, optional): Fields to include (e.g., 'name,memberCount,clientData'). Default: name,memberCount
+
+  </Accordion>
+
+  <Accordion title="google_contacts/create_contact_group">
+    **Description:** Create a new contact group (label).
+
+    **Parameters:**
+    - `name` (string, required): The name of the contact group
+    - `clientData` (array, optional): Client-specific data
+      ```json
+      [
+        {
+          "key": "data_key",
+          "value": "data_value"
+        }
+      ]
+      ```
+
+  </Accordion>
+
+  <Accordion title="google_contacts/update_contact_group">
+    **Description:** Update a contact group's information.
+
+    **Parameters:**
+    - `resourceName` (string, required): The resource name of the contact group (e.g., 'contactGroups/myContactGroup')
+    - `name` (string, required): The name of the contact group
+    - `clientData` (array, optional): Client-specific data
+      ```json
+      [
+        {
+          "key": "data_key",
+          "value": "data_value"
+        }
+      ]
+      ```
+
+  </Accordion>
+
+  <Accordion title="google_contacts/delete_contact_group">
+    **Description:** Delete a contact group.
+
+    **Parameters:**
+    - `resourceName` (string, required): The resource name of the contact group to delete (e.g., 'contactGroups/myContactGroup')
+    - `deleteContacts` (boolean, optional): Whether to delete contacts in the group as well. Default: false
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/enterprise/integrations/google_docs.mdx

@@ -132,6 +132,297 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `endIndex` (integer, required): The end index of the range.
 
   </Accordion>
+
+  <Accordion title="google_docs/create_document_with_content">
+    **Description:** Create a new Google Document with content in one action.
+
+    **Parameters:**
+    - `title` (string, required): The title for the new document. Appears at the top of the document and in Google Drive.
+    - `content` (string, optional): The text content to insert into the document. Use `\n` for new paragraphs.
+
+  </Accordion>
+
+  <Accordion title="google_docs/append_text">
+    **Description:** Append text to the end of a Google Document. Automatically inserts at the document end without needing to specify an index.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID from create_document response or URL.
+    - `text` (string, required): Text to append at the end of the document. Use `\n` for new paragraphs.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_text_bold">
+    **Description:** Make text bold or remove bold formatting in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `bold` (boolean, required): Set `true` to make bold, `false` to remove bold.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_text_italic">
+    **Description:** Make text italic or remove italic formatting in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `italic` (boolean, required): Set `true` to make italic, `false` to remove italic.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_text_underline">
+    **Description:** Add or remove underline formatting from text in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `underline` (boolean, required): Set `true` to underline, `false` to remove underline.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_text_strikethrough">
+    **Description:** Add or remove strikethrough formatting from text in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `strikethrough` (boolean, required): Set `true` to add strikethrough, `false` to remove.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_font_size">
+    **Description:** Change the font size of text in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `fontSize` (number, required): Font size in points. Common sizes: 10, 11, 12, 14, 16, 18, 24, 36.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_text_color">
+    **Description:** Change the color of text using RGB values (0-1 scale) in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to format.
+    - `endIndex` (integer, required): End position of text to format (exclusive).
+    - `red` (number, required): Red component (0-1). Example: `1` for full red.
+    - `green` (number, required): Green component (0-1). Example: `0.5` for half green.
+    - `blue` (number, required): Blue component (0-1). Example: `0` for no blue.
+
+  </Accordion>
+
+  <Accordion title="google_docs/create_hyperlink">
+    **Description:** Turn existing text into a clickable hyperlink in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of text to make into a link.
+    - `endIndex` (integer, required): End position of text to make into a link (exclusive).
+    - `url` (string, required): The URL the link should point to. Example: `"https://example.com"`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/apply_heading_style">
+    **Description:** Apply a heading or paragraph style to a text range in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of paragraph(s) to style.
+    - `endIndex` (integer, required): End position of paragraph(s) to style.
+    - `style` (string, required): The style to apply. Enum: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_paragraph_alignment">
+    **Description:** Set text alignment for paragraphs in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of paragraph(s) to align.
+    - `endIndex` (integer, required): End position of paragraph(s) to align.
+    - `alignment` (string, required): Text alignment. Enum: `START` (left), `CENTER`, `END` (right), `JUSTIFIED`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/set_line_spacing">
+    **Description:** Set line spacing for paragraphs in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of paragraph(s).
+    - `endIndex` (integer, required): End position of paragraph(s).
+    - `lineSpacing` (number, required): Line spacing as percentage. `100` = single, `115` = 1.15x, `150` = 1.5x, `200` = double.
+
+  </Accordion>
+
+  <Accordion title="google_docs/create_paragraph_bullets">
+    **Description:** Convert paragraphs to a bulleted or numbered list in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of paragraphs to convert to list.
+    - `endIndex` (integer, required): End position of paragraphs to convert to list.
+    - `bulletPreset` (string, required): Bullet/numbering style. Enum: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/delete_paragraph_bullets">
+    **Description:** Remove bullets or numbering from paragraphs in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `startIndex` (integer, required): Start position of list paragraphs.
+    - `endIndex` (integer, required): End position of list paragraphs.
+
+  </Accordion>
+
+  <Accordion title="google_docs/insert_table_with_content">
+    **Description:** Insert a table with content into a Google Document in one action. Provide content as a 2D array.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `rows` (integer, required): Number of rows in the table.
+    - `columns` (integer, required): Number of columns in the table.
+    - `index` (integer, optional): Position to insert the table. If not provided, the table is inserted at the end of the document.
+    - `content` (array, required): Table content as a 2D array. Each inner array is a row. Example: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/insert_table_row">
+    **Description:** Insert a new row above or below a reference cell in an existing table.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table. Get from get_document.
+    - `rowIndex` (integer, required): Row index (0-based) of reference cell.
+    - `columnIndex` (integer, optional): Column index (0-based) of reference cell. Default is `0`.
+    - `insertBelow` (boolean, optional): If `true`, insert below the reference row. If `false`, insert above. Default is `true`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/insert_table_column">
+    **Description:** Insert a new column left or right of a reference cell in an existing table.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table.
+    - `rowIndex` (integer, optional): Row index (0-based) of reference cell. Default is `0`.
+    - `columnIndex` (integer, required): Column index (0-based) of reference cell.
+    - `insertRight` (boolean, optional): If `true`, insert to the right. If `false`, insert to the left. Default is `true`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/delete_table_row">
+    **Description:** Delete a row from an existing table in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table.
+    - `rowIndex` (integer, required): Row index (0-based) to delete.
+    - `columnIndex` (integer, optional): Column index (0-based) of any cell in the row. Default is `0`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/delete_table_column">
+    **Description:** Delete a column from an existing table in a Google Document.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table.
+    - `rowIndex` (integer, optional): Row index (0-based) of any cell in the column. Default is `0`.
+    - `columnIndex` (integer, required): Column index (0-based) to delete.
+
+  </Accordion>
+
+  <Accordion title="google_docs/merge_table_cells">
+    **Description:** Merge a range of table cells into a single cell. Content from all cells is preserved.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table.
+    - `rowIndex` (integer, required): Starting row index (0-based) for the merge.
+    - `columnIndex` (integer, required): Starting column index (0-based) for the merge.
+    - `rowSpan` (integer, required): Number of rows to merge.
+    - `columnSpan` (integer, required): Number of columns to merge.
+
+  </Accordion>
+
+  <Accordion title="google_docs/unmerge_table_cells">
+    **Description:** Unmerge previously merged table cells back into individual cells.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `tableStartIndex` (integer, required): The start index of the table.
+    - `rowIndex` (integer, required): Row index (0-based) of the merged cell.
+    - `columnIndex` (integer, required): Column index (0-based) of the merged cell.
+    - `rowSpan` (integer, required): Number of rows the merged cell spans.
+    - `columnSpan` (integer, required): Number of columns the merged cell spans.
+
+  </Accordion>
+
+  <Accordion title="google_docs/insert_inline_image">
+    **Description:** Insert an image from a public URL into a Google Document. The image must be publicly accessible, under 50MB, and in PNG/JPEG/GIF format.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `uri` (string, required): Public URL of the image. Must be accessible without authentication.
+    - `index` (integer, optional): Position to insert the image. If not provided, the image is inserted at the end of the document. Default is `1`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/insert_section_break">
+    **Description:** Insert a section break to create document sections with different formatting.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `index` (integer, required): Position to insert the section break.
+    - `sectionType` (string, required): The type of section break. Enum: `CONTINUOUS` (stays on same page), `NEXT_PAGE` (starts a new page).
+
+  </Accordion>
+
+  <Accordion title="google_docs/create_header">
+    **Description:** Create a header for the document. Returns a headerId which can be used with insert_text to add header content.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `type` (string, optional): Header type. Enum: `DEFAULT`. Default is `DEFAULT`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/create_footer">
+    **Description:** Create a footer for the document. Returns a footerId which can be used with insert_text to add footer content.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `type` (string, optional): Footer type. Enum: `DEFAULT`. Default is `DEFAULT`.
+
+  </Accordion>
+
+  <Accordion title="google_docs/delete_header">
+    **Description:** Delete a header from the document. Use get_document to find the headerId.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `headerId` (string, required): The header ID to delete. Get from get_document response.
+
+  </Accordion>
+
+  <Accordion title="google_docs/delete_footer">
+    **Description:** Delete a footer from the document. Use get_document to find the footerId.
+
+    **Parameters:**
+    - `documentId` (string, required): The document ID.
+    - `footerId` (string, required): The footer ID to delete. Get from get_document response.
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/enterprise/integrations/google_slides.mdx

@@ -62,6 +62,22 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="google_slides/get_presentation_metadata">
+    **Description:** Get lightweight metadata about a presentation (title, slide count, slide IDs). Use this first before fetching full content.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation to retrieve.
+
+  </Accordion>
+
+  <Accordion title="google_slides/get_presentation_text">
+    **Description:** Extract all text content from a presentation. Returns slide IDs and text from shapes and tables only (no formatting).
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+
+  </Accordion>
+
   <Accordion title="google_slides/get_presentation">
     **Description:** Retrieves a presentation by ID.
 
@@ -96,6 +112,15 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="google_slides/get_slide_text">
+    **Description:** Extract text content from a single slide. Returns only text from shapes and tables (no formatting or styling).
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `pageObjectId` (string, required): The ID of the slide/page to get text from.
+
+  </Accordion>
+
   <Accordion title="google_slides/get_page">
     **Description:** Retrieves a specific page by its ID.
 
@@ -114,6 +139,120 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="google_slides/create_slide">
+    **Description:** Add an additional blank slide to a presentation. New presentations already have one blank slide - check get_presentation_metadata first. For slides with title/body areas, use create_slide_with_layout instead.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `insertionIndex` (integer, optional): Where to insert the slide (0-based). If omitted, adds at the end.
+
+  </Accordion>
+
+  <Accordion title="google_slides/create_slide_with_layout">
+    **Description:** Create a slide with a predefined layout containing placeholder areas for title, body, etc. This is better than create_slide for structured content. After creating, use get_page to find placeholder IDs, then insert text into them.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `layout` (string, required): Layout type. One of: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. TITLE_AND_BODY is best for title+description. TITLE for title-only slides. SECTION_HEADER for section dividers.
+    - `insertionIndex` (integer, optional): Where to insert (0-based). Omit to add at end.
+
+  </Accordion>
+
+  <Accordion title="google_slides/create_text_box">
+    **Description:** Create a text box on a slide with content. Use this for titles, descriptions, paragraphs - not tables. Optionally specify position (x, y) and size (width, height) in EMU units (914400 EMU = 1 inch).
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to add the text box to.
+    - `text` (string, required): The text content for the text box.
+    - `x` (integer, optional): X position in EMU (914400 = 1 inch). Default: 914400 (1 inch from left).
+    - `y` (integer, optional): Y position in EMU (914400 = 1 inch). Default: 914400 (1 inch from top).
+    - `width` (integer, optional): Width in EMU. Default: 7315200 (~8 inches).
+    - `height` (integer, optional): Height in EMU. Default: 914400 (~1 inch).
+
+  </Accordion>
+
+  <Accordion title="google_slides/delete_slide">
+    **Description:** Remove a slide from the presentation. Use get_presentation first to find the slide ID.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The object ID of the slide to delete. Get from get_presentation.
+
+  </Accordion>
+
+  <Accordion title="google_slides/duplicate_slide">
+    **Description:** Create a copy of an existing slide. The duplicate is inserted immediately after the original.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The object ID of the slide to duplicate. Get from get_presentation.
+
+  </Accordion>
+
+  <Accordion title="google_slides/move_slides">
+    **Description:** Reorder slides by moving them to a new position. Slide IDs must be in their current presentation order (no duplicates).
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideIds` (array of strings, required): Array of slide IDs to move. Must be in current presentation order.
+    - `insertionIndex` (integer, required): Target position (0-based). 0 = beginning, slide count = end.
+
+  </Accordion>
+
+  <Accordion title="google_slides/insert_youtube_video">
+    **Description:** Embed a YouTube video on a slide. The video ID is the value after "v=" in YouTube URLs (e.g., for youtube.com/watch?v=abc123, use "abc123").
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to add the video to. Get from get_presentation.
+    - `videoId` (string, required): The YouTube video ID (the value after v= in the URL).
+
+  </Accordion>
+
+  <Accordion title="google_slides/insert_drive_video">
+    **Description:** Embed a video from Google Drive on a slide. The file ID can be found in the Drive file URL.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to add the video to. Get from get_presentation.
+    - `fileId` (string, required): The Google Drive file ID of the video.
+
+  </Accordion>
+
+  <Accordion title="google_slides/set_slide_background_image">
+    **Description:** Set a background image for a slide. The image URL must be publicly accessible.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to set the background for. Get from get_presentation.
+    - `imageUrl` (string, required): Publicly accessible URL of the image to use as background.
+
+  </Accordion>
+
+  <Accordion title="google_slides/create_table">
+    **Description:** Create an empty table on a slide. To create a table with content, use create_table_with_content instead.
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to add the table to. Get from get_presentation.
+    - `rows` (integer, required): Number of rows in the table.
+    - `columns` (integer, required): Number of columns in the table.
+
+  </Accordion>
+
+  <Accordion title="google_slides/create_table_with_content">
+    **Description:** Create a table with content in one action. Provide content as a 2D array where each inner array is a row. Example: [["Header1", "Header2"], ["Row1Col1", "Row1Col2"]].
+
+    **Parameters:**
+    - `presentationId` (string, required): The ID of the presentation.
+    - `slideId` (string, required): The ID of the slide to add the table to. Get from get_presentation.
+    - `rows` (integer, required): Number of rows in the table.
+    - `columns` (integer, required): Number of columns in the table.
+    - `content` (array, required): Table content as 2D array. Each inner array is a row. Example: [["Year", "Revenue"], ["2023", "$10M"]].
+
+  </Accordion>
+
   <Accordion title="google_slides/import_data_from_sheet">
     **Description:** Imports data from a Google Sheet into a presentation.
 

docs/en/enterprise/integrations/microsoft_excel.mdx

@@ -169,6 +169,16 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="microsoft_excel/get_table_data">
+    **Description:** Get data from a specific table in an Excel worksheet.
+
+    **Parameters:**
+    - `file_id` (string, required): The ID of the Excel file
+    - `worksheet_name` (string, required): Name of the worksheet
+    - `table_name` (string, required): Name of the table
+
+  </Accordion>
+
   <Accordion title="microsoft_excel/create_chart">
     **Description:** Create a chart in an Excel worksheet.
 
@@ -201,6 +211,15 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="microsoft_excel/get_used_range_metadata">
+    **Description:** Get the used range metadata (dimensions only, no data) of an Excel worksheet.
+
+    **Parameters:**
+    - `file_id` (string, required): The ID of the Excel file
+    - `worksheet_name` (string, required): Name of the worksheet
+
+  </Accordion>
+
   <Accordion title="microsoft_excel/list_charts">
     **Description:** Get all charts in an Excel worksheet.
 

docs/en/enterprise/integrations/microsoft_onedrive.mdx

@@ -151,6 +151,49 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `item_id` (string, required): The ID of the file.
 
   </Accordion>
+
+  <Accordion title="microsoft_onedrive/list_files_by_path">
+    **Description:** List files and folders in a specific OneDrive path.
+
+    **Parameters:**
+    - `folder_path` (string, required): The folder path (e.g., 'Documents/Reports').
+    - `top` (integer, optional): Number of items to retrieve (max 1000). Default is `50`.
+    - `orderby` (string, optional): Order by field (e.g., "name asc", "lastModifiedDateTime desc"). Default is "name asc".
+
+  </Accordion>
+
+  <Accordion title="microsoft_onedrive/get_recent_files">
+    **Description:** Get recently accessed files from OneDrive.
+
+    **Parameters:**
+    - `top` (integer, optional): Number of items to retrieve (max 200). Default is `25`.
+
+  </Accordion>
+
+  <Accordion title="microsoft_onedrive/get_shared_with_me">
+    **Description:** Get files and folders shared with the user.
+
+    **Parameters:**
+    - `top` (integer, optional): Number of items to retrieve (max 200). Default is `50`.
+    - `orderby` (string, optional): Order by field. Default is "name asc".
+
+  </Accordion>
+
+  <Accordion title="microsoft_onedrive/get_file_by_path">
+    **Description:** Get information about a specific file or folder by path.
+
+    **Parameters:**
+    - `file_path` (string, required): The file or folder path (e.g., 'Documents/report.docx').
+
+  </Accordion>
+
+  <Accordion title="microsoft_onedrive/download_file_by_path">
+    **Description:** Download a file from OneDrive by its path.
+
+    **Parameters:**
+    - `file_path` (string, required): The file path (e.g., 'Documents/report.docx').
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/enterprise/integrations/microsoft_outlook.mdx

@@ -133,6 +133,74 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `companyName` (string, optional): Contact's company name.
 
   </Accordion>
+
+  <Accordion title="microsoft_outlook/get_message">
+    **Description:** Get a specific email message by ID.
+
+    **Parameters:**
+    - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action.
+    - `select` (string, optional): Comma-separated list of properties to return. Example: "id,subject,body,from,receivedDateTime". Default is "id,subject,body,from,toRecipients,receivedDateTime".
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/reply_to_email">
+    **Description:** Reply to an email message.
+
+    **Parameters:**
+    - `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get_messages action.
+    - `comment` (string, required): The reply message content. Can be plain text or HTML. The original message will be quoted below this content.
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/forward_email">
+    **Description:** Forward an email message.
+
+    **Parameters:**
+    - `message_id` (string, required): The unique identifier of the message to forward. Obtain from get_messages action.
+    - `to_recipients` (array, required): Array of recipient email addresses to forward to. Example: ["john@example.com", "jane@example.com"].
+    - `comment` (string, optional): Optional message to include above the forwarded content. Can be plain text or HTML.
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/mark_message_read">
+    **Description:** Mark a message as read or unread.
+
+    **Parameters:**
+    - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action.
+    - `is_read` (boolean, required): Set to true to mark as read, false to mark as unread.
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/delete_message">
+    **Description:** Delete an email message.
+
+    **Parameters:**
+    - `message_id` (string, required): The unique identifier of the message to delete. Obtain from get_messages action.
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/update_event">
+    **Description:** Update an existing calendar event.
+
+    **Parameters:**
+    - `event_id` (string, required): The unique identifier of the event. Obtain from get_calendar_events action.
+    - `subject` (string, optional): New subject/title for the event.
+    - `start_time` (string, optional): New start time in ISO 8601 format (e.g., "2024-01-20T10:00:00"). REQUIRED: Must also provide start_timezone when using this field.
+    - `start_timezone` (string, optional): Timezone for start time. REQUIRED when updating start_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC".
+    - `end_time` (string, optional): New end time in ISO 8601 format. REQUIRED: Must also provide end_timezone when using this field.
+    - `end_timezone` (string, optional): Timezone for end time. REQUIRED when updating end_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC".
+    - `location` (string, optional): New location for the event.
+    - `body` (string, optional): New body/description for the event. Supports HTML formatting.
+
+  </Accordion>
+
+  <Accordion title="microsoft_outlook/delete_event">
+    **Description:** Delete a calendar event.
+
+    **Parameters:**
+    - `event_id` (string, required): The unique identifier of the event to delete. Obtain from get_calendar_events action.
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/enterprise/integrations/microsoft_sharepoint.mdx

@@ -78,6 +78,17 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
+  <Accordion title="microsoft_sharepoint/get_drives">
+    **Description:** List all document libraries (drives) in a SharePoint site. Use this to discover available libraries before using file operations.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `top` (integer, optional): Maximum number of drives to return per page (1-999). Default is 100
+    - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,webUrl,driveType')
+
+  </Accordion>
+
   <Accordion title="microsoft_sharepoint/get_site_lists">
     **Description:** Get all lists in a SharePoint site.
 
@@ -159,20 +170,317 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
 
   </Accordion>
 
-  <Accordion title="microsoft_sharepoint/get_drive_items">
-    **Description:** Get files and folders from a SharePoint document library.
+  <Accordion title="microsoft_sharepoint/list_files">
+    **Description:** Retrieve files and folders from a SharePoint document library. By default lists the root folder, but you can navigate into subfolders by providing a folder_id.
 
     **Parameters:**
-    - `site_id` (string, required): The ID of the SharePoint site
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `folder_id` (string, optional): The ID of the folder to list contents from. Use 'root' for the root folder, or provide a folder ID from a previous list_files call. Default is 'root'
+    - `top` (integer, optional): Maximum number of items to return per page (1-1000). Default is 50
+    - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results
+    - `orderby` (string, optional): Sort order for results (e.g., 'name asc', 'size desc', 'lastModifiedDateTime desc'). Default is 'name asc'
+    - `filter` (string, optional): OData filter to narrow results (e.g., 'file ne null' for files only, 'folder ne null' for folders only)
+    - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime')
 
   </Accordion>
 
-  <Accordion title="microsoft_sharepoint/delete_drive_item">
-    **Description:** Delete a file or folder from SharePoint document library.
+  <Accordion title="microsoft_sharepoint/delete_file">
+    **Description:** Delete a file or folder from a SharePoint document library. For folders, all contents are deleted recursively. Items are moved to the site recycle bin.
 
     **Parameters:**
-    - `site_id` (string, required): The ID of the SharePoint site
-    - `item_id` (string, required): The ID of the file or folder to delete
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the file or folder to delete. Obtain from list_files
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/list_files_by_path">
+    **Description:** List files and folders in a SharePoint document library folder by its path. More efficient than multiple list_files calls for deep navigation.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `folder_path` (string, required): The full path to the folder without leading/trailing slashes (e.g., 'Documents', 'Reports/2024/Q1')
+    - `top` (integer, optional): Maximum number of items to return per page (1-1000). Default is 50
+    - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results
+    - `orderby` (string, optional): Sort order for results (e.g., 'name asc', 'size desc'). Default is 'name asc'
+    - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/download_file">
+    **Description:** Download raw file content from a SharePoint document library. Use only for plain text files (.txt, .csv, .json). For Excel files, use the Excel-specific actions. For Word files, use get_word_document_content.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the file to download. Obtain from list_files or list_files_by_path
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_file_info">
+    **Description:** Retrieve detailed metadata for a specific file or folder in a SharePoint document library, including name, size, created/modified dates, and author information.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the file or folder. Obtain from list_files or list_files_by_path
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/create_folder">
+    **Description:** Create a new folder in a SharePoint document library. By default creates the folder in the root; use parent_id to create subfolders.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `folder_name` (string, required): Name for the new folder. Cannot contain: \ / : * ? " < > |
+    - `parent_id` (string, optional): The ID of the parent folder. Use 'root' for the document library root, or provide a folder ID from list_files. Default is 'root'
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/search_files">
+    **Description:** Search for files and folders in a SharePoint document library by keywords. Searches file names, folder names, and file contents for Office documents. Do not use wildcards or special characters.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `query` (string, required): Search keywords (e.g., 'report', 'budget 2024'). Wildcards like *.txt are not supported
+    - `top` (integer, optional): Maximum number of results to return per page (1-1000). Default is 50
+    - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results
+    - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/copy_file">
+    **Description:** Copy a file or folder to a new location within SharePoint. The original item remains unchanged. The copy operation is asynchronous for large files.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the file or folder to copy. Obtain from list_files or search_files
+    - `destination_folder_id` (string, required): The ID of the destination folder. Use 'root' for the root folder, or a folder ID from list_files
+    - `new_name` (string, optional): New name for the copy. If not provided, the original name is used
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/move_file">
+    **Description:** Move a file or folder to a new location within SharePoint. The item is removed from its original location. For folders, all contents are moved as well.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the file or folder to move. Obtain from list_files or search_files
+    - `destination_folder_id` (string, required): The ID of the destination folder. Use 'root' for the root folder, or a folder ID from list_files
+    - `new_name` (string, optional): New name for the moved item. If not provided, the original name is kept
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_worksheets">
+    **Description:** List all worksheets (tabs) in an Excel workbook stored in a SharePoint document library. Use the returned worksheet name with other Excel actions.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,position,visibility')
+    - `filter` (string, optional): OData filter expression (e.g., "visibility eq 'Visible'" to exclude hidden sheets)
+    - `top` (integer, optional): Maximum number of worksheets to return. Minimum: 1, Maximum: 999
+    - `orderby` (string, optional): Sort order (e.g., 'position asc' to return sheets in tab order)
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/create_excel_worksheet">
+    **Description:** Create a new worksheet (tab) in an Excel workbook stored in a SharePoint document library. The new sheet is added at the end of the tab list.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `name` (string, required): Name for the new worksheet. Maximum 31 characters. Cannot contain: \ / * ? : [ ]. Must be unique within the workbook
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_range_data">
+    **Description:** Retrieve cell values from a specific range in an Excel worksheet stored in SharePoint. For reading all data without knowing dimensions, use get_excel_used_range instead.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet (tab) to read from. Obtain from get_excel_worksheets. Case-sensitive
+    - `range` (string, required): Cell range in A1 notation (e.g., 'A1:C10', 'A:C', '1:5', 'A1')
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/update_excel_range_data">
+    **Description:** Write values to a specific range in an Excel worksheet stored in SharePoint. Overwrites existing cell contents. The values array dimensions must match the range dimensions exactly.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet (tab) to update. Obtain from get_excel_worksheets. Case-sensitive
+    - `range` (string, required): Cell range in A1 notation where values will be written (e.g., 'A1:C3' for a 3x3 block)
+    - `values` (array, required): 2D array of values (rows containing cells). Example for A1:B2: [["Header1", "Header2"], ["Value1", "Value2"]]. Use null to clear a cell
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_used_range_metadata">
+    **Description:** Return only the metadata (address and dimensions) of the used range in a worksheet, without the actual cell values. Ideal for large files to understand spreadsheet size before reading data in chunks.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet (tab) to read. Obtain from get_excel_worksheets. Case-sensitive
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_used_range">
+    **Description:** Retrieve all cells containing data in a worksheet stored in SharePoint. Do not use for files larger than 2MB. For large files, use get_excel_used_range_metadata first, then get_excel_range_data to read in smaller chunks.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet (tab) to read. Obtain from get_excel_worksheets. Case-sensitive
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text,rowCount,columnCount')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_cell">
+    **Description:** Retrieve the value of a single cell by row and column index from an Excel file in SharePoint. Indices are 0-based (row 0 = Excel row 1, column 0 = column A).
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet (tab). Obtain from get_excel_worksheets. Case-sensitive
+    - `row` (integer, required): 0-based row index (row 0 = Excel row 1). Valid range: 0-1048575
+    - `column` (integer, required): 0-based column index (column 0 = A, column 1 = B). Valid range: 0-16383
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/add_excel_table">
+    **Description:** Convert a cell range into a formatted Excel table with filtering, sorting, and structured data capabilities. Tables enable add_excel_table_row for appending data.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet containing the data range. Obtain from get_excel_worksheets
+    - `range` (string, required): Cell range to convert into a table, including headers and data (e.g., 'A1:D10' where A1:D1 contains column headers)
+    - `has_headers` (boolean, optional): Set to true if the first row contains column headers. Default is true
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_tables">
+    **Description:** List all tables in a specific Excel worksheet stored in SharePoint. Returns table properties including id, name, showHeaders, and showTotals.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet to get tables from. Obtain from get_excel_worksheets
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/add_excel_table_row">
+    **Description:** Append a new row to the end of an Excel table in a SharePoint file. The values array must have the same number of elements as the table has columns.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets
+    - `table_name` (string, required): Name of the table to add the row to (e.g., 'Table1'). Obtain from get_excel_tables. Case-sensitive
+    - `values` (array, required): Array of cell values for the new row, one per column in table order (e.g., ["John Doe", "john@example.com", 25])
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_excel_table_data">
+    **Description:** Get all rows from an Excel table in a SharePoint file as a data range. Easier than get_excel_range_data when working with structured tables since you don't need to know the exact range.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets
+    - `table_name` (string, required): Name of the table to get data from (e.g., 'Table1'). Obtain from get_excel_tables. Case-sensitive
+    - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text')
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/create_excel_chart">
+    **Description:** Create a chart visualization in an Excel worksheet stored in SharePoint from a data range. The chart is embedded in the worksheet.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet where the chart will be created. Obtain from get_excel_worksheets
+    - `chart_type` (string, required): Chart type (e.g., 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut')
+    - `source_data` (string, required): Data range for the chart in A1 notation, including headers (e.g., 'A1:B10')
+    - `series_by` (string, optional): How data series are organized: 'Auto', 'Columns', or 'Rows'. Default is 'Auto'
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/list_excel_charts">
+    **Description:** List all charts embedded in an Excel worksheet stored in SharePoint. Returns chart properties including id, name, chartType, height, width, and position.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet to list charts from. Obtain from get_excel_worksheets
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/delete_excel_worksheet">
+    **Description:** Permanently remove a worksheet (tab) and all its contents from an Excel workbook stored in SharePoint. Cannot be undone. A workbook must have at least one worksheet.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet to delete. Case-sensitive. All data, tables, and charts on this sheet will be permanently removed
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/delete_excel_table">
+    **Description:** Remove a table from an Excel worksheet in SharePoint. This deletes the table structure (filtering, formatting, table features) but preserves the underlying cell data.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+    - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets
+    - `table_name` (string, required): Name of the table to delete (e.g., 'Table1'). Obtain from get_excel_tables. The data in the cells will remain after table deletion
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/list_excel_names">
+    **Description:** Retrieve all named ranges defined in an Excel workbook stored in SharePoint. Named ranges are user-defined labels for cell ranges (e.g., 'SalesData' for A1:D100).
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files
+
+  </Accordion>
+
+  <Accordion title="microsoft_sharepoint/get_word_document_content">
+    **Description:** Download and extract text content from a Word document (.docx) stored in a SharePoint document library. This is the recommended way to read Word documents from SharePoint.
+
+    **Parameters:**
+    - `site_id` (string, required): The full SharePoint site identifier from get_sites
+    - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs
+    - `item_id` (string, required): The unique identifier of the Word document (.docx) in SharePoint. Obtain from list_files or search_files
 
   </Accordion>
 </AccordionGroup>

docs/en/enterprise/integrations/microsoft_teams.mdx

@@ -108,6 +108,86 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `join_web_url` (string, required): The join web URL of the meeting to search for.
 
   </Accordion>
+
+  <Accordion title="microsoft_teams/search_online_meetings_by_meeting_id">
+    **Description:** Search online meetings by external Meeting ID.
+
+    **Parameters:**
+    - `join_meeting_id` (string, required): The meeting ID (numeric code) that attendees use to join. This is the joinMeetingId shown in meeting invitations, not the Graph API meeting id.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/get_meeting">
+    **Description:** Get details of a specific online meeting.
+
+    **Parameters:**
+    - `meeting_id` (string, required): The Graph API meeting ID (a long alphanumeric string). Obtain from create_meeting or search_online_meetings actions. Different from the numeric joinMeetingId.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/get_team_members">
+    **Description:** Get members of a specific team.
+
+    **Parameters:**
+    - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action.
+    - `top` (integer, optional): Maximum number of members to retrieve per page (1-999). Default is `100`.
+    - `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the $skiptoken parameter value and pass it here to get the next page of results.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/create_channel">
+    **Description:** Create a new channel in a team.
+
+    **Parameters:**
+    - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action.
+    - `display_name` (string, required): Name of the channel as displayed in Teams. Must be unique within the team. Max 50 characters.
+    - `description` (string, optional): Optional description explaining the channel's purpose. Visible in channel details. Max 1024 characters.
+    - `membership_type` (string, optional): Channel visibility. Enum: `standard`, `private`. "standard" = visible to all team members, "private" = visible only to specifically added members. Default is `standard`.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/get_message_replies">
+    **Description:** Get replies to a specific message in a channel.
+
+    **Parameters:**
+    - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action.
+    - `channel_id` (string, required): The unique identifier of the channel. Obtain from get_channels action.
+    - `message_id` (string, required): The unique identifier of the parent message. Obtain from get_messages action.
+    - `top` (integer, optional): Maximum number of replies to retrieve per page (1-50). Default is `50`.
+    - `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the $skiptoken parameter value and pass it here to get the next page of results.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/reply_to_message">
+    **Description:** Reply to a message in a Teams channel.
+
+    **Parameters:**
+    - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action.
+    - `channel_id` (string, required): The unique identifier of the channel. Obtain from get_channels action.
+    - `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get_messages action.
+    - `message` (string, required): The reply content. For HTML, include formatting tags. For text, plain text only.
+    - `content_type` (string, optional): Content format. Enum: `html`, `text`. "text" for plain text, "html" for rich text with formatting. Default is `text`.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/update_meeting">
+    **Description:** Update an existing online meeting.
+
+    **Parameters:**
+    - `meeting_id` (string, required): The unique identifier of the meeting. Obtain from create_meeting or search_online_meetings actions.
+    - `subject` (string, optional): New meeting title.
+    - `startDateTime` (string, optional): New start time in ISO 8601 format with timezone. Example: "2024-01-20T10:00:00-08:00".
+    - `endDateTime` (string, optional): New end time in ISO 8601 format with timezone.
+
+  </Accordion>
+
+  <Accordion title="microsoft_teams/delete_meeting">
+    **Description:** Delete an online meeting.
+
+    **Parameters:**
+    - `meeting_id` (string, required): The unique identifier of the meeting to delete. Obtain from create_meeting or search_online_meetings actions.
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/enterprise/integrations/microsoft_word.mdx

@@ -98,6 +98,26 @@ CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
     - `file_id` (string, required): The ID of the document to delete.
 
   </Accordion>
+
+  <Accordion title="microsoft_word/copy_document">
+    **Description:** Copy a document to a new location in OneDrive.
+
+    **Parameters:**
+    - `file_id` (string, required): The ID of the document to copy
+    - `name` (string, optional): New name for the copied document
+    - `parent_id` (string, optional): The ID of the destination folder (defaults to root)
+
+  </Accordion>
+
+  <Accordion title="microsoft_word/move_document">
+    **Description:** Move a document to a new location in OneDrive.
+
+    **Parameters:**
+    - `file_id` (string, required): The ID of the document to move
+    - `parent_id` (string, required): The ID of the destination folder
+    - `name` (string, optional): New name for the moved document
+
+  </Accordion>
 </AccordionGroup>
 
 ## Usage Examples

docs/en/examples/cookbooks.mdx

@@ -8,6 +8,10 @@ mode: "wide"
 ## Quickstarts & Demos
 
 <CardGroup cols={3}>
+  <Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
+    Manage chat sessions with sliding-window history, summary compaction, and persisted Flow state.
+  </Card>
+
   <Card title="Collaboration" icon="people-arrows" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Collaboration/crewai_collaboration.ipynb">
     Coordinate multiple agents on shared tasks. Includes notebook with end-to-end collaboration pattern.
   </Card>

docs/en/examples/example.mdx

@@ -34,6 +34,10 @@ mode: "wide"
 ## Flows
 
 <CardGroup cols={3}>
+  <Card title="Flowstate Chat History" icon="comments" href="/en/learn/flowstate-chat-history">
+    Stateful chat pattern with compacted context and persisted session state.
+  </Card>
+
   <Card title="Content Creator Flow" icon="pen" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/content_creator_flow">
     Multi‑crew content generation with routing.
   </Card>

docs/en/guides/coding-tools/agents-md.mdx

@@ -0,0 +1,61 @@
+---
+title: Coding Tools
+description: Use AGENTS.md to guide coding agents and IDEs across your CrewAI projects.
+icon: terminal
+mode: "wide"
+---
+
+## Why AGENTS.md
+
+`AGENTS.md` is a lightweight, repo-local instruction file that gives coding agents consistent, project-specific guidance. Keep it in the project root and treat it as the source of truth for how you want assistants to work: conventions, commands, architecture notes, and guardrails.
+
+## Create a Project with the CLI
+
+Use the CrewAI CLI to scaffold a project, then `AGENTS.md` will be automatically added at the root.
+
+```bash
+# Crew
+crewai create crew my_crew
+
+# Flow
+crewai create flow my_flow
+
+# Tool repository
+crewai tool create my_tool
+```
+
+## Tool Setup: Point Assistants to AGENTS.md
+
+### Codex
+
+Codex can be guided by `AGENTS.md` files placed in your repository. Use them to supply persistent project context such as conventions, commands, and workflow expectations.
+
+### Claude Code
+
+Claude Code stores project memory in `CLAUDE.md`. You can bootstrap it with `/init` and edit it using `/memory`. Claude Code also supports imports inside `CLAUDE.md`, so you can add a single line like `@AGENTS.md` to pull in the shared instructions without duplicating them.
+
+You can simply use:
+
+```bash
+mv AGENTS.md CLAUDE.md
+```
+
+### Gemini CLI and Google Antigravity
+
+Gemini CLI and Antigravity load a project context file (default: `GEMINI.md`) from the repo root and parent directories. You can configure it to read `AGENTS.md` instead (or in addition) by setting `context.fileName` in your Gemini CLI settings. For example, set it to `AGENTS.md` only, or include both `AGENTS.md` and `GEMINI.md` if you want to keep each tool’s format.
+
+You can simply use:
+
+```bash
+mv AGENTS.md GEMINI.md
+```
+
+### Cursor
+
+Cursor supports `AGENTS.md` as a project instruction file. Place it at the project root to provide guidance for Cursor’s coding assistant.
+
+### Windsurf
+
+Claude Code provides an official integration with Windsurf. If you use Claude Code inside Windsurf, follow the Claude Code guidance above and import `AGENTS.md` from `CLAUDE.md`.
+
+If you are using Windsurf’s native assistant, configure its project rules or instructions feature (if available) to read from `AGENTS.md` or paste the contents directly.

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

@@ -47,6 +47,23 @@ CrewAI offers two ways to manage state in your flows:
 
 Let's examine each approach in detail.
 
+### Flow State vs Memory: When to use each
+
+Both features keep context, but they solve different problems.
+
+| Dimension | Flow State (`self.state`) | Memory (`self.remember` / `self.recall`) |
+|---|---|---|
+| Primary purpose | Track execution and deterministic workflow data | Store and retrieve semantic knowledge across interactions |
+| Data shape | Explicit fields (dict/Pydantic model) | Text records with inferred scopes and ranked recall |
+| Typical lifetime | Current flow run (or persisted checkpoints) | Long-term knowledge over many runs |
+| Access pattern | Direct reads/writes (`self.state.field`) | Query-based retrieval (`self.recall("...")`) |
+| Best for | Routing flags, counters, intermediate outputs, chat window | Durable facts, prior outcomes, reusable context |
+| Chat use | Recent turns + running summary + control flags | Long-tail memory outside context window |
+
+Practical rule:
+- Use **state** for what your control flow depends on right now.
+- Use **memory** for what you may want to retrieve later by meaning.
+
 ## Unstructured State Management
 
 Unstructured state uses a dictionary-like approach, offering flexibility and simplicity for straightforward applications.

docs/en/index.mdx

@@ -27,8 +27,11 @@ mode: "wide"
   </div>
 
   <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, justifyContent: 'center' }}>
-    <a className="button button-primary" href="/en/quickstart">Get started</a>
-    <a className="button" href="/en/changelog">View changelog</a>
+    <a className="button button-primary" href="/en/installation">Install</a>
+    <a className="button" href="/en/quickstart">Quickstart</a>
+    <a className="button" href="/en/guides/crews/first-crew">First Crew</a>
+    <a className="button" href="/en/guides/flows/first-flow">First Flow</a>
+    <a className="button" href="/en/concepts/llms">LLM Setup</a>
     <a className="button" href="/en/api-reference/introduction">API Reference</a>
   </div>
 
@@ -36,17 +39,49 @@ mode: "wide"
 
 <div style={{ marginTop: 32 }} />
 
-## Get started
+## Start in 3 steps
 
 <CardGroup cols={3}>
-  <Card title="Introduction" href="/en/introduction" icon="sparkles">
-    Overview of CrewAI concepts, architecture, and what you can build with agents, crews, and flows.
-  </Card>
-  <Card title="Installation" href="/en/installation" icon="wrench">
+  <Card title="1) Install" href="/en/installation" icon="wrench">
     Install via `uv`, configure API keys, and set up the CLI for local development.
   </Card>
-  <Card title="Quickstart" href="/en/quickstart" icon="rocket">
-    Spin up your first crew in minutes. Learn the core runtime, project layout, and dev loop.
+  <Card title="2) Run Quickstart" href="/en/quickstart" icon="rocket">
+    Launch your first working crew with a minimal project and iterate from there.
+  </Card>
+  <Card title="3) Pick a path" href="/en/ai/overview" icon="sitemap">
+    Continue with canonical domain packs for Flows, Agents, Crews, LLMs, Memory, and Tools.
+  </Card>
+</CardGroup>
+
+## Most-used pages
+
+<CardGroup cols={3}>
+  <Card title="First Crew" href="/en/guides/crews/first-crew" icon="users">
+    Build a production-style crew with role/task configuration and execution flow.
+  </Card>
+  <Card title="First Flow" href="/en/guides/flows/first-flow" icon="arrow-progress">
+    Build event-driven orchestration with state, listeners, and routing.
+  </Card>
+  <Card title="Flowstate Chat History" href="/en/learn/flowstate-chat-history" icon="comments">
+    Stateful chat history pattern with persistence and summary compaction.
+  </Card>
+  <Card title="Agents" href="/en/concepts/agents" icon="user">
+    Agent role design, tool boundaries, and output contracts.
+  </Card>
+  <Card title="Crews" href="/en/concepts/crews" icon="users-gear">
+    Multi-agent collaboration patterns and process semantics.
+  </Card>
+  <Card title="Flows" href="/en/concepts/flows" icon="code-branch">
+    Deterministic orchestration, state lifecycle, persistence, and resume.
+  </Card>
+  <Card title="LLMs" href="/en/concepts/llms" icon="microchip-ai">
+    Model setup, provider config, routing patterns, and reliability defaults.
+  </Card>
+  <Card title="Memory" href="/en/concepts/memory" icon="database">
+    Semantic recall, scope strategy, and state-vs-memory architecture.
+  </Card>
+  <Card title="Tools" href="/en/tools/overview" icon="wrench">
+    Tool categories, integration surfaces, and practical usage patterns.
   </Card>
 </CardGroup>
 
@@ -90,7 +125,11 @@ mode: "wide"
 </CardGroup>
 
 <Callout title="Explore real-world patterns" icon="github">
-  Browse the <a href="/en/examples/cookbooks">examples and cookbooks</a> for end-to-end reference implementations across agents, flows, and enterprise automations.
+  Browse the <a href="/en/examples/cookbooks">examples and cookbooks</a> for end-to-end reference implementations across agents, flows, and enterprise automations. For a practical conversational pattern, start with <a href="/en/learn/flowstate-chat-history">Flowstate Chat History</a>.
+</Callout>
+
+<Callout title="AI-First Docs" icon="sitemap">
+  Use the <a href="/en/ai/overview">AI-First Documentation map</a> for canonical domain packs across Flows, Agents, Crews, LLMs, Memory, and Tools.
 </Callout>
 
 ## Stay connected

docs/en/introduction.mdx

@@ -16,6 +16,52 @@ It empowers developers to build production-ready multi-agent systems by combinin
 
 With over 100,000 developers certified through our community courses, CrewAI is the standard for enterprise-ready AI automation.
 
+## Start Here
+
+<CardGroup cols={3}>
+  <Card title="Install" href="/en/installation" icon="wrench">
+    Set up CrewAI, configure API keys, and prepare your local environment.
+  </Card>
+  <Card title="Quickstart" href="/en/quickstart" icon="rocket">
+    Run your first working crew with a minimal setup.
+  </Card>
+  <Card title="First Crew" href="/en/guides/crews/first-crew" icon="users-gear">
+    Build a production-style crew with roles, tasks, and execution flow.
+  </Card>
+  <Card title="First Flow" href="/en/guides/flows/first-flow" icon="arrow-progress">
+    Build event-driven orchestration with state, listeners, and routers.
+  </Card>
+  <Card title="LLM Setup" href="/en/concepts/llms" icon="microchip-ai">
+    Configure providers, models, and reliability defaults.
+  </Card>
+  <Card title="API Reference" href="/en/api-reference/introduction" icon="book">
+    Use kickoff, resume, and status endpoints for production integrations.
+  </Card>
+</CardGroup>
+
+## Most-used Docs
+
+<CardGroup cols={3}>
+  <Card title="Agents" href="/en/concepts/agents" icon="user">
+    Role design, tool boundaries, and output contracts.
+  </Card>
+  <Card title="Crews" href="/en/concepts/crews" icon="users">
+    Multi-agent coordination and process choices.
+  </Card>
+  <Card title="Flows" href="/en/concepts/flows" icon="code-branch">
+    Deterministic orchestration, state, persistence, and resume.
+  </Card>
+  <Card title="Memory" href="/en/concepts/memory" icon="database">
+    Scope strategy and semantic recall across runs.
+  </Card>
+  <Card title="Flowstate Chat History" href="/en/learn/flowstate-chat-history" icon="comments">
+    Stateful chat context with summary compaction and persistence.
+  </Card>
+  <Card title="AI-First Docs Map" href="/en/ai/overview" icon="sitemap">
+    Canonical domain packs for Flows, Agents, Crews, LLMs, Memory, and Tools.
+  </Card>
+</CardGroup>
+
 ## The CrewAI Architecture
 
 CrewAI's architecture is designed to balance autonomy with control.
@@ -130,7 +176,7 @@ For any production-ready application, **start with a Flow**.
   <Card
     title="Quick Start"
     icon="bolt"
-    href="en/quickstart"
+    href="/en/quickstart"
   >
     Follow our quickstart guide to create your first CrewAI agent and get hands-on experience.
   </Card>

docs/en/learn/a2a-agent-delegation.mdx

@@ -1,43 +1,48 @@
 ---
 title: Agent-to-Agent (A2A) Protocol
-description: Enable CrewAI agents to delegate tasks to remote A2A-compliant agents for specialized handling
+description: Agents delegate tasks to remote A2A agents and/or operate as A2A-compliant server agents.
 icon: network-wired
 mode: "wide"
 ---
 
 ## A2A Agent Delegation
 
-CrewAI supports the Agent-to-Agent (A2A) protocol, allowing agents to delegate tasks to remote specialized agents. The agent's LLM automatically decides whether to handle a task directly or delegate to an A2A agent based on the task requirements.
-
-<Note>
-  A2A delegation requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'`
-</Note>
+CrewAI treats [A2A protocol](https://a2a-protocol.org/latest/) as a first-class delegation primitive, enabling agents to delegate tasks, request information, and collaborate with remote agents, as well as act as A2A-compliant server agents.
+In client mode, agents autonomously choose between local execution and remote delegation based on task requirements.
 
 ## How It Works
 
 When an agent is configured with A2A capabilities:
 
-1. The LLM analyzes each task
+1. The Agent analyzes each task
 2. It decides to either:
    - Handle the task directly using its own capabilities
    - Delegate to a remote A2A agent for specialized handling
 3. If delegating, the agent communicates with the remote A2A agent through the protocol
 4. Results are returned to the CrewAI workflow
 
+<Note>
+  A2A delegation requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'`
+</Note>
+
 ## Basic Configuration
 
+<Warning>
+  `crewai.a2a.config.A2AConfig` is deprecated and will be removed in v2.0.0. Use `A2AClientConfig` for connecting to remote agents and/or `A2AServerConfig` for exposing agents as servers.
+</Warning>
+
 Configure an agent for A2A delegation by setting the `a2a` parameter:
 
 ```python Code
 from crewai import Agent, Crew, Task
-from crewai.a2a import A2AConfig
+from crewai.a2a import A2AClientConfig
 
 agent = Agent(
     role="Research Coordinator",
     goal="Coordinate research tasks efficiently",
     backstory="Expert at delegating to specialized research agents",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://example.com/.well-known/agent-card.json",
         timeout=120,
         max_turns=10
@@ -54,9 +59,9 @@ crew = Crew(agents=[agent], tasks=[task], verbose=True)
 result = crew.kickoff()
 ```
 
-## Configuration Options
+## Client Configuration Options
 
-The `A2AConfig` class accepts the following parameters:
+The `A2AClientConfig` class accepts the following parameters:
 
 <ParamField path="endpoint" type="str" required>
   The A2A agent endpoint URL (typically points to `.well-known/agent-card.json`)
@@ -91,14 +96,34 @@ The `A2AConfig` class accepts the following parameters:
   Update mechanism for receiving task status. Options: `StreamingConfig`, `PollingConfig`, or `PushNotificationConfig`.
 </ParamField>
 
+<ParamField path="transport_protocol" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">
+  Transport protocol for A2A communication. Options: `JSONRPC` (default), `GRPC`, or `HTTP+JSON`.
+</ParamField>
+
+<ParamField path="accepted_output_modes" type="list[str]" default='["application/json"]'>
+  Media types the client can accept in responses.
+</ParamField>
+
+<ParamField path="supported_transports" type="list[str]" default='["JSONRPC"]'>
+  Ordered list of transport protocols the client supports.
+</ParamField>
+
+<ParamField path="use_client_preference" type="bool" default="False">
+  Whether to prioritize client transport preferences over server.
+</ParamField>
+
+<ParamField path="extensions" type="list[str]" default="[]">
+  Extension URIs the client supports.
+</ParamField>
+
 ## Authentication
 
 For A2A agents that require authentication, use one of the provided auth schemes:
 
 <Tabs>
   <Tab title="Bearer Token">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python bearer_token_auth.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.auth import BearerTokenAuth
 
 agent = Agent(
@@ -106,18 +131,18 @@ agent = Agent(
     goal="Coordinate tasks with secured agents",
     backstory="Manages secure agent communications",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://secure-agent.example.com/.well-known/agent-card.json",
         auth=BearerTokenAuth(token="your-bearer-token"),
         timeout=120
     )
 )
-    ```
+```
   </Tab>
 
   <Tab title="API Key">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python api_key_auth.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.auth import APIKeyAuth
 
 agent = Agent(
@@ -125,7 +150,7 @@ agent = Agent(
     goal="Coordinate with API-based agents",
     backstory="Manages API-authenticated communications",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://api-agent.example.com/.well-known/agent-card.json",
         auth=APIKeyAuth(
             api_key="your-api-key",
@@ -135,12 +160,12 @@ agent = Agent(
         timeout=120
     )
 )
-    ```
+```
   </Tab>
 
   <Tab title="OAuth2">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python oauth2_auth.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.auth import OAuth2ClientCredentials
 
 agent = Agent(
@@ -148,7 +173,7 @@ agent = Agent(
     goal="Coordinate with OAuth-secured agents",
     backstory="Manages OAuth-authenticated communications",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://oauth-agent.example.com/.well-known/agent-card.json",
         auth=OAuth2ClientCredentials(
             token_url="https://auth.example.com/oauth/token",
@@ -159,12 +184,12 @@ agent = Agent(
         timeout=120
     )
 )
-    ```
+```
   </Tab>
 
   <Tab title="HTTP Basic">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python http_basic_auth.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.auth import HTTPBasicAuth
 
 agent = Agent(
@@ -172,7 +197,7 @@ agent = Agent(
     goal="Coordinate with basic auth agents",
     backstory="Manages basic authentication communications",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://basic-agent.example.com/.well-known/agent-card.json",
         auth=HTTPBasicAuth(
             username="your-username",
@@ -181,7 +206,7 @@ agent = Agent(
         timeout=120
     )
 )
-    ```
+```
   </Tab>
 </Tabs>
 
@@ -190,7 +215,7 @@ agent = Agent(
 Configure multiple A2A agents for delegation by passing a list:
 
 ```python Code
-from crewai.a2a import A2AConfig
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.auth import BearerTokenAuth
 
 agent = Agent(
@@ -199,11 +224,11 @@ agent = Agent(
     backstory="Expert at delegating to the right specialist",
     llm="gpt-4o",
     a2a=[
-        A2AConfig(
+        A2AClientConfig(
             endpoint="https://research.example.com/.well-known/agent-card.json",
             timeout=120
         ),
-        A2AConfig(
+        A2AClientConfig(
             endpoint="https://data.example.com/.well-known/agent-card.json",
             auth=BearerTokenAuth(token="data-token"),
             timeout=90
@@ -219,7 +244,7 @@ The LLM will automatically choose which A2A agent to delegate to based on the ta
 Control how agent connection failures are handled using the `fail_fast` parameter:
 
 ```python Code
-from crewai.a2a import A2AConfig
+from crewai.a2a import A2AClientConfig
 
 # Fail immediately on connection errors (default)
 agent = Agent(
@@ -227,7 +252,7 @@ agent = Agent(
     goal="Coordinate research tasks",
     backstory="Expert at delegation",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://research.example.com/.well-known/agent-card.json",
         fail_fast=True
     )
@@ -240,11 +265,11 @@ agent = Agent(
     backstory="Expert at working with available resources",
     llm="gpt-4o",
     a2a=[
-        A2AConfig(
+        A2AClientConfig(
             endpoint="https://primary.example.com/.well-known/agent-card.json",
             fail_fast=False
         ),
-        A2AConfig(
+        A2AClientConfig(
             endpoint="https://backup.example.com/.well-known/agent-card.json",
             fail_fast=False
         )
@@ -263,8 +288,8 @@ Control how your agent receives task status updates from remote A2A agents:
 
 <Tabs>
   <Tab title="Streaming (Default)">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python streaming_config.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.updates import StreamingConfig
 
 agent = Agent(
@@ -272,17 +297,17 @@ agent = Agent(
     goal="Coordinate research tasks",
     backstory="Expert at delegation",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://research.example.com/.well-known/agent-card.json",
         updates=StreamingConfig()
     )
 )
-    ```
+```
   </Tab>
 
   <Tab title="Polling">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python polling_config.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.updates import PollingConfig
 
 agent = Agent(
@@ -290,7 +315,7 @@ agent = Agent(
     goal="Coordinate research tasks",
     backstory="Expert at delegation",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://research.example.com/.well-known/agent-card.json",
         updates=PollingConfig(
             interval=2.0,
@@ -299,12 +324,12 @@ agent = Agent(
         )
     )
 )
-    ```
+```
   </Tab>
 
   <Tab title="Push Notifications">
-    ```python Code
-from crewai.a2a import A2AConfig
+```python push_notifications_config.py lines
+from crewai.a2a import A2AClientConfig
 from crewai.a2a.updates import PushNotificationConfig
 
 agent = Agent(
@@ -312,19 +337,137 @@ agent = Agent(
     goal="Coordinate research tasks",
     backstory="Expert at delegation",
     llm="gpt-4o",
-    a2a=A2AConfig(
+    a2a=A2AClientConfig(
         endpoint="https://research.example.com/.well-known/agent-card.json",
         updates=PushNotificationConfig(
-            url={base_url}/a2a/callback",
+            url="{base_url}/a2a/callback",
             token="your-validation-token",
             timeout=300.0
         )
     )
 )
-    ```
+```
   </Tab>
 </Tabs>
 
+## Exposing Agents as A2A Servers
+
+You can expose your CrewAI agents as A2A-compliant servers, allowing other A2A clients to delegate tasks to them.
+
+### Server Configuration
+
+Add an `A2AServerConfig` to your agent to enable server capabilities:
+
+```python a2a_server_agent.py lines
+from crewai import Agent
+from crewai.a2a import A2AServerConfig
+
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze datasets and provide insights",
+    backstory="Expert data scientist with statistical analysis skills",
+    llm="gpt-4o",
+    a2a=A2AServerConfig(url="https://your-server.com")
+)
+```
+
+### Server Configuration Options
+
+<ParamField path="name" type="str" default="None">
+  Human-readable name for the agent. Defaults to the agent's role if not provided.
+</ParamField>
+
+<ParamField path="description" type="str" default="None">
+  Human-readable description. Defaults to the agent's goal and backstory if not provided.
+</ParamField>
+
+<ParamField path="version" type="str" default="1.0.0">
+  Version string for the agent card.
+</ParamField>
+
+<ParamField path="skills" type="list[AgentSkill]" default="[]">
+  List of agent skills. Auto-generated from agent tools if not provided.
+</ParamField>
+
+<ParamField path="capabilities" type="AgentCapabilities" default="AgentCapabilities(streaming=True, push_notifications=False)">
+  Declaration of optional capabilities supported by the agent.
+</ParamField>
+
+<ParamField path="default_input_modes" type="list[str]" default='["text/plain", "application/json"]'>
+  Supported input MIME types.
+</ParamField>
+
+<ParamField path="default_output_modes" type="list[str]" default='["text/plain", "application/json"]'>
+  Supported output MIME types.
+</ParamField>
+
+<ParamField path="url" type="str" default="None">
+  Preferred endpoint URL. If set, overrides the URL passed to `to_agent_card()`.
+</ParamField>
+
+<ParamField path="preferred_transport" type="Literal['JSONRPC', 'GRPC', 'HTTP+JSON']" default="JSONRPC">
+  Transport protocol for the preferred endpoint.
+</ParamField>
+
+<ParamField path="protocol_version" type="str" default="0.3">
+  A2A protocol version this agent supports.
+</ParamField>
+
+<ParamField path="provider" type="AgentProvider" default="None">
+  Information about the agent's service provider.
+</ParamField>
+
+<ParamField path="documentation_url" type="str" default="None">
+  URL to the agent's documentation.
+</ParamField>
+
+<ParamField path="icon_url" type="str" default="None">
+  URL to an icon for the agent.
+</ParamField>
+
+<ParamField path="additional_interfaces" type="list[AgentInterface]" default="[]">
+  Additional supported interfaces (transport and URL combinations).
+</ParamField>
+
+<ParamField path="security" type="list[dict[str, list[str]]]" default="[]">
+  Security requirement objects for all agent interactions.
+</ParamField>
+
+<ParamField path="security_schemes" type="dict[str, SecurityScheme]" default="{}">
+  Security schemes available to authorize requests.
+</ParamField>
+
+<ParamField path="supports_authenticated_extended_card" type="bool" default="False">
+  Whether agent provides extended card to authenticated users.
+</ParamField>
+
+<ParamField path="signatures" type="list[AgentCardSignature]" default="[]">
+  JSON Web Signatures for the AgentCard.
+</ParamField>
+
+### Combined Client and Server
+
+An agent can act as both client and server by providing both configurations:
+
+```python Code
+from crewai import Agent
+from crewai.a2a import A2AClientConfig, A2AServerConfig
+
+agent = Agent(
+    role="Research Coordinator",
+    goal="Coordinate research and serve analysis requests",
+    backstory="Expert at delegation and analysis",
+    llm="gpt-4o",
+    a2a=[
+        A2AClientConfig(
+            endpoint="https://specialist.example.com/.well-known/agent-card.json",
+            timeout=120
+        ),
+        A2AServerConfig(url="https://your-server.com")
+    ]
+)
+```
+
 ## Best Practices
 
 <CardGroup cols={2}>

docs/en/learn/flowstate-chat-history.mdx

@@ -0,0 +1,167 @@
+---
+title: "Flowstate Chat History"
+description: "Build a stateful chat workflow that keeps context compact, persistent, and production-friendly."
+icon: "comments"
+mode: "wide"
+---
+
+## Overview
+
+This guide shows a practical pattern for managing LLM chat history with Flow state:
+
+- Keep recent turns in a sliding window
+- Summarize older turns into a compact running summary
+- Persist state automatically with `@persist()`
+- Keep optional long-term recall using Flow memory
+
+## Why this pattern works
+
+Naively appending every message to prompts causes token bloat and unstable behavior over long sessions. A better approach is:
+
+1. Keep only the most recent turns in `state.messages`
+2. Move older turns into `state.running_summary`
+3. Build prompts from `running_summary + recent messages`
+
+## Prerequisites
+
+1. CrewAI installed and configured
+2. API key configured for your model provider
+3. Basic familiarity with Flow decorators (`@start`, `@listen`)
+
+## Step 1: Define typed chat state
+
+```python Code
+from typing import Dict, List
+from pydantic import BaseModel, Field
+
+
+class ChatSessionState(BaseModel):
+    session_id: str = "demo-session"
+    running_summary: str = ""
+    messages: List[Dict[str, str]] = Field(default_factory=list)
+    max_recent_messages: int = 8
+    last_user_message: str = ""
+    assistant_reply: str = ""
+    turn_count: int = 0
+```
+
+## Step 2: Build the Flow
+
+```python Code
+from crewai.flow.flow import Flow, start, listen
+from crewai.flow.persistence import persist
+from litellm import completion
+
+
+@persist()
+class ChatHistoryFlow(Flow[ChatSessionState]):
+    model = "gpt-4o-mini"
+
+    @start()
+    def capture_user_message(self):
+        self.state.last_user_message = self.state.last_user_message.strip()
+        self.state.messages.append(
+            {"role": "user", "content": self.state.last_user_message}
+        )
+        self.state.turn_count += 1
+        return self.state.last_user_message
+
+    @listen(capture_user_message)
+    def compact_old_history(self, _):
+        if len(self.state.messages) <= self.state.max_recent_messages:
+            return "no_compaction"
+
+        overflow = self.state.messages[:-self.state.max_recent_messages]
+        self.state.messages = self.state.messages[-self.state.max_recent_messages :]
+        overflow_text = "\n".join(
+            f"{m['role']}: {m['content']}" for m in overflow
+        )
+
+        summary_prompt = [
+            {
+                "role": "system",
+                "content": "Summarize old chat turns into short bullet points. Preserve facts, constraints, and decisions.",
+            },
+            {
+                "role": "user",
+                "content": (
+                    f"Existing summary:\n{self.state.running_summary or '(empty)'}\n\n"
+                    f"New old turns:\n{overflow_text}"
+                ),
+            },
+        ]
+        summary_response = completion(model=self.model, messages=summary_prompt)
+        self.state.running_summary = summary_response["choices"][0]["message"]["content"]
+        return "compacted"
+
+    @listen(compact_old_history)
+    def generate_reply(self, _):
+        system_context = (
+            "You are a helpful assistant.\n"
+            f"Conversation summary so far:\n{self.state.running_summary or '(none)'}"
+        )
+
+        response = completion(
+            model=self.model,
+            messages=[{"role": "system", "content": system_context}, *self.state.messages],
+        )
+        answer = response["choices"][0]["message"]["content"]
+
+        self.state.assistant_reply = answer
+        self.state.messages.append({"role": "assistant", "content": answer})
+
+        # Optional: store key turns in long-term memory for later recall
+        self.remember(
+            f"Session {self.state.session_id} turn {self.state.turn_count}: "
+            f"user={self.state.last_user_message} assistant={answer}",
+            scope=f"/chat/{self.state.session_id}",
+        )
+        return answer
+```
+
+## Step 3: Run it
+
+```python Code
+flow = ChatHistoryFlow()
+
+first = flow.kickoff(
+    inputs={
+        "session_id": "customer-42",
+        "last_user_message": "I need help choosing a pricing plan for a 10-person team.",
+    }
+)
+print("Assistant:", first)
+
+second = flow.kickoff(
+    inputs={
+        "last_user_message": "We also need SSO and audit logs. What do you recommend now?",
+    }
+)
+print("Assistant:", second)
+print("Turns:", flow.state.turn_count)
+print("Recent messages:", len(flow.state.messages))
+```
+
+## Expected output (shape)
+
+```text Output
+Assistant: ...initial recommendation...
+Assistant: ...updated recommendation with SSO and audit-log requirements...
+Turns: 2
+Recent messages: 4
+```
+
+## Troubleshooting
+
+- If replies ignore earlier context:
+  increase `max_recent_messages` and ensure `running_summary` is included in the system context.
+- If prompts become too large:
+  lower `max_recent_messages` and summarize more aggressively.
+- If sessions collide:
+  provide a stable `session_id` and isolate memory scope with `/chat/{session_id}`.
+
+## Next steps
+
+- Add tool calls for account lookup or product catalog retrieval
+- Route to human review for high-risk decisions
+- Add structured output to capture recommendations in machine-readable JSON

docs/en/learn/human-feedback-in-flows.mdx

@@ -7,6 +7,10 @@ mode: "wide"
 
 ## Overview
 
+<Note>
+The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**. Make sure to update your installation before using this feature.
+</Note>
+
 The `@human_feedback` decorator enables human-in-the-loop (HITL) workflows directly within CrewAI Flows. It allows you to pause flow execution, present output to a human for review, collect their feedback, and optionally route to different listeners based on the feedback outcome.
 
 This is particularly valuable for:
@@ -69,6 +73,8 @@ When this flow runs, it will:
 | `default_outcome` | `str` | No | Outcome to use if no feedback provided. Must be in `emit` |
 | `metadata` | `dict` | No | Additional data for enterprise integrations |
 | `provider` | `HumanFeedbackProvider` | No | Custom provider for async/non-blocking feedback. See [Async Human Feedback](#async-human-feedback-non-blocking) |
+| `learn` | `bool` | No | Enable HITL learning: distill lessons from feedback and pre-review future output. Default `False`. See [Learning from Feedback](#learning-from-feedback) |
+| `learn_limit` | `int` | No | Max past lessons to recall for pre-review. Default `5` |
 
 ### Basic Usage (No Routing)
 
@@ -92,33 +98,43 @@ def handle_feedback(self, result):
 When you specify `emit`, the decorator becomes a router. The human's free-form feedback is interpreted by an LLM and collapsed into one of the specified outcomes:
 
 ```python Code
-@start()
-@human_feedback(
-    message="Do you approve this content for publication?",
-    emit=["approved", "rejected", "needs_revision"],
-    llm="gpt-4o-mini",
-    default_outcome="needs_revision",
-)
-def review_content(self):
-    return "Draft blog post content here..."
+from crewai.flow.flow import Flow, start, listen, or_
+from crewai.flow.human_feedback import human_feedback
 
-@listen("approved")
-def publish(self, result):
-    print(f"Publishing! User said: {result.feedback}")
+class ReviewFlow(Flow):
+    @start()
+    def generate_content(self):
+        return "Draft blog post content here..."
 
-@listen("rejected")
-def discard(self, result):
-    print(f"Discarding. Reason: {result.feedback}")
+    @human_feedback(
+        message="Do you approve this content for publication?",
+        emit=["approved", "rejected", "needs_revision"],
+        llm="gpt-4o-mini",
+        default_outcome="needs_revision",
+    )
+    @listen(or_("generate_content", "needs_revision"))
+    def review_content(self):
+        return "Draft blog post content here..."
 
-@listen("needs_revision")
-def revise(self, result):
-    print(f"Revising based on: {result.feedback}")
+    @listen("approved")
+    def publish(self, result):
+        print(f"Publishing! User said: {result.feedback}")
+
+    @listen("rejected")
+    def discard(self, result):
+        print(f"Discarding. Reason: {result.feedback}")
 ```
 
+When the human says something like "needs more detail", the LLM collapses that to `"needs_revision"`, which triggers `review_content` again via `or_()` — creating a revision loop. The loop continues until the outcome is `"approved"` or `"rejected"`.
+
 <Tip>
 The LLM uses structured outputs (function calling) when available to guarantee the response is one of your specified outcomes. This makes routing reliable and predictable.
 </Tip>
 
+<Warning>
+A `@start()` method only runs once at the beginning of the flow. If you need a revision loop, separate the start method from the review method and use `@listen(or_("trigger", "revision_outcome"))` on the review method to enable the self-loop.
+</Warning>
+
 ## HumanFeedbackResult
 
 The `HumanFeedbackResult` dataclass contains all information about a human feedback interaction:
@@ -182,127 +198,183 @@ Each `HumanFeedbackResult` is appended to `human_feedback_history`, so multiple
 
 ## Complete Example: Content Approval Workflow
 
-Here's a full example implementing a content review and approval workflow:
+Here's a full example implementing a content review and approval workflow with a revision loop:
 
 <CodeGroup>
 
 ```python Code
-from crewai.flow.flow import Flow, start, listen
+from crewai.flow.flow import Flow, start, listen, or_
 from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
 from pydantic import BaseModel
 
 
 class ContentState(BaseModel):
-    topic: str = ""
     draft: str = ""
-    final_content: str = ""
     revision_count: int = 0
+    status: str = "pending"
 
 
 class ContentApprovalFlow(Flow[ContentState]):
-    """A flow that generates content and gets human approval."""
+    """A flow that generates content and loops until the human approves."""
 
     @start()
-    def get_topic(self):
-        self.state.topic = input("What topic should I write about? ")
-        return self.state.topic
-
-    @listen(get_topic)
-    def generate_draft(self, topic):
-        # In real use, this would call an LLM
-        self.state.draft = f"# {topic}\n\nThis is a draft about {topic}..."
+    def generate_draft(self):
+        self.state.draft = "# AI Safety\n\nThis is a draft about AI Safety..."
         return self.state.draft
 
-    @listen(generate_draft)
     @human_feedback(
-        message="Please review this draft. Reply 'approved', 'rejected', or provide revision feedback:",
+        message="Please review this draft. Approve, reject, or describe what needs changing:",
         emit=["approved", "rejected", "needs_revision"],
         llm="gpt-4o-mini",
         default_outcome="needs_revision",
     )
-    def review_draft(self, draft):
-        return draft
+    @listen(or_("generate_draft", "needs_revision"))
+    def review_draft(self):
+        self.state.revision_count += 1
+        return f"{self.state.draft} (v{self.state.revision_count})"
 
     @listen("approved")
     def publish_content(self, result: HumanFeedbackResult):
-        self.state.final_content = result.output
-        print("\n✅ Content approved and published!")
-        print(f"Reviewer comment: {result.feedback}")
+        self.state.status = "published"
+        print(f"Content approved and published! Reviewer said: {result.feedback}")
         return "published"
 
     @listen("rejected")
     def handle_rejection(self, result: HumanFeedbackResult):
-        print("\n❌ Content rejected")
-        print(f"Reason: {result.feedback}")
+        self.state.status = "rejected"
+        print(f"Content rejected. Reason: {result.feedback}")
         return "rejected"
 
-    @listen("needs_revision")
-    def revise_content(self, result: HumanFeedbackResult):
-        self.state.revision_count += 1
-        print(f"\n📝 Revision #{self.state.revision_count} requested")
-        print(f"Feedback: {result.feedback}")
 
-        # In a real flow, you might loop back to generate_draft
-        # For this example, we just acknowledge
-        return "revision_requested"
-
-
-# Run the flow
 flow = ContentApprovalFlow()
 result = flow.kickoff()
-print(f"\nFlow completed. Revisions requested: {flow.state.revision_count}")
+print(f"\nFlow completed. Status: {flow.state.status}, Reviews: {flow.state.revision_count}")
 ```
 
 ```text Output
-What topic should I write about? AI Safety
+==================================================
+OUTPUT FOR REVIEW:
+==================================================
+# AI Safety
+
+This is a draft about AI Safety... (v1)
+==================================================
+
+Please review this draft. Approve, reject, or describe what needs changing:
+(Press Enter to skip, or type your feedback)
+
+Your feedback: Needs more detail on alignment research
 
 ==================================================
 OUTPUT FOR REVIEW:
 ==================================================
 # AI Safety
 
-This is a draft about AI Safety...
+This is a draft about AI Safety... (v2)
 ==================================================
 
-Please review this draft. Reply 'approved', 'rejected', or provide revision feedback:
+Please review this draft. Approve, reject, or describe what needs changing:
 (Press Enter to skip, or type your feedback)
 
 Your feedback: Looks good, approved!
 
-✅ Content approved and published!
-Reviewer comment: Looks good, approved!
+Content approved and published! Reviewer said: Looks good, approved!
 
-Flow completed. Revisions requested: 0
+Flow completed. Status: published, Reviews: 2
 ```
 
 </CodeGroup>
 
+The key pattern is `@listen(or_("generate_draft", "needs_revision"))` — the review method listens to both the initial trigger and its own revision outcome, creating a self-loop that repeats until the human approves or rejects.
+
 ## Combining with Other Decorators
 
-The `@human_feedback` decorator works with other flow decorators. Place it as the innermost decorator (closest to the function):
+The `@human_feedback` decorator works with `@start()`, `@listen()`, and `or_()`. Both decorator orderings work — the framework propagates attributes in both directions — but the recommended patterns are:
 
 ```python Code
-# Correct: @human_feedback is innermost (closest to the function)
+# One-shot review at the start of a flow (no self-loop)
 @start()
-@human_feedback(message="Review this:")
+@human_feedback(message="Review this:", emit=["approved", "rejected"], llm="gpt-4o-mini")
 def my_start_method(self):
     return "content"
 
+# Linear review on a listener (no self-loop)
 @listen(other_method)
-@human_feedback(message="Review this too:")
+@human_feedback(message="Review this too:", emit=["good", "bad"], llm="gpt-4o-mini")
 def my_listener(self, data):
     return f"processed: {data}"
+
+# Self-loop: review that can loop back for revisions
+@human_feedback(message="Approve or revise?", emit=["approved", "revise"], llm="gpt-4o-mini")
+@listen(or_("upstream_method", "revise"))
+def review_with_loop(self):
+    return "content for review"
 ```
 
-<Tip>
-Place `@human_feedback` as the innermost decorator (last/closest to the function) so it wraps the method directly and can capture the return value before passing to the flow system.
-</Tip>
+### Self-loop pattern
+
+To create a revision loop, the review method must listen to **both** an upstream trigger and its own revision outcome using `or_()`:
+
+```python Code
+@start()
+def generate(self):
+    return "initial draft"
+
+@human_feedback(
+    message="Approve or request changes?",
+    emit=["revise", "approved"],
+    llm="gpt-4o-mini",
+    default_outcome="approved",
+)
+@listen(or_("generate", "revise"))
+def review(self):
+    return "content"
+
+@listen("approved")
+def publish(self):
+    return "published"
+```
+
+When the outcome is `"revise"`, the flow routes back to `review` (because it listens to `"revise"` via `or_()`). When the outcome is `"approved"`, the flow continues to `publish`. This works because the flow engine exempts routers from the "fire once" rule, allowing them to re-execute on each loop iteration.
+
+### Chained routers
+
+A listener triggered by one router's outcome can itself be a router:
+
+```python Code
+@start()
+def generate(self):
+    return "draft content"
+
+@human_feedback(message="First review:", emit=["approved", "rejected"], llm="gpt-4o-mini")
+@listen("generate")
+def first_review(self):
+    return "draft content"
+
+@human_feedback(message="Final review:", emit=["publish", "hold"], llm="gpt-4o-mini")
+@listen("approved")
+def final_review(self, prev):
+    return "final content"
+
+@listen("publish")
+def on_publish(self, prev):
+    return "published"
+
+@listen("hold")
+def on_hold(self, prev):
+    return "held for later"
+```
+
+### Limitations
+
+- **`@start()` methods run once**: A `@start()` method cannot self-loop. If you need a revision cycle, use a separate `@start()` method as the entry point and put the `@human_feedback` on a `@listen()` method.
+- **No `@start()` + `@listen()` on the same method**: This is a Flow framework constraint. A method is either a start point or a listener, not both.
 
 ## Best Practices
 
 ### 1. Write Clear Request Messages
 
-The `request` parameter is what the human sees. Make it actionable:
+The `message` parameter is what the human sees. Make it actionable:
 
 ```python Code
 # ✅ Good - clear and actionable
@@ -510,9 +582,9 @@ class ContentPipeline(Flow):
     @start()
     @human_feedback(
         message="Approve this content for publication?",
-        emit=["approved", "rejected", "needs_revision"],
+        emit=["approved", "rejected"],
         llm="gpt-4o-mini",
-        default_outcome="needs_revision",
+        default_outcome="rejected",
         provider=SlackNotificationProvider("#content-reviews"),
     )
     def generate_content(self):
@@ -528,11 +600,6 @@ class ContentPipeline(Flow):
         print(f"Archived. Reason: {result.feedback}")
         return {"status": "archived"}
 
-    @listen("needs_revision")
-    def queue_revision(self, result):
-        print(f"Queued for revision: {result.feedback}")
-        return {"status": "revision_needed"}
-
 
 # Starting the flow (will pause and wait for Slack response)
 def start_content_pipeline():
@@ -572,6 +639,64 @@ If you're using an async web framework (FastAPI, aiohttp, Slack Bolt async mode)
 5. **Automatic persistence**: State is automatically saved when `HumanFeedbackPending` is raised and uses `SQLiteFlowPersistence` by default
 6. **Custom persistence**: Pass a custom persistence instance to `from_pending()` if needed
 
+## Learning from Feedback
+
+The `learn=True` parameter enables a feedback loop between human reviewers and the memory system. When enabled, the system progressively improves its outputs by learning from past human corrections.
+
+### How It Works
+
+1. **After feedback**: The LLM extracts generalizable lessons from the output + feedback and stores them in memory with `source="hitl"`. If the feedback is just approval (e.g. "looks good"), nothing is stored.
+2. **Before next review**: Past HITL lessons are recalled from memory and applied by the LLM to improve the output before the human sees it.
+
+Over time, the human sees progressively better pre-reviewed output because each correction informs future reviews.
+
+### Example
+
+```python Code
+class ArticleReviewFlow(Flow):
+    @start()
+    def generate_article(self):
+        return self.crew.kickoff(inputs={"topic": "AI Safety"}).raw
+
+    @human_feedback(
+        message="Review this article draft:",
+        emit=["approved", "needs_revision"],
+        llm="gpt-4o-mini",
+        learn=True,  # enable HITL learning
+    )
+    @listen(or_("generate_article", "needs_revision"))
+    def review_article(self):
+        return self.last_human_feedback.output if self.last_human_feedback else "article draft"
+
+    @listen("approved")
+    def publish(self):
+        print(f"Publishing: {self.last_human_feedback.output}")
+```
+
+**First run**: The human sees the raw output and says "Always include citations for factual claims." The lesson is distilled and stored in memory.
+
+**Second run**: The system recalls the citation lesson, pre-reviews the output to add citations, then shows the improved version. The human's job shifts from "fix everything" to "catch what the system missed."
+
+### Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `learn` | `False` | Enable HITL learning |
+| `learn_limit` | `5` | Max past lessons to recall for pre-review |
+
+### Key Design Decisions
+
+- **Same LLM for everything**: The `llm` parameter on the decorator is shared by outcome collapsing, lesson distillation, and pre-review. No need to configure multiple models.
+- **Structured output**: Both distillation and pre-review use function calling with Pydantic models when the LLM supports it, falling back to text parsing otherwise.
+- **Non-blocking storage**: Lessons are stored via `remember_many()` which runs in a background thread -- the flow continues immediately.
+- **Graceful degradation**: If the LLM fails during distillation, nothing is stored. If it fails during pre-review, the raw output is shown. Neither failure blocks the flow.
+- **No scope/categories needed**: When storing lessons, only `source` is passed. The encoding pipeline infers scope, categories, and importance automatically.
+
+<Note>
+`learn=True` requires the Flow to have memory available. Flows get memory automatically by default, but if you've disabled it with `_skip_auto_memory`, HITL learning will be silently skipped.
+</Note>
+
+
 ## Related Documentation
 
 - [Flows Overview](/en/concepts/flows) - Learn about CrewAI Flows
@@ -579,3 +704,4 @@ If you're using an async web framework (FastAPI, aiohttp, Slack Bolt async mode)
 - [Flow Persistence](/en/concepts/flows#persistence) - Persisting flow state
 - [Routing with @router](/en/concepts/flows#router) - More about conditional routing
 - [Human Input on Execution](/en/learn/human-input-on-execution) - Task-level human input
+- [Memory](/en/concepts/memory) - The unified memory system used by HITL learning

docs/en/learn/human-in-the-loop.mdx

@@ -11,10 +11,10 @@ Human-in-the-Loop (HITL) is a powerful approach that combines artificial intelli
 
 CrewAI offers two main approaches for implementing human-in-the-loop workflows:
 
-| Approach | Best For | Integration |
-|----------|----------|-------------|
-| **Flow-based** (`@human_feedback` decorator) | Local development, console-based review, synchronous workflows | [Human Feedback in Flows](/en/learn/human-feedback-in-flows) |
-| **Webhook-based** (Enterprise) | Production deployments, async workflows, external integrations (Slack, Teams, etc.) | This guide |
+| Approach | Best For | Integration | Version |
+|----------|----------|-------------|---------|
+| **Flow-based** (`@human_feedback` decorator) | Local development, console-based review, synchronous workflows | [Human Feedback in Flows](/en/learn/human-feedback-in-flows) | **1.8.0+** |
+| **Webhook-based** (Enterprise) | Production deployments, async workflows, external integrations (Slack, Teams, etc.) | This guide | - |
 
 <Tip>
 If you're building flows and want to add human review steps with routing based on feedback, check out the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide for the `@human_feedback` decorator.
@@ -151,3 +151,9 @@ HITL workflows are particularly valuable for:
 - Sensitive or high-stakes operations
 - Creative tasks requiring human judgment
 - Compliance and regulatory reviews
+
+## Enterprise Features
+
+<Card title="Flow HITL Management Platform" icon="users-gear" href="/en/enterprise/features/flow-hitl-management">
+  CrewAI Enterprise provides a comprehensive HITL management system for Flows with in-platform review, responder assignment, permissions, escalation policies, SLA management, dynamic routing, and full analytics. [Learn more →](/en/enterprise/features/flow-hitl-management)
+</Card>

docs/en/observability/galileo.mdx

@@ -0,0 +1,115 @@
+---
+title: Galileo
+description: Galileo integration for CrewAI tracing and evaluation
+icon: telescope
+mode: "wide"
+---
+
+## Overview
+
+This guide demonstrates how to integrate **Galileo** with **CrewAI**
+for comprehensive tracing and Evaluation Engineering.
+By the end of this guide, you will be able to trace your CrewAI agents,
+monitor their performance, and evaluate their behaviour with
+Galileo's powerful observability platform.
+
+> **What is Galileo?** [Galileo](https://galileo.ai) is AI evaluation and observability
+platform that delivers end-to-end tracing, evaluation,
+and monitoring for AI applications. It enables teams to capture ground truth,
+create robust guardrails, and run systematic experiments with
+built-in experiment tracking and performance analytics—ensuring reliability,
+transparency, and continuous improvement across the AI lifecycle.
+
+## Getting started
+
+This tutorial follows the [CrewAI quickstart](/en/quickstart) and shows how to add
+Galileo's [CrewAIEventListener](https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler),
+an event handler.
+For more information, see Galileo’s
+[Add Galileo to a CrewAI Application](https://v2docs.galileo.ai/how-to-guides/third-party-integrations/add-galileo-to-crewai/add-galileo-to-crewai)
+how-to guide.
+
+> **Note** This tutorial assumes you have completed the [CrewAI quickstart](/en/quickstart).
+If you want a completed comprehensive example, see the Galileo
+[CrewAI sdk-example repo](https://github.com/rungalileo/sdk-examples/tree/main/python/agent/crew-ai).
+
+### Step 1: Install dependencies
+
+Install the required dependencies for your app.
+Create a virtual environment using your preferred method,
+then install dependencies inside that environment using your
+preferred tool:
+
+```bash
+uv add galileo 
+```
+
+### Step 2: Add to the .env file from the [CrewAI quickstart](/en/quickstart)
+
+```bash
+# Your Galileo API key
+GALILEO_API_KEY="your-galileo-api-key"
+
+# Your Galileo project name
+GALILEO_PROJECT="your-galileo-project-name"
+
+# The name of the Log stream you want to use for logging
+GALILEO_LOG_STREAM="your-galileo-log-stream "
+```
+
+### Step 3: Add the Galileo event listener
+
+To enable logging with Galileo, you need to create an instance of the `CrewAIEventListener`.
+Import the Galileo CrewAI handler package by
+adding the following code at the top of your main.py file:
+
+```python
+from galileo.handlers.crewai.handler import CrewAIEventListener
+```
+
+At the start of your run function, create the event listener:
+
+```python
+def run():
+    # Create the event listener
+    CrewAIEventListener()
+    # The rest of your existing code goes here
+```
+
+When you create the listener instance, it is automatically
+registered with CrewAI.
+
+### Step 4: Run your crew
+
+Run your crew with the CrewAI CLI:
+
+```bash
+crewai run
+```
+
+### Step 5: View the traces in Galileo
+
+Once your crew has finished, the traces will be flushed and appear in Galileo.
+
+![Galileo trace view](/images/galileo-trace-veiw.png)
+  
+## Understanding the Galileo Integration
+
+Galileo integrates with CrewAI by registering an event listener
+that captures Crew execution events (e.g., agent actions, tool calls, model responses)
+and forwards them to Galileo for observability and evaluation.
+
+### Understanding the event listener
+
+Creating a `CrewAIEventListener()` instance is all that’s
+required to enable Galileo for a CrewAI run. When instantiated, the listener:
+
+- Automatically registers itself with CrewAI
+- Reads Galileo configuration from environment variables
+- Logs all run data to the Galileo project and log stream specified by
+  `GALILEO_PROJECT` and `GALILEO_LOG_STREAM`
+
+No additional configuration or code changes are required.
+All data from this run is logged to the Galileo project and
+log stream specified by your environment configuration
+(for example, GALILEO_PROJECT and GALILEO_LOG_STREAM).

docs/en/tools/database-data/nl2sqltool.mdx

@@ -15,6 +15,29 @@ Along with that provides the ability for the Agent to update the database based
 
 **Attention**: Make sure that the Agent has access to a Read-Replica or that is okay for the Agent to run insert/update queries on the database.
 
+## Security Model
+
+`NL2SQLTool` is an execution-capable tool. It runs model-generated SQL directly against the configured database connection.
+
+This means risk depends on your deployment choices:
+
+- Which credentials you provide in `db_uri`
+- Whether untrusted input can influence prompts
+- Whether you add tool-call guardrails before execution
+
+If you route untrusted input to agents using this tool, treat it as a high-risk integration.
+
+## Hardening Recommendations
+
+Use all of the following in production:
+
+- Use a read-only database user whenever possible
+- Prefer a read replica for analytics/retrieval workloads
+- Grant least privilege (no superuser/admin roles, no file/system-level capabilities)
+- Apply database-side resource limits (statement timeout, lock timeout, cost/row limits)
+- Add `before_tool_call` hooks to enforce allowed query patterns
+- Enable query logging and alerting for destructive statements
+
 ## Requirements
 
 - SqlAlchemy

docs/ko/changelog.mdx

@@ -4,6 +4,613 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 1월 26일">
+  ## v1.9.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.9.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 프로바이더 전반에 걸친 구조화된 출력 및 response_format 지원 추가
+  - 스트리밍 응답에 응답 ID 추가
+  - 부모-자식 계층 구조를 가진 이벤트 순서 추가
+  - Keycloak SSO 인증 지원 추가
+  - 멀티모달 파일 처리 기능 추가
+  - 네이티브 OpenAI responses API 지원 추가
+  - A2A 작업 실행 유틸리티 추가
+  - A2A 서버 구성 및 에이전트 카드 생성 추가
+  - 이벤트 시스템 향상 및 전송 옵션 확장
+  - 도구 호출 메커니즘 개선
+
+  ### 버그 수정
+  - aiocache를 사용할 수 없을 때 폴백 메모리 캐시로 파일 저장소 향상
+  - 문서 목록이 비어 있지 않도록 보장
+  - Bedrock 중지 시퀀스 적절히 처리
+  - Google Vertex API 키 지원 추가
+  - Azure 모델 중지 단어 감지 향상
+  - 흐름 실행 시 HumanFeedbackPending 오류 처리 개선
+  - 실행 스팬 작업 연결 해제 수정
+
+  ### 문서
+  - 네이티브 파일 처리 문서 추가
+  - OpenAI responses API 문서 추가
+  - 에이전트 카드 구현 가이드 추가
+  - A2A 문서 개선
+  - v1.8.0 변경 로그 업데이트
+
+  ### 기여자
+  @Anaisdg, @GininDenis, @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @koushiv777, @lorenzejay, @nicoferdi96, @vinibrsl
+
+</Update>
+
+<Update label="2026년 1월 15일">
+  ## v1.8.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.8.1)
+
+  ## 변경 사항
+
+  ### 기능
+  - A2A 작업 실행 유틸리티 추가
+  - A2A 서버 구성 및 에이전트 카드 생성 추가
+  - 추가 전송 메커니즘 추가
+  - Galileo 통합 지원 추가
+
+  ### 버그 수정
+  - Azure 모델 호환성 개선
+  - parent_flow 감지를 위한 프레임 검사 깊이 확장
+  - 작업 실행 스팬 관리 문제 해결
+  - 흐름 실행 중 휴먼 피드백 시나리오에 대한 오류 처리 향상
+
+  ### 문서
+  - A2A 에이전트 카드 문서 추가
+  - PII 삭제 기능 문서 추가
+
+  ### 기여자
+  @Anaisdg, @GininDenis, @greysonlalonde, @joaomdmoura, @koushiv777, @lorenzejay, @vinibrsl
+
+</Update>
+
+<Update label="2026년 1월 8일">
+  ## v1.8.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.8.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - a2a를 위한 네이티브 비동기 체인 추가
+  - 핸들러 및 설정과 함께 a2a 업데이트 메커니즘(poll/stream/push) 추가
+  - 휴먼 인 더 루프 피드백을 위한 전역 흐름 설정 도입
+  - 스트리밍 도구 호출 이벤트 추가 및 프로바이더 ID 추적 수정
+  - 프로덕션 준비된 Flows 및 Crews 아키텍처 도입
+  - Flows를 위한 HITL 추가
+  - 향상된 이벤트 처리를 위한 EventListener 및 TraceCollectionListener 개선
+
+  ### 버그 수정
+  - 누락된 a2a 종속성을 선택적으로 처리
+  - WorkOS 로그인 폴링을 위한 오류 가져오기 수정
+  - 샘플 문서의 잘못된 트리거 이름 수정
+
+  ### 문서
+  - 웹훅 스트리밍 문서 업데이트
+  - AOP에서 AMP로 문서 언어 조정
+
+  ### 기여자
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta
+
+</Update>
+
+<Update label="2025년 12월 19일">
+  ## v1.7.2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.7.2)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 연결 문제 해결
+
+  ### 문서
+  - api-reference/status 문서 페이지 업데이트
+
+  ### 기여자
+  @greysonlalonde, @heitorado, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="2025년 12월 16일">
+  ## v1.7.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.7.1)
+
+  ## 변경 사항
+
+  ### 개선 사항
+  - bump 명령에 `--no-commit` 플래그 추가
+  - 도구 인수 직렬화에 JSON 스키마 사용
+
+  ### 버그 수정
+  - 도구 저장소 로그인 실패 시 응답에서 오류 메시지 표시 수정
+  - 비동기 작업 실행 시 future의 정상적인 종료 수정
+  - 인덱스를 추가하여 작업 순서 수정
+  - Windows 신호에 대한 플랫폼 호환성 검사 수정
+  - 프로세스 중단을 방지하기 위한 RPM 컨트롤러 타이머 수정
+  - 토큰 사용량 기록 수정 및 스트림에서 응답 모델 검증
+
+  ### 문서
+  - 비동기에 대한 번역된 문서 추가
+  - AOP Deploy API 문서 추가
+  - 에이전트 핸들러 커넥터 문서 추가
+  - 네이티브 비동기 문서 추가
+
+  ### 기여자
+  @Llamrei, @dragosmc, @gilfeig, @greysonlalonde, @heitorado, @lorenzejay, @mattatcha, @vinibrsl
+
+</Update>
+
+<Update label="2025년 12월 9일">
+  ## v1.7.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.7.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 비동기 흐름 킥오프 추가
+  - 비동기 크루 지원 추가
+  - 비동기 작업 지원 추가
+  - 비동기 지식 지원 추가
+  - 비동기 메모리 지원 추가
+  - 도구 및 에이전트 실행기에 대한 비동기 지원 추가; 타입 및 문서 개선
+  - a2a 확장 API 및 비동기 에이전트 카드 캐싱 구현; 작업 전파 및 스트리밍 수정
+  - 네이티브 비동기 도구 지원 추가
+  - 비동기 llm 지원 추가
+  - sys 이벤트 유형 및 핸들러 생성
+
+  ### 버그 수정
+  - nonetypes가 otel에 전달되지 않도록 보장하는 문제 수정
+  - 토큰 저장소 파일 작업의 교착 상태 수정
+  - otel span이 닫히도록 보장하는 수정
+  - 임베딩에 HuggingFaceEmbeddingFunction 사용, 키 업데이트 및 테스트 추가
+  - 모든 지원되는 anthropic 모델에 대해 supports_tools가 true인지 확인
+  - 라이트 에이전트 흐름에서 훅이 작동하도록 보장
+
+  ### 기여자
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="2025년 11월 29일">
+  ## v1.6.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.6.1)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - ChatCompletionsClient 호출이 제대로 작동하도록 수정
+  - 어노테이션에 대해 비동기 메서드가 실행 가능하도록 보장
+  - RagTool.add의 매개변수 수정, 타입 및 테스트 추가
+  - SSE 클라이언트에서 잘못된 매개변수 제거
+  - 'crewai config reset' 명령에서 'oauth2_extra' 설정 삭제
+
+  ### 리팩토링
+  - LLM 클래스에서 모델 검증 및 프로바이더 추론 향상
+
+  ### 기여자
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @lorenzejay
+
+</Update>
+
+<Update label="2025년 11월 25일">
+  ## v1.6.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.6.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 흐름 및 크루에 스트리밍 결과 지원 추가
+  - gemini-3-pro-preview 추가
+  - Entra ID를 사용한 CLI 로그인 지원
+  - Merge Agent Handler 도구 추가
+  - 흐름 이벤트 상태 관리 향상
+
+  ### 버그 수정
+  - 사용자 지정 rag 저장소 지속 경로가 전달된 경우 설정되도록 보장
+  - 퍼지 반환이 더 엄격하고 타입 경고를 표시하도록 보장
+  - openai response_format 매개변수 다시 추가 및 테스트 추가
+  - rag 도구 임베딩 설정 수정
+  - 플롯에서 흐름 실행 시작 패널이 표시되지 않도록 보장
+
+  ### 문서
+  - 문서에서 AMP에서 AOP로 참조 업데이트
+  - AMP에서 AOP로 업데이트
+
+  ### 기여자
+  @Vidit-Ostwal, @gilfeig, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @markmcd
+
+</Update>
+
+<Update label="2025년 11월 22일">
+  ## v0.203.2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.203.2)
+
+  ## 변경 사항
+
+  - 0.203.1에서 0.203.2로 핫픽스 버전 범프
+
+</Update>
+
+<Update label="2025년 11월 16일">
+  ## v1.5.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.5.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - a2a 신뢰 원격 완료 상태 플래그 추가
+  - Okta 인증 서버에 대한 더 많은 데이터 가져오기 및 저장
+  - CrewAgentExecutor에서 LLM 호출 전후 훅 구현
+  - TaskOutput 및 LiteAgentOutputs에 메시지 노출
+  - QdrantVectorSearchTool의 스키마 설명 향상
+
+  ### 버그 수정
+  - 추적 인스트루멘테이션 플래그가 올바르게 적용되도록 보장
+  - 사용자 정의 도구 문서 링크 수정 및 Mintlify 깨진 링크 작업 추가
+
+  ### 문서
+  - LLM 기반 검증 지원으로 작업 가드레일 문서 향상
+
+  ### 기여자
+  @danielfsbarreto, @greysonlalonde, @heitorado, @lorenzejay, @theCyberTech
+
+</Update>
+
+<Update label="2025년 11월 7일">
+  ## v1.4.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.4.1)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 에이전트 최대 반복 처리 수정
+  - LLM 모델 구문에 대한 라우팅 문제를 해당 프로바이더로 해결
+
+  ### 기여자
+  @greysonlalonde
+
+</Update>
+
+<Update label="2025년 11월 7일">
+  ## v1.4.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.4.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 비AST 플롯 경로 지원 추가
+  - MCP에 대한 일급 지원 구현
+  - BaseInterceptor에 Pydantic 검증 던더 추가
+  - LLM 메시지 인터셉터 훅 지원 추가
+  - 효율적인 사용을 위한 i18n 프롬프트 캐싱
+  - QdrantVectorSearchTool 향상
+
+  ### 버그 수정
+  - stopwords 업데이트 유지 관련 문제 수정
+  - 흐름 상태에서 피클할 수 없는 값 해결
+  - 라이트 에이전트가 검증 오류 시 수정되도록 보장
+  - 캐싱이 작동하도록 콜백 인수 해싱 수정
+  - 유효한 URL에서 RAG 소스 콘텐츠 추가 허용
+  - 플롯 노드 선택을 더 부드럽게 만듦
+  - 지식에 대한 중복 문서 ID 수정
+
+  ### 리팩토링
+  - concurrent futures로 MCP 도구 실행 처리 개선
+  - 흐름 처리, 타입 및 로깅 단순화; UI 및 테스트 업데이트
+  - 중지 단어 관리를 속성으로 리팩토링
+
+  ### 문서
+  - embedder를 embedding_model로 마이그레이션하고 도구 문서 전체에 vectordb 필요; 프로바이더 예제 추가 (en/ko/pt-BR)
+
+  ### 기여자
+  @danielfsbarreto, @greysonlalonde, @lorenzejay, @lucasgomide, @tonykipkemboi
+
+</Update>
+
+<Update label="2025년 11월 1일">
+  ## v1.3.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.3.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 흐름 처리, 타입 및 로깅 리팩토링
+  - QdrantVectorSearchTool 향상
+
+  ### 버그 수정
+  - Firecrawl 도구 수정 및 테스트 추가
+  - use_stop_words를 속성으로 리팩토링하고 중지 단어 확인 추가
+
+  ### 문서
+  - embedder를 embedding_model로 마이그레이션하고 도구 문서 전체에 vectordb 필요
+  - 영어, 한국어 및 포르투갈어로 프로바이더 예제 추가
+
+  ### 리팩토링
+  - 흐름 처리 및 UI 업데이트 개선
+
+  ### 기여자
+  @danielfsbarreto, @greysonlalonde, @lorenzejay, @lucasgomide, @tonykipkemboi
+
+</Update>
+
+<Update label="2025년 10월 27일">
+  ## v1.2.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.2.1)
+
+  ## 변경 사항
+
+  ### 기능
+  - Datadog 통합 지원 추가
+  - liteagent에서 apps 및 mcps 지원
+
+  ### 문서
+  - 각 통합에 대해 Platform 도구를 호출하기 위한 필수 환경 변수 설명
+  - Datadog 통합 문서 추가
+
+  ### 기여자
+  @barieom, @lorenzejay, @lucasgomide, @sabrenner
+
+</Update>
+
+<Update label="2025년 10월 24일">
+  ## v1.2.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.2.0)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 기본 LLM 모델 업데이트 및 LLM 유틸리티의 오류 로깅 개선
+  - 흐름 시각화 디렉토리 및 메서드 검사 변경
+
+  ### 사용되지 않는 항목 삭제
+  - aisuite 제거
+
+  ### 기여자
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="2025년 10월 21일">
+  ## v1.1.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.1.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - InternalInstructor를 향상하여 여러 LLM 프로바이더 지원
+  - mypy 플러그인 기반 구현
+  - QdrantVectorSearchTool 개선
+
+  ### 버그 수정
+  - 깨진 통합 문서 링크 수정
+  - 이중 추적 호출 수정 및 타입 추가
+  - 템플릿 버전을 최신으로 고정
+
+  ### 문서
+  - LLM 통합 세부 정보 및 예제 업데이트
+
+  ### 리팩토링
+  - CrewBase 타이핑 개선
+
+  ### 기여자
+  @cwarre33, @danielfsbarreto, @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="2025년 10월 20일">
+  ## v1.0.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 버전을 1.0.0으로 범프
+  - Agent 클래스에서 지식 및 가드레일 이벤트 처리 향상
+  - crewai run 명령에 도구 저장소 자격 증명 주입
+
+  ### 버그 수정
+  - Flow 데코레이터에서 중첩된 조건 구조 유지
+  - Printer.print 메서드에 표준 인쇄 매개변수 추가
+  - input()을 사용할 수 없을 때 오류 수정
+  - JWT 디코딩 시 10초 여유 추가
+  - 잘못된 cron 일정 되돌리기
+  - 특정 날짜에 5일마다 실행되도록 cron 일정 수정
+  - 하드코딩된 경로 대신 Docker 바이너리에 시스템 PATH 사용
+  - 템플릿 디렉토리를 올바르게 제외하기 위한 CodeQL 구성 추가
+
+  ### 문서
+  - 취약점 보고를 위한 보안 정책 업데이트
+  - CrewAI AMP에서 텔레메트리 로그 캡처 가이드 추가
+  - 누락된 /resume 파일 추가
+  - HITL 워크플로에서 웹훅 URL 매개변수 명확화
+
+  ### 기여자
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta, @theCyberTech
+
+</Update>
+
+<Update label="2025년 10월 18일">
+  ## v1.0.0b3 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b3)
+
+  ## 변경 사항
+
+  ### 기능
+  - 작업 가드레일 기능 및 검증 향상
+  - 네이티브 SDK 가져오기 지원 개선
+  - Azure 네이티브 테스트 추가
+  - 고급 기능으로 BedrockCompletion 클래스 향상
+  - 클라이언트 매개변수 지원으로 GeminiCompletion 클래스 향상
+  - 추가 클라이언트 매개변수로 AnthropicCompletion 클래스 향상
+
+  ### 버그 수정
+  - Flow 데코레이터에서 중첩된 조건 구조 유지
+  - Printer.print 메서드에 표준 인쇄 매개변수 추가
+  - stdout 인쇄 제거 및 테스트 결정론 개선
+
+  ### 리팩토링
+  - 전체 타이핑을 포함한 메타클래스로 프로젝트 모듈 변환
+
+  ### 기여자
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
+<Update label="2025년 10월 16일">
+  ## v1.0.0b2 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b2)
+
+  ## 변경 사항
+
+  ### 기능
+  - 추가 클라이언트 매개변수로 OpenAICompletion 클래스 향상
+  - 이벤트 버스 스레드 안전성 및 비동기 지원 개선
+  - crewai run 명령에 도구 저장소 자격 증명 주입
+
+  ### 버그 수정
+  - input()을 사용할 수 없을 때 오류가 발생하는 문제 수정
+  - JWT 디코딩 시 10초 여유 추가
+  - task.py에서 복사 및 NOT_SPECIFIED 확인 수정
+
+  ### 문서
+  - 문서에서 CREWAI_PLATFORM_INTEGRATION_TOKEN이 언급되도록 보장
+  - 트리거 문서 업데이트
+
+  ### 기여자
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="2025년 10월 14일">
+  ## v1.0.0b1 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0b1)
+
+  ## 변경 사항
+
+  ### 기능
+  - 추가 클라이언트 매개변수로 OpenAICompletion 클래스 향상
+  - 이벤트 버스 스레드 안전성 및 비동기 지원 개선
+  - Bedrock LLM 통합 구현
+
+  ### 버그 수정
+  - 누락된 input() 가용성 문제 수정
+  - 10초 여유를 추가하여 JWT 디코딩 오류 해결
+  - crewai run 명령에 도구 저장소 자격 증명 주입
+  - task.py에서 복사 및 NOT_SPECIFIED 확인 수정
+
+  ### 문서
+  - 문서에서 CREWAI_PLATFORM_INTEGRATION_TOKEN이 언급되도록 보장
+  - 트리거 문서 업데이트
+
+  ### 기여자
+  @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="2025년 10월 13일">
+  ## v0.203.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/0.203.1)
+
+  ## 변경 사항
+
+  ### 핵심 개선 및 수정
+  - `crewai run` 명령에 도구 저장소 자격 증명 주입 수정
+  - 토큰 검증 오류를 줄이기 위해 JWT 디코딩 시 10초 여유 추가
+  - 특정 날짜에 5일마다 작업을 실행하도록 의도된 cron 일정 수정(이후 되돌림)
+
+  ### 문서 및 가이드
+  - 취약점 보고 프로세스를 명확히 하기 위해 보안 정책 업데이트
+
+</Update>
+
+<Update label="2025년 10월 9일">
+  ## v1.0.0a4 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0a4)
+
+  ## 변경 사항
+
+  ### 기능
+  - Agent 클래스에서 지식 및 가드레일 이벤트 처리 향상
+  - 로컬 개발을 위한 트리거 목록 및 실행 명령 도입
+  - Platform Actions을 소비하는 새로운 접근 방식으로 문서 업데이트
+  - CrewAI AMP에서 텔레메트리 로그 캡처 가이드 추가
+
+  ### 버그 수정
+  - 잘못된 cron 일정 되돌리기
+  - 특정 날짜에 5일마다 실행되도록 cron 일정 수정
+  - 중복 행 제거 및 명시적 환경 변수 추가
+
+  ### 기여자
+  @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta, @theCyberTech
+
+</Update>
+
+<Update label="2025년 10월 7일">
+  ## v1.0.0a3 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0a3)
+
+  ## 변경 사항
+
+  ### 기능
+  - 플랫폼 작업에 대한 에이전트 지원 추가
+  - 코드 실행기 도구에 인터프리터 인수 추가
+  - 플랫폼 앱 실행에 대한 직접 지원
+
+  ### 문서
+  - 플랫폼 작업 문서 추가
+  - MCP 문서에 stdio 및 sse 전송 유형 추가
+  - AWS 모델 목록 업데이트
+
+  ### 기여자
+  @greysonlalonde, @heitorado, @lorenzejay, @lucasgomide
+
+</Update>
+
+<Update label="2025년 10월 3일">
+  ## v1.0.0a2 (프리릴리스)
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.0.0a2)
+
+  ## 변경 사항
+
+  ### 핵심 개선 및 수정
+  - 모노레포를 위한 CI 업데이트
+  - 기본 Anthropic 모델을 claude-sonnet-4-20250514로 업데이트
+  - 모델 업데이트에 대한 테스트 수정
+
+  ### 기여자
+  @greysonlalonde, @lorenzejay
+
+</Update>
+
 <Update label="2025년 9월 30일">
   ## v1.0.0a1
 

docs/ko/concepts/files.mdx

@@ -0,0 +1,267 @@
+---
+title: 파일
+description: 멀티모달 처리를 위해 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 전달하세요.
+icon: file-image
+---
+
+## 개요
+
+CrewAI는 네이티브 멀티모달 파일 입력을 지원하여 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 직접 전달할 수 있습니다. 파일은 각 LLM 프로바이더의 API 요구사항에 맞게 자동으로 포맷됩니다.
+
+<Note type="info" title="선택적 의존성">
+파일 지원을 위해서는 선택적 `crewai-files` 패키지가 필요합니다. 다음 명령어로 설치하세요:
+
+```bash
+uv add 'crewai[file-processing]'
+```
+</Note>
+
+<Note type="warning" title="얼리 액세스">
+파일 처리 API는 현재 얼리 액세스 단계입니다.
+</Note>
+
+## 파일 타입
+
+CrewAI는 5가지 특정 파일 타입과 타입을 자동 감지하는 일반 `File` 클래스를 지원합니다:
+
+| 타입 | 클래스 | 사용 사례 |
+|:-----|:------|:----------|
+| **이미지** | `ImageFile` | 사진, 스크린샷, 다이어그램, 차트 |
+| **PDF** | `PDFFile` | 문서, 보고서, 논문 |
+| **오디오** | `AudioFile` | 음성 녹음, 팟캐스트, 회의 |
+| **비디오** | `VideoFile` | 화면 녹화, 프레젠테이션 |
+| **텍스트** | `TextFile` | 코드 파일, 로그, 데이터 파일 |
+| **일반** | `File` | 콘텐츠에서 타입 자동 감지 |
+
+```python
+from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile
+
+image = ImageFile(source="screenshot.png")
+pdf = PDFFile(source="report.pdf")
+audio = AudioFile(source="meeting.mp3")
+video = VideoFile(source="demo.mp4")
+text = TextFile(source="data.csv")
+
+file = File(source="document.pdf")
+```
+
+## 파일 소스
+
+`source` 파라미터는 여러 입력 타입을 받아들이고 적절한 핸들러를 자동으로 감지합니다:
+
+### 경로에서
+
+```python
+from crewai_files import ImageFile
+
+image = ImageFile(source="./images/chart.png")
+```
+
+### URL에서
+
+```python
+from crewai_files import ImageFile
+
+image = ImageFile(source="https://example.com/image.png")
+```
+
+### 바이트에서
+
+```python
+from crewai_files import ImageFile, FileBytes
+
+image_bytes = download_image_from_api()
+image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
+image = ImageFile(source=image_bytes)
+```
+
+## 파일 사용하기
+
+파일은 여러 레벨에서 전달할 수 있으며, 더 구체적인 레벨이 우선순위를 가집니다.
+
+### Crew와 함께
+
+crew를 킥오프할 때 파일을 전달합니다:
+
+```python
+from crewai import Crew
+from crewai_files import ImageFile
+
+crew = Crew(agents=[analyst], tasks=[analysis_task])
+
+result = crew.kickoff(
+    inputs={"topic": "Q4 Sales"},
+    input_files={
+        "chart": ImageFile(source="sales_chart.png"),
+        "report": PDFFile(source="quarterly_report.pdf"),
+    }
+)
+```
+
+### Task와 함께
+
+특정 작업에 파일을 첨부합니다:
+
+```python
+from crewai import Task
+from crewai_files import ImageFile
+
+task = Task(
+    description="매출 차트를 분석하고 {chart}에서 트렌드를 파악하세요",
+    expected_output="주요 트렌드 요약",
+    input_files={
+        "chart": ImageFile(source="sales_chart.png"),
+    }
+)
+```
+
+### Flow와 함께
+
+flow에 파일을 전달하면 자동으로 crew에 상속됩니다:
+
+```python
+from crewai.flow.flow import Flow, start
+from crewai_files import ImageFile
+
+class AnalysisFlow(Flow):
+    @start()
+    def analyze(self):
+        return self.analysis_crew.kickoff()
+
+flow = AnalysisFlow()
+result = flow.kickoff(
+    input_files={"image": ImageFile(source="data.png")}
+)
+```
+
+### 단독 에이전트와 함께
+
+에이전트 킥오프에 직접 파일을 전달합니다:
+
+```python
+from crewai import Agent
+from crewai_files import ImageFile
+
+agent = Agent(
+    role="Image Analyst",
+    goal="Analyze images",
+    backstory="Expert at visual analysis",
+    llm="gpt-4o",
+)
+
+result = agent.kickoff(
+    messages="What's in this image?",
+    input_files={"photo": ImageFile(source="photo.jpg")},
+)
+```
+
+## 파일 우선순위
+
+여러 레벨에서 파일이 전달될 때, 더 구체적인 레벨이 상위 레벨을 오버라이드합니다:
+
+```
+Flow input_files < Crew input_files < Task input_files
+```
+
+예를 들어, Flow와 Task 모두 `"chart"`라는 이름의 파일을 정의하면, Task의 버전이 사용됩니다.
+
+## 프로바이더 지원
+
+각 프로바이더는 서로 다른 파일 타입을 지원합니다. CrewAI는 각 프로바이더의 API에 맞게 파일을 자동으로 포맷합니다.
+
+| 프로바이더 | 이미지 | PDF | 오디오 | 비디오 | 텍스트 |
+|:---------|:-----:|:---:|:-----:|:-----:|:----:|
+| **OpenAI** (completions API) | ✓ | | | | |
+| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | |
+| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
+| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
+| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |
+
+<Note type="info" title="최대 파일 지원을 위한 Gemini">
+Google Gemini 모델은 비디오를 포함한 모든 파일 타입을 지원합니다 (최대 1시간, 2GB). 비디오 콘텐츠를 처리해야 할 때 Gemini를 사용하세요.
+</Note>
+
+<Note type="warning" title="지원되지 않는 파일 타입">
+프로바이더가 지원하지 않는 파일 타입을 전달하면 (예: OpenAI에 비디오) `UnsupportedFileTypeError`가 발생합니다. 처리해야 하는 파일 타입에 따라 프로바이더를 선택하세요.
+</Note>
+
+## 파일 전송 방식
+
+CrewAI는 각 프로바이더에 파일을 전송하는 최적의 방법을 자동으로 선택합니다:
+
+| 방식 | 설명 | 사용 조건 |
+|:-------|:------------|:----------|
+| **인라인 Base64** | 파일이 요청에 직접 임베드됨 | 작은 파일 (일반적으로 < 5MB) |
+| **파일 업로드 API** | 파일이 별도로 업로드되고 ID로 참조됨 | 임계값을 초과하는 큰 파일 |
+| **URL 참조** | 직접 URL이 모델에 전달됨 | 파일 소스가 이미 URL인 경우 |
+
+### 프로바이더 전송 방식
+
+| 프로바이더 | 인라인 Base64 | 파일 업로드 API | URL 참조 |
+|:---------|:-------------:|:---------------:|:--------------:|
+| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
+| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
+| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
+| **AWS Bedrock** | ✓ | | ✓ (S3 URI) |
+| **Azure OpenAI** | ✓ | | ✓ |
+
+<Note type="info" title="자동 최적화">
+이를 직접 관리할 필요가 없습니다. CrewAI는 파일 크기와 프로바이더 기능에 따라 가장 효율적인 방법을 자동으로 사용합니다. 파일 업로드 API가 없는 프로바이더는 모든 파일에 인라인 base64를 사용합니다.
+</Note>
+
+## 파일 처리 모드
+
+프로바이더 제한을 초과할 때 파일 처리 방식을 제어합니다:
+
+```python
+from crewai_files import ImageFile, PDFFile
+
+image = ImageFile(source="large.png", mode="strict")
+image = ImageFile(source="large.png", mode="auto")
+image = ImageFile(source="large.png", mode="warn")
+pdf = PDFFile(source="large.pdf", mode="chunk")
+```
+
+## 프로바이더 제약사항
+
+각 프로바이더는 파일 크기와 규격에 대한 특정 제한이 있습니다:
+
+### OpenAI
+- **이미지**: 최대 20 MB, 요청당 최대 10개 이미지
+- **PDF**: 최대 32 MB, 최대 100 페이지
+- **오디오**: 최대 25 MB, 최대 25분
+
+### Anthropic
+- **이미지**: 최대 5 MB, 최대 8000x8000 픽셀, 최대 100개 이미지
+- **PDF**: 최대 32 MB, 최대 100 페이지
+
+### Google Gemini
+- **이미지**: 최대 100 MB
+- **PDF**: 최대 50 MB
+- **오디오**: 최대 100 MB, 최대 9.5시간
+- **비디오**: 최대 2 GB, 최대 1시간
+
+### AWS Bedrock
+- **이미지**: 최대 4.5 MB, 최대 8000x8000 픽셀
+- **PDF**: 최대 3.75 MB, 최대 100 페이지
+
+## 프롬프트에서 파일 참조하기
+
+작업 설명에서 파일의 키 이름을 사용하여 파일을 참조합니다:
+
+```python
+task = Task(
+    description="""
+    제공된 자료를 분석하세요:
+    1. {sales_chart}에서 차트 검토
+    2. {quarterly_report}의 데이터와 교차 참조
+    3. 주요 발견사항 요약
+    """,
+    expected_output="주요 인사이트가 포함된 분석 요약",
+    input_files={
+        "sales_chart": ImageFile(source="chart.png"),
+        "quarterly_report": PDFFile(source="report.pdf"),
+    }
+)
+```

docs/ko/concepts/flows.mdx

@@ -567,6 +567,10 @@ Fourth method running
 
 ### Human in the Loop (인간 피드백)
 
+<Note>
+`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다.
+</Note>
+
 `@human_feedback` 데코레이터는 인간의 피드백을 수집하기 위해 플로우 실행을 일시 중지하는 human-in-the-loop 워크플로우를 가능하게 합니다. 이는 승인 게이트, 품질 검토, 인간의 판단이 필요한 결정 지점에 유용합니다.
 
 ```python Code

docs/ko/concepts/llms.mdx

@@ -107,7 +107,7 @@ CrewAI 코드 내에는 사용할 모델을 지정할 수 있는 여러 위치
 
 ## 공급자 구성 예시
 
-CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양한 LLM 공급자를 지원합니다.  
+CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양한 LLM 공급자를 지원합니다.
 이 섹션에서는 프로젝트의 요구에 가장 적합한 LLM을 선택, 구성, 최적화하는 데 도움이 되는 자세한 예시를 제공합니다.
 
 <AccordionGroup>
@@ -150,11 +150,42 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     | o1-mini           | 128,000 토큰      | 빠른 추론, 복잡한 추론                       |
     | o1-preview        | 128,000 토큰      | 빠른 추론, 복잡한 추론                       |
     | o1                | 200,000 토큰      | 빠른 추론, 복잡한 추론                       |
+
+    **Responses API:**
+
+    OpenAI는 Chat Completions(기본값)와 새로운 Responses API, 두 가지 API를 제공합니다. Responses API는 네이티브 멀티모달 지원을 기반으로 처음부터 설계되었으며, 텍스트, 이미지, 오디오, 함수 호출이 모두 일급 객체입니다. 추론 모델에서 더 나은 성능을 제공하고 자동 체이닝 및 내장 도구와 같은 추가 기능을 지원합니다.
+
+    ```python Code
+    from crewai import LLM
+
+    # Chat Completions 대신 Responses API 사용
+    llm = LLM(
+        model="openai/gpt-4o",
+        api="responses",  # Responses API 활성화
+        store=True,  # 멀티턴을 위한 응답 저장 (선택사항)
+        auto_chain=True,  # 추론 모델용 자동 체이닝 (선택사항)
+    )
+    ```
+
+    **Responses API 파라미터:**
+    - `api`: Responses API를 사용하려면 `"responses"`로 설정 (기본값: `"completions"`)
+    - `instructions`: 시스템 레벨 지침 (Responses API 전용)
+    - `store`: 멀티턴 대화를 위한 응답 저장 여부
+    - `previous_response_id`: 멀티턴을 위한 이전 응답 ID
+    - `include`: 응답에 포함할 추가 데이터 (예: `["reasoning.encrypted_content"]`)
+    - `builtin_tools`: OpenAI 내장 도구 목록: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"`
+    - `parse_tool_outputs`: 파싱된 내장 도구 출력과 함께 구조화된 `ResponsesAPIResult` 반환
+    - `auto_chain`: 멀티턴 대화를 위한 응답 ID 자동 추적 및 사용
+    - `auto_chain_reasoning`: ZDR(제로 데이터 보존) 준수를 위한 암호화된 추론 항목 추적
+
+    <Tip>
+      새 프로젝트, 특히 추론 모델(o1, o3, o4)을 사용하거나 [파일](/ko/concepts/files)에 대한 네이티브 멀티모달 지원이 필요한 경우 Responses API를 사용하세요.
+    </Tip>
   </Accordion>
 
   <Accordion title="Meta-Llama">
-    Meta의 Llama API는 Meta의 대형 언어 모델 패밀리 접근을 제공합니다.  
-    API는 [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website)에서 사용할 수 있습니다.  
+    Meta의 Llama API는 Meta의 대형 언어 모델 패밀리 접근을 제공합니다.
+    API는 [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website)에서 사용할 수 있습니다.
     `.env` 파일에 다음 환경 변수를 설정하십시오:
 
     ```toml Code
@@ -207,11 +238,20 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     `.env` 파일에 API 키를 설정하십시오. 키가 필요하거나 기존 키를 찾으려면 [AI Studio](https://aistudio.google.com/apikey)를 확인하세요.
 
     ```toml .env
-    # https://ai.google.dev/gemini-api/docs/api-key
+    # Gemini API 사용 시 (다음 중 하나)
+    GOOGLE_API_KEY=<your-api-key>
     GEMINI_API_KEY=<your-api-key>
+
+    # Vertex AI Express 모드 사용 시 (API 키 인증)
+    GOOGLE_GENAI_USE_VERTEXAI=true
+    GOOGLE_API_KEY=<your-api-key>
+
+    # Vertex AI 서비스 계정 사용 시
+    GOOGLE_CLOUD_PROJECT=<your-project-id>
+    GOOGLE_CLOUD_LOCATION=<location>  # 기본값: us-central1
     ```
 
-    CrewAI 프로젝트에서의 예시 사용법:
+    **기본 사용법:**
     ```python Code
     from crewai import LLM
 
@@ -221,6 +261,34 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     )
     ```
 
+    **Vertex AI Express 모드 (API 키 인증):**
+
+    Vertex AI Express 모드를 사용하면 서비스 계정 자격 증명 대신 간단한 API 키 인증으로 Vertex AI를 사용할 수 있습니다. Vertex AI를 시작하는 가장 빠른 방법입니다.
+
+    Express 모드를 활성화하려면 `.env` 파일에 두 환경 변수를 모두 설정하세요:
+    ```toml .env
+    GOOGLE_GENAI_USE_VERTEXAI=true
+    GOOGLE_API_KEY=<your-api-key>
+    ```
+
+    그런 다음 평소처럼 LLM을 사용하세요:
+    ```python Code
+    from crewai import LLM
+
+    llm = LLM(
+        model="gemini/gemini-2.0-flash",
+        temperature=0.7
+    )
+    ```
+
+    <Info>
+      Express 모드 API 키를 받으려면:
+      - 신규 Google Cloud 사용자: [Express 모드 API 키](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) 받기
+      - 기존 Google Cloud 사용자: [서비스 계정에 바인딩된 Google Cloud API 키](https://cloud.google.com/docs/authentication/api-keys) 받기
+
+      자세한 내용은 [Vertex AI Express 모드 문서](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey)를 참조하세요.
+    </Info>
+
     ### Gemini 모델
 
     Google은 다양한 용도에 최적화된 강력한 모델을 제공합니다.
@@ -476,7 +544,7 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
 
   <Accordion title="Local NVIDIA NIM Deployed using WSL2">
 
-    NVIDIA NIM을 이용하면 Windows 기기에서 WSL2(Windows Subsystem for Linux)를 통해 강력한 LLM을 로컬로 실행할 수 있습니다.  
+    NVIDIA NIM을 이용하면 Windows 기기에서 WSL2(Windows Subsystem for Linux)를 통해 강력한 LLM을 로컬로 실행할 수 있습니다.
     이 방식은 Nvidia GPU를 활용하여 프라이빗하고, 안전하며, 비용 효율적인 AI 추론을 클라우드 서비스에 의존하지 않고 구현할 수 있습니다.
     데이터 프라이버시, 오프라인 기능이 필요한 개발, 테스트, 또는 프로덕션 환경에 최적입니다.
 
@@ -954,4 +1022,4 @@ LLM 설정을 최대한 활용하는 방법을 알아보세요:
     llm = LLM(model="openai/gpt-4o")  # 128K tokens
     ```
   </Tab>
-</Tabs>
+</Tabs>