fix: Resolve remaining lint issues (W291, W293, B904)

- Remove trailing whitespace from examples/prompt_caching_example.py
- Fix exception handling to use 'from e' for proper error chaining
- All lint checks now pass locally

Co-Authored-By: João <joao@crewai.com>

.github/workflows/build-uv-cache.yml

@@ -0,0 +1,46 @@
+name: Build uv cache
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "uv.lock"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-cache:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+
+      - name: Install dependencies and populate cache
+        run: |
+          echo "Building global UV cache for Python ${{ matrix.python-version }}..."
+          uv sync --all-groups --all-extras --no-install-project
+          echo "Cache populated successfully"
+
+      - name: Save uv caches
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}

.github/workflows/codeql.yml

@@ -0,0 +1,102 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - "src/crewai/cli/templates/**"
+  pull_request:
+    branches: [ "main" ]
+    paths-ignore:
+      - "src/crewai/cli/templates/**"
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/linter.yml

@@ -2,6 +2,9 @@ name: Lint
 
 on: [pull_request]
 
+permissions:
+  contents: read
+
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -15,8 +18,27 @@ jobs:
       - name: Fetch Target Branch
         run: git fetch origin $TARGET_BRANCH --depth=1
 
-      - name: Install Ruff
-        run: pip install ruff
+      - name: Restore global uv cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py3.11-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-main-py3.11-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: "3.11"
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --all-groups --all-extras --no-install-project
 
       - name: Get Changed Python Files
         id: changed-files
@@ -33,4 +55,14 @@ jobs:
           echo "${{ steps.changed-files.outputs.files }}" \
             | tr ' ' '\n' \
             | grep -v 'src/crewai/cli/templates/' \
-            | xargs -I{} ruff check "{}"
+            | xargs -I{} uv run ruff check "{}"
+
+      - name: Save uv caches
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py3.11-${{ hashFiles('uv.lock') }}

.github/workflows/security-checker.yml

@@ -1,23 +0,0 @@
-name: Security Checker
-
-on: [pull_request]
-
-jobs:
-  security-check:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11.9"
-
-      - name: Install dependencies
-        run: pip install bandit
-
-      - name: Run Bandit
-        run: bandit -c pyproject.toml -r src/ -ll
-

.github/workflows/tests.yml

@@ -3,7 +3,7 @@ name: Run Tests
 on: [pull_request]
 
 permissions:
-  contents: write
+  contents: read
 
 env:
   OPENAI_API_KEY: fake-api-key
@@ -22,29 +22,76 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper diff
+
+      - name: Restore global uv cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-main-py${{ matrix.python-version }}-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v6
         with:
-          enable-cache: true
-          cache-dependency-glob: |
-            **/pyproject.toml
-            **/uv.lock
-
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
+          version: "0.8.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
 
       - name: Install the project
-        run: uv sync --dev --all-extras
+        run: uv sync --all-groups --all-extras
+
+      - name: Restore test durations
+        uses: actions/cache/restore@v4
+        with:
+          path: .test_durations_py*
+          key: test-durations-py${{ matrix.python-version }}
 
       - name: Run tests (group ${{ matrix.group }} of 8)
         run: |
+          PYTHON_VERSION_SAFE=$(echo "${{ matrix.python-version }}" | tr '.' '_')
+          DURATION_FILE=".test_durations_py${PYTHON_VERSION_SAFE}"
+          
+          # Temporarily always skip cached durations to fix test splitting
+          # When durations don't match, pytest-split runs duplicate tests instead of splitting
+          echo "Using even test splitting (duration cache disabled until fix merged)"
+          DURATIONS_ARG=""
+          
+          # Original logic (disabled temporarily):
+          # if [ ! -f "$DURATION_FILE" ]; then
+          #   echo "No cached durations found, tests will be split evenly"
+          #   DURATIONS_ARG=""
+          # elif git diff origin/${{ github.base_ref }}...HEAD --name-only 2>/dev/null | grep -q "^tests/.*\.py$"; then
+          #   echo "Test files have changed, skipping cached durations to avoid mismatches"
+          #   DURATIONS_ARG=""
+          # else
+          #   echo "No test changes detected, using cached test durations for optimal splitting"
+          #   DURATIONS_ARG="--durations-path=${DURATION_FILE}"
+          # fi
+          
           uv run pytest \
             --block-network \
             --timeout=30 \
             -vv \
             --splits 8 \
             --group ${{ matrix.group }} \
+            $DURATIONS_ARG \
             --durations=10 \
             -n auto \
             --maxfail=3
+
+      - name: Save uv caches
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}

.github/workflows/type-checker.yml

@@ -3,24 +3,99 @@ name: Run Type Checks
 on: [pull_request]
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
-  type-checker:
+  type-checker-matrix:
+    name: type-checker (${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
         with:
-          python-version: "3.11.9"
+          fetch-depth: 0 # Fetch all history for proper diff
 
-      - name: Install Requirements
+      - name: Restore global uv cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-main-py${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --all-groups --all-extras
+
+      - name: Get changed Python files
+        id: changed-files
         run: |
-          pip install mypy
+          # Get the list of changed Python files compared to the base branch
+          echo "Fetching changed files..."
+          git diff --name-only --diff-filter=ACMRT origin/${{ github.base_ref }}...HEAD -- '*.py' > changed_files.txt
 
-      - name: Run type checks
-        run: mypy src
+          # Filter for files in src/ directory only (excluding tests/)
+          grep -E "^src/" changed_files.txt > filtered_changed_files.txt || true
+
+          # Check if there are any changed files
+          if [ -s filtered_changed_files.txt ]; then
+            echo "Changed Python files in src/:"
+            cat filtered_changed_files.txt
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            # Convert newlines to spaces for mypy command
+            echo "files=$(cat filtered_changed_files.txt | tr '\n' ' ')" >> $GITHUB_OUTPUT
+          else
+            echo "No Python files changed in src/"
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run type checks on changed files
+        if: steps.changed-files.outputs.has_changes == 'true'
+        run: |
+          echo "Running mypy on changed files with Python ${{ matrix.python-version }}..."
+          uv run mypy ${{ steps.changed-files.outputs.files }}
+
+      - name: No files to check
+        if: steps.changed-files.outputs.has_changes == 'false'
+        run: echo "No Python files in src/ were modified - skipping type checks"
+
+      - name: Save uv caches
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+
+  # Summary job to provide single status for branch protection
+  type-checker:
+    name: type-checker
+    runs-on: ubuntu-latest
+    needs: type-checker-matrix
+    if: always()
+    steps:
+      - name: Check matrix results
+        run: |
+          if [ "${{ needs.type-checker-matrix.result }}" == "success" ] || [ "${{ needs.type-checker-matrix.result }}" == "skipped" ]; then
+            echo "✅ All type checks passed"
+          else
+            echo "❌ Type checks failed"
+            exit 1
+          fi

.github/workflows/update-test-durations.yml

@@ -0,0 +1,71 @@
+name: Update Test Durations
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'tests/**/*.py'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  update-durations:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    env:
+      OPENAI_API_KEY: fake-api-key
+      PYTHONUNBUFFERED: 1
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Restore global uv cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-main-py${{ matrix.python-version }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+
+      - name: Install the project
+        run: uv sync --all-groups --all-extras
+
+      - name: Run all tests and store durations
+        run: |
+          PYTHON_VERSION_SAFE=$(echo "${{ matrix.python-version }}" | tr '.' '_')
+          uv run pytest --store-durations --durations-path=.test_durations_py${PYTHON_VERSION_SAFE} -n auto
+        continue-on-error: true
+
+      - name: Save durations to cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .test_durations_py*
+          key: test-durations-py${{ matrix.python-version }}
+
+      - name: Save uv caches
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+            .venv
+          key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}

.pre-commit-config.yaml

@@ -1,7 +1,19 @@
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.2
+  - repo: local
     hooks:
       - id: ruff
-        args: ["--fix"]
+        name: ruff
+        entry: uv run ruff check
+        language: system
+        types: [python]
       - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        exclude: ^tests/

.ruff.toml

@@ -1,4 +0,0 @@
-exclude = [
-    "templates",
-    "__init__.py",
-]

README.md

@@ -418,10 +418,10 @@ Choose CrewAI to easily build powerful, adaptable, and production-ready AI autom
 
 You can test different real life examples of AI crews in the [CrewAI-examples repo](https://github.com/crewAIInc/crewAI-examples?tab=readme-ov-file):
 
-- [Landing Page Generator](https://github.com/crewAIInc/crewAI-examples/tree/main/landing_page_generator)
+- [Landing Page Generator](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/landing_page_generator)
 - [Having Human input on the execution](https://docs.crewai.com/how-to/Human-Input-on-Execution)
-- [Trip Planner](https://github.com/crewAIInc/crewAI-examples/tree/main/trip_planner)
-- [Stock Analysis](https://github.com/crewAIInc/crewAI-examples/tree/main/stock_analysis)
+- [Trip Planner](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/trip_planner)
+- [Stock Analysis](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/stock_analysis)
 
 ### Quick Tutorial
 
@@ -429,19 +429,19 @@ You can test different real life examples of AI crews in the [CrewAI-examples re
 
 ### Write Job Descriptions
 
-[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/job-posting) or watch a video below:
+[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/job-posting) or watch a video below:
 
 [![Jobs postings](https://img.youtube.com/vi/u98wEMz-9to/maxresdefault.jpg)](https://www.youtube.com/watch?v=u98wEMz-9to "Jobs postings")
 
 ### Trip Planner
 
-[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/trip_planner) or watch a video below:
+[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/trip_planner) or watch a video below:
 
 [![Trip Planner](https://img.youtube.com/vi/xis7rWp-hjs/maxresdefault.jpg)](https://www.youtube.com/watch?v=xis7rWp-hjs "Trip Planner")
 
 ### Stock Analysis
 
-[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/stock_analysis) or watch a video below:
+[Check out code for this example](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/stock_analysis) or watch a video below:
 
 [![Stock Analysis](https://img.youtube.com/vi/e0Uj4yWdaAg/maxresdefault.jpg)](https://www.youtube.com/watch?v=e0Uj4yWdaAg "Stock Analysis")
 

docs/docs.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "mint",
+  "theme": "aspen",
   "name": "CrewAI",
   "colors": {
     "primary": "#EB6658",
@@ -28,20 +28,21 @@
               "icon": "discourse"
             },
             {
-              "anchor": "Crew GPT",
-              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
-              "icon": "robot"
+              "anchor": "Blog",
+              "href": "https://blog.crewai.com",
+              "icon": "newspaper"
             },
             {
-              "anchor": "Releases",
-              "href": "https://github.com/crewAIInc/crewAI/releases",
-              "icon": "tag"
+              "anchor": "CrewGPT",
+              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
+              "icon": "robot"
             }
           ]
         },
         "tabs": [
           {
             "tab": "Documentation",
+            "icon": "book-open",
             "groups": [
               {
                 "group": "Get Started",
@@ -52,18 +53,22 @@
                 "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"
@@ -71,6 +76,7 @@
                   },
                   {
                     "group": "Advanced",
+                    "icon": "gear",
                     "pages": [
                       "en/guides/advanced/customizing-prompts",
                       "en/guides/advanced/fingerprinting"
@@ -116,6 +122,7 @@
                   "en/tools/overview",
                   {
                     "group": "File & Document",
+                    "icon": "folder-open",
                     "pages": [
                       "en/tools/file-document/overview",
                       "en/tools/file-document/filereadtool",
@@ -135,6 +142,7 @@
                   },
                   {
                     "group": "Web Scraping & Browsing",
+                    "icon": "globe",
                     "pages": [
                       "en/tools/web-scraping/overview",
                       "en/tools/web-scraping/scrapewebsitetool",
@@ -154,6 +162,7 @@
                   },
                   {
                     "group": "Search & Research",
+                    "icon": "magnifying-glass",
                     "pages": [
                       "en/tools/search-research/overview",
                       "en/tools/search-research/serperdevtool",
@@ -175,6 +184,7 @@
                   },
                   {
                     "group": "Database & Data",
+                    "icon": "database",
                     "pages": [
                       "en/tools/database-data/overview",
                       "en/tools/database-data/mysqltool",
@@ -189,6 +199,7 @@
                   },
                   {
                     "group": "AI & Machine Learning",
+                    "icon": "brain",
                     "pages": [
                       "en/tools/ai-ml/overview",
                       "en/tools/ai-ml/dalletool",
@@ -202,16 +213,26 @@
                   },
                   {
                     "group": "Cloud & Storage",
+                    "icon": "cloud",
                     "pages": [
                       "en/tools/cloud-storage/overview",
                       "en/tools/cloud-storage/s3readertool",
                       "en/tools/cloud-storage/s3writertool",
-                      "en/tools/cloud-storage/bedrockinvokeagenttool",
                       "en/tools/cloud-storage/bedrockkbretriever"
                     ]
                   },
                   {
-                    "group": "Automation & Integration",
+                    "group": "Integrations",
+                    "icon": "plug",
+                    "pages": [
+                      "en/tools/tool-integrations/overview",
+                      "en/tools/tool-integrations/bedrockinvokeagenttool",
+                      "en/tools/tool-integrations/crewaiautomationtool"
+                    ]
+                  },
+                  {
+                    "group": "Automation",
+                    "icon": "bolt",
                     "pages": [
                       "en/tools/automation/overview",
                       "en/tools/automation/apifyactorstool",
@@ -273,6 +294,7 @@
           },
           {
             "tab": "Enterprise",
+            "icon": "briefcase",
             "groups": [
               {
                 "group": "Getting Started",
@@ -339,6 +361,7 @@
           },
           {
             "tab": "API Reference",
+            "icon": "magnifying-glass",
             "groups": [
               {
                 "group": "Getting Started",
@@ -353,12 +376,23 @@
           },
           {
             "tab": "Examples",
+            "icon": "code",
             "groups": [
               {
                 "group": "Examples",
                 "pages": ["en/examples/example", "en/examples/cookbooks"]
               }
             ]
+          },
+          {
+            "tab": "Changelog",
+            "icon": "clock",
+            "groups": [
+              {
+                "group": "Release Notes",
+                "pages": ["en/changelog"]
+              }
+            ]
           }
         ]
       },
@@ -377,20 +411,21 @@
               "icon": "discourse"
             },
             {
-              "anchor": "Crew GPT",
-              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
-              "icon": "robot"
+              "anchor": "Blog",
+              "href": "https://blog.crewai.com",
+              "icon": "newspaper"
             },
             {
-              "anchor": "Lançamentos",
-              "href": "https://github.com/crewAIInc/crewAI/releases",
-              "icon": "tag"
+              "anchor": "CrewGPT",
+              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
+              "icon": "robot"
             }
           ]
         },
         "tabs": [
           {
             "tab": "Documentação",
+            "icon": "book-open",
             "groups": [
               {
                 "group": "Começando",
@@ -405,18 +440,22 @@
                 "pages": [
                   {
                     "group": "Estratégia",
+                    "icon": "compass",
                     "pages": ["pt-BR/guides/concepts/evaluating-use-cases"]
                   },
                   {
                     "group": "Agentes",
+                    "icon": "user",
                     "pages": ["pt-BR/guides/agents/crafting-effective-agents"]
                   },
                   {
                     "group": "Crews",
+                    "icon": "users",
                     "pages": ["pt-BR/guides/crews/first-crew"]
                   },
                   {
                     "group": "Flows",
+                    "icon": "code-branch",
                     "pages": [
                       "pt-BR/guides/flows/first-flow",
                       "pt-BR/guides/flows/mastering-flow-state"
@@ -424,6 +463,7 @@
                   },
                   {
                     "group": "Avançado",
+                    "icon": "gear",
                     "pages": [
                       "pt-BR/guides/advanced/customizing-prompts",
                       "pt-BR/guides/advanced/fingerprinting"
@@ -469,6 +509,7 @@
                   "pt-BR/tools/overview",
                   {
                     "group": "Arquivo & Documento",
+                    "icon": "folder-open",
                     "pages": [
                       "pt-BR/tools/file-document/overview",
                       "pt-BR/tools/file-document/filereadtool",
@@ -486,6 +527,7 @@
                   },
                   {
                     "group": "Web Scraping & Navegação",
+                    "icon": "globe",
                     "pages": [
                       "pt-BR/tools/web-scraping/overview",
                       "pt-BR/tools/web-scraping/scrapewebsitetool",
@@ -504,6 +546,7 @@
                   },
                   {
                     "group": "Pesquisa",
+                    "icon": "magnifying-glass",
                     "pages": [
                       "pt-BR/tools/search-research/overview",
                       "pt-BR/tools/search-research/serperdevtool",
@@ -519,6 +562,7 @@
                   },
                   {
                     "group": "Dados",
+                    "icon": "database",
                     "pages": [
                       "pt-BR/tools/database-data/overview",
                       "pt-BR/tools/database-data/mysqltool",
@@ -531,6 +575,7 @@
                   },
                   {
                     "group": "IA & Machine Learning",
+                    "icon": "brain",
                     "pages": [
                       "pt-BR/tools/ai-ml/overview",
                       "pt-BR/tools/ai-ml/dalletool",
@@ -544,16 +589,26 @@
                   },
                   {
                     "group": "Cloud & Armazenamento",
+                    "icon": "cloud",
                     "pages": [
                       "pt-BR/tools/cloud-storage/overview",
                       "pt-BR/tools/cloud-storage/s3readertool",
                       "pt-BR/tools/cloud-storage/s3writertool",
-                      "pt-BR/tools/cloud-storage/bedrockinvokeagenttool",
                       "pt-BR/tools/cloud-storage/bedrockkbretriever"
                     ]
                   },
                   {
-                    "group": "Automação & Integração",
+                    "group": "Integrações",
+                    "icon": "plug",
+                    "pages": [
+                      "pt-BR/tools/tool-integrations/overview",
+                      "pt-BR/tools/tool-integrations/bedrockinvokeagenttool",
+                      "pt-BR/tools/tool-integrations/crewaiautomationtool"
+                    ]
+                  },
+                  {
+                    "group": "Automação",
+                    "icon": "bolt",
                     "pages": [
                       "pt-BR/tools/automation/overview",
                       "pt-BR/tools/automation/apifyactorstool",
@@ -613,6 +668,7 @@
           },
           {
             "tab": "Enterprise",
+            "icon": "briefcase",
             "groups": [
               {
                 "group": "Começando",
@@ -680,6 +736,7 @@
           },
           {
             "tab": "Referência da API",
+            "icon": "magnifying-glass",
             "groups": [
               {
                 "group": "Começando",
@@ -694,12 +751,23 @@
           },
           {
             "tab": "Exemplos",
+            "icon": "code",
             "groups": [
               {
                 "group": "Exemplos",
                 "pages": ["pt-BR/examples/example", "pt-BR/examples/cookbooks"]
               }
             ]
+          },
+          {
+            "tab": "Notas de Versão",
+            "icon": "clock",
+            "groups": [
+              {
+                "group": "Notas de Versão",
+                "pages": ["pt-BR/changelog"]
+              }
+            ]
           }
         ]
       },
@@ -718,20 +786,21 @@
               "icon": "discourse"
             },
             {
-              "anchor": "Crew GPT",
-              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
-              "icon": "robot"
+              "anchor": "블로그",
+              "href": "https://blog.crewai.com",
+              "icon": "newspaper"
             },
             {
-              "anchor": "릴리스",
-              "href": "https://github.com/crewAIInc/crewAI/releases",
-              "icon": "tag"
+              "anchor": "CrewGPT",
+              "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant",
+              "icon": "robot"
             }
           ]
         },
         "tabs": [
           {
             "tab": "기술 문서",
+            "icon": "book-open",
             "groups": [
               {
                 "group": "시작 안내",
@@ -742,18 +811,22 @@
                 "pages": [
                   {
                     "group": "전략",
+                    "icon": "compass",
                     "pages": ["ko/guides/concepts/evaluating-use-cases"]
                   },
                   {
                     "group": "에이전트 (Agents)",
+                    "icon": "user",
                     "pages": ["ko/guides/agents/crafting-effective-agents"]
                   },
                   {
                     "group": "크루 (Crews)",
+                    "icon": "users",
                     "pages": ["ko/guides/crews/first-crew"]
                   },
                   {
                     "group": "플로우 (Flows)",
+                    "icon": "code-branch",
                     "pages": [
                       "ko/guides/flows/first-flow",
                       "ko/guides/flows/mastering-flow-state"
@@ -761,6 +834,7 @@
                   },
                   {
                     "group": "고급",
+                    "icon": "gear",
                     "pages": [
                       "ko/guides/advanced/customizing-prompts",
                       "ko/guides/advanced/fingerprinting"
@@ -806,6 +880,7 @@
                   "ko/tools/overview",
                   {
                     "group": "파일 & 문서",
+                    "icon": "folder-open",
                     "pages": [
                       "ko/tools/file-document/overview",
                       "ko/tools/file-document/filereadtool",
@@ -825,6 +900,7 @@
                   },
                   {
                     "group": "웹 스크래핑 & 브라우징",
+                    "icon": "globe",
                     "pages": [
                       "ko/tools/web-scraping/overview",
                       "ko/tools/web-scraping/scrapewebsitetool",
@@ -844,6 +920,7 @@
                   },
                   {
                     "group": "검색 및 연구",
+                    "icon": "magnifying-glass",
                     "pages": [
                       "ko/tools/search-research/overview",
                       "ko/tools/search-research/serperdevtool",
@@ -865,6 +942,7 @@
                   },
                   {
                     "group": "데이터베이스 & 데이터",
+                    "icon": "database",
                     "pages": [
                       "ko/tools/database-data/overview",
                       "ko/tools/database-data/mysqltool",
@@ -879,6 +957,7 @@
                   },
                   {
                     "group": "인공지능 & 머신러닝",
+                    "icon": "brain",
                     "pages": [
                       "ko/tools/ai-ml/overview",
                       "ko/tools/ai-ml/dalletool",
@@ -892,6 +971,7 @@
                   },
                   {
                     "group": "클라우드 & 스토리지",
+                    "icon": "cloud",
                     "pages": [
                       "ko/tools/cloud-storage/overview",
                       "ko/tools/cloud-storage/s3readertool",
@@ -901,7 +981,17 @@
                     ]
                   },
                   {
-                    "group": "자동화 & 통합",
+                    "group": "통합",
+                    "icon": "plug",
+                    "pages": [
+                      "ko/tools/tool-integrations/overview",
+                      "ko/tools/tool-integrations/bedrockinvokeagenttool",
+                      "ko/tools/tool-integrations/crewaiautomationtool"
+                    ]
+                  },
+                  {
+                    "group": "자동화",
+                    "icon": "bolt",
                     "pages": [
                       "ko/tools/automation/overview",
                       "ko/tools/automation/apifyactorstool",
@@ -962,6 +1052,7 @@
           },
           {
             "tab": "엔터프라이즈",
+            "icon": "briefcase",
             "groups": [
               {
                 "group": "시작 안내",
@@ -1028,6 +1119,7 @@
           },
           {
             "tab": "API 레퍼런스",
+            "icon": "magnifying-glass",
             "groups": [
               {
                 "group": "시작 안내",
@@ -1042,12 +1134,23 @@
           },
           {
             "tab": "예시",
+            "icon": "code",
             "groups": [
               {
                 "group": "예시",
                 "pages": ["ko/examples/example", "ko/examples/cookbooks"]
               }
             ]
+          },
+          {
+            "tab": "변경 로그",
+            "icon": "clock",
+            "groups": [
+              {
+                "group": "릴리스 노트",
+                "pages": ["ko/changelog"]
+              }
+            ]
           }
         ]
       }
@@ -1057,15 +1160,23 @@
     "light": "/images/crew_only_logo.png",
     "dark": "/images/crew_only_logo.png"
   },
+  "fonts": {
+    "family": "Inter"
+  },
   "appearance": {
-    "default": "dark",
-    "strict": false
+    "default": "system",
+    "strict": false,
+    "layout": "sidenav"
+  },
+  "background": {
+    "decoration": "grid"
   },
   "navbar": {
     "links": [
       {
         "label": "Start Cloud Trial",
-        "href": "https://app.crewai.com"
+        "href": "https://app.crewai.com",
+        "icon": "arrow-up-right-from-square"
       }
     ],
     "primary": {
@@ -1084,7 +1195,20 @@
     }
   },
   "seo": {
-    "indexing": "all"
+    "indexing": "all",
+    "metatags": {
+      "og:type": "website",
+      "og:site_name": "CrewAI Documentation",
+      "og:image": "https://docs.crewai.com/images/crew_only_logo.png",
+      "twitter:card": "summary_large_image",
+      "twitter:site": "@crewAIInc",
+      "keywords": "AI agents, multi-agent systems, CrewAI, artificial intelligence, automation, Python framework, agent collaboration, AI workflows"
+    }
+  },
+  "feedback": {
+    "enabled": true,
+    "thumbsRating": true,
+    "suggestEdit": true
   },
   "redirects": [
     {
@@ -1105,7 +1229,7 @@
     },
     {
       "source": "/changelog",
-      "destination": "https://github.com/crewAIInc/crewAI/releases"
+      "destination": "/en/changelog"
     },
     {
       "source": "/telemetry",

docs/en/api-reference/inputs.mdx

@@ -2,6 +2,7 @@
 title: "GET /inputs"
 description: "Get required inputs for your crew"
 openapi: "/enterprise-api.en.yaml GET /inputs"
+mode: "wide"
 ---
 
 

docs/en/api-reference/introduction.mdx

@@ -2,6 +2,7 @@
 title: "Introduction"
 description: "Complete reference for the CrewAI Enterprise REST API"
 icon: "code"
+mode: "wide"
 ---
 
 # CrewAI Enterprise API

docs/en/api-reference/kickoff.mdx

@@ -2,6 +2,7 @@
 title: "POST /kickoff"
 description: "Start a crew execution"
 openapi: "/enterprise-api.en.yaml POST /kickoff"
+mode: "wide"
 ---
 
 

docs/en/api-reference/status.mdx

@@ -2,6 +2,7 @@
 title: "GET /status/{kickoff_id}"
 description: "Get execution status"
 openapi: "/enterprise-api.en.yaml GET /status/{kickoff_id}"
+mode: "wide"
 ---
 
 

docs/en/concepts/agents.mdx

@@ -2,6 +2,7 @@
 title: Agents
 description: Detailed guide on creating and managing agents within the CrewAI framework.
 icon: robot
+mode: "wide"
 ---
 
 ## Overview of an Agent

docs/en/concepts/cli.mdx

@@ -2,6 +2,7 @@
 title: CLI
 description: Learn how to use the CrewAI CLI to interact with CrewAI.
 icon: terminal
+mode: "wide"
 ---
 
 <Warning>Since release 0.140.0, CrewAI Enterprise started a process of migrating their login provider. As such, the authentication flow via CLI was updated. Users that use Google to login, or that created their account after July 3rd, 2025 will be unable to log in with older versions of the `crewai` library.</Warning>
@@ -282,7 +283,25 @@ Watch this video tutorial for a step-by-step demonstration of deploying your cre
   allowfullscreen
 ></iframe>
 
-### 11. API Keys
+### 11. Login
+
+Authenticate with CrewAI Enterprise using a secure device code flow (no email entry required).
+
+```shell Terminal
+crewai login
+```
+
+What happens:
+- A verification URL and short code are displayed in your terminal
+- Your browser opens to the verification URL
+- Enter/confirm the code to complete authentication
+
+Notes:
+- The OAuth2 provider and domain are configured via `crewai config` (defaults use `login.crewai.com`)
+- After successful login, the CLI also attempts to authenticate to the Tool Repository automatically
+- If you reset your configuration, run `crewai login` again to re-authenticate
+
+### 12. API Keys
 
 When running ```crewai create crew``` command, the CLI will show you a list of available LLM providers to choose from, followed by model selection for your chosen provider.
 
@@ -310,7 +329,7 @@ See the following link for each provider's key name:
 
 * [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
 
-### 12. Configuration Management
+### 13. Configuration Management
 
 Manage CLI configuration settings for CrewAI.
 
@@ -351,19 +370,15 @@ crewai config list
 ```
 
 Example output:
-```
-CrewAI CLI Configuration
-┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Setting            ┃ Value                              ┃ Description                                                                                      ┃
-┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ enterprise_base_url│ https://app.crewai.com             │ Base URL of the CrewAI Enterprise instance                                                       │
-│ org_name           │ Not set                            │ Name of the currently active organization                                                        │
-│ org_uuid           │ Not set                            │ UUID of the currently active organization                                                        │
-│ oauth2_provider    │ workos                             │ OAuth2 provider used for authentication (e.g., workos, okta, auth0).                             │
-│ oauth2_audience    │ client_01YYY                       │ OAuth2 audience value, typically used to identify the target API or resource.                    │
-│ oauth2_client_id   │ client_01XXX                       │ OAuth2 client ID issued by the provider, used during authentication requests.                    │
-│ oauth2_domain      │ login.crewai.com                   │ OAuth2 provider's domain (e.g., your-org.auth0.com) used for issuing tokens.                     │
-```
+| Setting             | Value                    | Description                                                 |
+| :------------------ | :----------------------- | :---------------------------------------------------------- |
+| enterprise_base_url | https://app.crewai.com   | Base URL of the CrewAI Enterprise instance                  |
+| org_name            | Not set                  | Name of the currently active organization                   |
+| org_uuid            | Not set                  | UUID of the currently active organization                   |
+| oauth2_provider     | workos                   | OAuth2 provider (e.g., workos, okta, auth0)                 |
+| oauth2_audience     | client_01YYY             | Audience identifying the target API/resource                |
+| oauth2_client_id    | client_01XXX             | OAuth2 client ID issued by the provider                     |
+| oauth2_domain       | login.crewai.com         | Provider domain (e.g., your-org.auth0.com)                  |
 
 Set the enterprise base URL:
 ```shell Terminal
@@ -385,6 +400,10 @@ Reset all configuration to defaults:
 crewai config reset
 ```
 
+<Tip>
+After resetting configuration, re-run `crewai login` to authenticate again.
+</Tip>
+
 <Note>
 Configuration settings are stored in `~/.config/crewai/settings.json`. Some settings like organization name and UUID are read-only and managed through authentication and organization commands. Tool repository related settings are hidden and cannot be set directly by users.
 </Note>

docs/en/concepts/collaboration.mdx

@@ -2,6 +2,7 @@
 title: Collaboration
 description: How to enable agents to work together, delegate tasks, and communicate effectively within CrewAI teams.
 icon: screen-users
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/crews.mdx

@@ -2,6 +2,7 @@
 title: Crews
 description: Understanding and utilizing crews in the crewAI framework with comprehensive attributes and functionalities.
 icon: people-group
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/event-listener.mdx

@@ -2,6 +2,7 @@
 title: 'Event Listeners'
 description: 'Tap into CrewAI events to build custom integrations and monitoring'
 icon: spinner
+mode: "wide"
 ---
 
 ## Overview
@@ -44,12 +45,12 @@ To create a custom event listener, you need to:
 Here's a simple example of a custom event listener class:
 
 ```python
-from crewai.utilities.events import (
+from crewai.events import (
     CrewKickoffStartedEvent,
     CrewKickoffCompletedEvent,
     AgentExecutionCompletedEvent,
 )
-from crewai.utilities.events.base_event_listener import BaseEventListener
+from crewai.events import BaseEventListener
 
 class MyCustomListener(BaseEventListener):
     def __init__(self):
@@ -146,7 +147,7 @@ my_project/
 
 ```python
 # my_custom_listener.py
-from crewai.utilities.events.base_event_listener import BaseEventListener
+from crewai.events import BaseEventListener
 # ... import events ...
 
 class MyCustomListener(BaseEventListener):
@@ -279,7 +280,7 @@ Additional fields vary by event type. For example, `CrewKickoffCompletedEvent` i
 For temporary event handling (useful for testing or specific operations), you can use the `scoped_handlers` context manager:
 
 ```python
-from crewai.utilities.events import crewai_event_bus, CrewKickoffStartedEvent
+from crewai.events import crewai_event_bus, CrewKickoffStartedEvent
 
 with crewai_event_bus.scoped_handlers():
     @crewai_event_bus.on(CrewKickoffStartedEvent)

docs/en/concepts/flows.mdx

@@ -2,6 +2,7 @@
 title: Flows
 description: Learn how to create and manage AI workflows using CrewAI Flows.
 icon: arrow-progress
+mode: "wide"
 ---
 
 ## Overview
@@ -97,7 +98,13 @@ The state's unique ID and stored data can be useful for tracking flow executions
 
 ### @start()
 
-The `@start()` decorator is used to mark a method as the starting point of a Flow. When a Flow is started, all the methods decorated with `@start()` are executed in parallel. You can have multiple start methods in a Flow, and they will all be executed when the Flow is started.
+The `@start()` decorator marks entry points for a Flow. You can:
+
+- Declare multiple unconditional starts: `@start()`
+- Gate a start on a prior method or router label: `@start("method_or_label")`
+- Provide a callable condition to control when a start should fire
+
+All satisfied `@start()` methods will execute (often in parallel) when the Flow begins or resumes.
 
 ### @listen()
 

docs/en/concepts/knowledge.mdx

@@ -2,6 +2,7 @@
 title: Knowledge
 description: What is knowledge in CrewAI and how to use it.
 icon: book
+mode: "wide"
 ---
 
 ## Overview
@@ -24,6 +25,41 @@ For file-based Knowledge Sources, make sure to place your files in a `knowledge`
 Also, use relative paths from the `knowledge` directory when creating the source.
 </Tip>
 
+### Vector store (RAG) client configuration
+
+CrewAI exposes a provider-neutral RAG client abstraction for vector stores. The default provider is ChromaDB, and Qdrant is supported as well. You can switch providers using configuration utilities.
+
+Supported today:
+- ChromaDB (default)
+- Qdrant
+
+```python Code
+from crewai.rag.config.utils import set_rag_config, get_rag_client, clear_rag_config
+
+# ChromaDB (default)
+from crewai.rag.chromadb.config import ChromaDBConfig
+set_rag_config(ChromaDBConfig())
+chromadb_client = get_rag_client()
+
+# Qdrant
+from crewai.rag.qdrant.config import QdrantConfig
+set_rag_config(QdrantConfig())
+qdrant_client = get_rag_client()
+
+# Example operations (same API for any provider)
+client = qdrant_client  # or chromadb_client
+client.create_collection(collection_name="docs")
+client.add_documents(
+    collection_name="docs",
+    documents=[{"id": "1", "content": "CrewAI enables collaborative AI agents."}],
+)
+results = client.search(collection_name="docs", query="collaborative agents", limit=3)
+
+clear_rag_config()  # optional reset
+```
+
+This RAG client is separate from Knowledge’s built-in storage. Use it when you need direct vector-store control or custom retrieval pipelines.
+
 ### Basic String Knowledge Example
 
 ```python Code
@@ -681,11 +717,11 @@ CrewAI emits events during the knowledge retrieval process that you can listen f
 #### Example: Monitoring Knowledge Retrieval
 
 ```python
-from crewai.utilities.events import (
+from crewai.events import (
     KnowledgeRetrievalStartedEvent,
     KnowledgeRetrievalCompletedEvent,
+    BaseEventListener,
 )
-from crewai.utilities.events.base_event_listener import BaseEventListener
 
 class KnowledgeMonitorListener(BaseEventListener):
     def setup_listeners(self, crewai_event_bus):

docs/en/concepts/llms.mdx

@@ -2,6 +2,7 @@
 title: 'LLMs'
 description: 'A comprehensive guide to configuring and using Large Language Models (LLMs) in your CrewAI projects'
 icon: 'microchip-ai'
+mode: "wide"
 ---
 
 ## Overview
@@ -733,10 +734,10 @@ CrewAI supports streaming responses from LLMs, allowing your application to rece
     CrewAI emits events for each chunk received during streaming:
 
     ```python
-    from crewai.utilities.events import (
+    from crewai.events import (
       LLMStreamChunkEvent
     )
-    from crewai.utilities.events.base_event_listener import BaseEventListener
+    from crewai.events import BaseEventListener
 
     class MyCustomListener(BaseEventListener):
         def setup_listeners(self, crewai_event_bus):
@@ -758,8 +759,8 @@ CrewAI supports streaming responses from LLMs, allowing your application to rece
 
     ```python
     from crewai import LLM, Agent, Task, Crew
-    from crewai.utilities.events import LLMStreamChunkEvent
-    from crewai.utilities.events.base_event_listener import BaseEventListener
+    from crewai.events import LLMStreamChunkEvent
+    from crewai.events import BaseEventListener
 
     class MyCustomListener(BaseEventListener):
         def setup_listeners(self, crewai_event_bus):

docs/en/concepts/memory.mdx

@@ -2,11 +2,12 @@
 title: Memory
 description: Leveraging memory systems in the CrewAI framework to enhance agent capabilities.
 icon: database
+mode: "wide"
 ---
 
 ## Overview
 
-The CrewAI framework provides a sophisticated memory system designed to significantly enhance AI agent capabilities. CrewAI offers **three distinct memory approaches** that serve different use cases:
+The CrewAI framework provides a sophisticated memory system designed to significantly enhance AI agent capabilities. CrewAI offers **two distinct memory approaches** that serve different use cases:
 
 1. **Basic Memory System** - Built-in short-term, long-term, and entity memory
 2. **External Memory** - Standalone external memory providers
@@ -738,6 +739,17 @@ print(f"OpenAI: {openai_time:.2f}s")
 print(f"Ollama: {ollama_time:.2f}s")
 ```
 
+### Entity Memory batching behavior
+
+Entity Memory supports batching when saving multiple entities at once. When you pass a list of `EntityMemoryItem`, the system:
+
+- Emits a single MemorySaveStartedEvent with `entity_count`
+- Saves each entity internally, collecting any partial errors
+- Emits MemorySaveCompletedEvent with aggregate metadata (saved count, errors)
+- Raises a partial-save exception if some entities failed (includes counts)
+
+This improves performance and observability when writing many entities in one operation.
+
 ## 2. External Memory 
 External Memory provides a standalone memory system that operates independently from the crew's built-in memory. This is ideal for specialized memory providers or cross-application memory sharing.
 
@@ -1041,8 +1053,8 @@ CrewAI emits the following memory-related events:
 Track memory operation timing to optimize your application:
 
 ```python
-from crewai.utilities.events.base_event_listener import BaseEventListener
-from crewai.utilities.events import (
+from crewai.events import (
+    BaseEventListener,
     MemoryQueryCompletedEvent,
     MemorySaveCompletedEvent
 )
@@ -1076,8 +1088,8 @@ memory_monitor = MemoryPerformanceMonitor()
 Log memory operations for debugging and insights:
 
 ```python
-from crewai.utilities.events.base_event_listener import BaseEventListener
-from crewai.utilities.events import (
+from crewai.events import (
+    BaseEventListener,
     MemorySaveStartedEvent,
     MemoryQueryStartedEvent,
     MemoryRetrievalCompletedEvent
@@ -1117,8 +1129,8 @@ memory_logger = MemoryLogger()
 Capture and respond to memory errors:
 
 ```python
-from crewai.utilities.events.base_event_listener import BaseEventListener
-from crewai.utilities.events import (
+from crewai.events import (
+    BaseEventListener,
     MemorySaveFailedEvent,
     MemoryQueryFailedEvent
 )
@@ -1167,8 +1179,8 @@ error_tracker = MemoryErrorTracker(notify_email="admin@example.com")
 Memory events can be forwarded to analytics and monitoring platforms to track performance metrics, detect anomalies, and visualize memory usage patterns:
 
 ```python
-from crewai.utilities.events.base_event_listener import BaseEventListener
-from crewai.utilities.events import (
+from crewai.events import (
+    BaseEventListener,
     MemoryQueryCompletedEvent,
     MemorySaveCompletedEvent
 )

docs/en/concepts/planning.mdx

@@ -2,6 +2,7 @@
 title: Planning
 description: Learn how to add planning to your CrewAI Crew and improve their performance.
 icon: ruler-combined
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/processes.mdx

@@ -2,6 +2,7 @@
 title: Processes
 description: Detailed guide on workflow management through processes in CrewAI, with updated implementation details.
 icon: bars-staggered
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/reasoning.mdx

@@ -2,6 +2,7 @@
 title: Reasoning
 description: "Learn how to enable and use agent reasoning to improve task execution."
 icon: brain
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/tasks.mdx

@@ -2,6 +2,7 @@
 title: Tasks
 description: Detailed guide on managing and creating tasks within the CrewAI framework.
 icon: list-check
+mode: "wide"
 ---
 
 ## Overview
@@ -61,6 +62,11 @@ crew = Crew(
 | **Guardrail** _(optional)_       | `guardrail`       | `Optional[Callable]`             | Function 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">
+  The task attribute `max_retries` is deprecated and will be removed in v1.0.0.
+  Use `guardrail_max_retries` instead to control retry attempts when a guardrail fails.
+</Note>
+
 ## Creating Tasks
 
 There are two ways to create tasks in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
@@ -432,7 +438,7 @@ When a guardrail returns `(False, error)`:
 2. The agent attempts to fix the issue
 3. The process repeats until:
    - The guardrail returns `(True, result)`
-   - Maximum retries are reached
+   - Maximum retries are reached (`guardrail_max_retries`)
 
 Example with retry handling:
 ```python Code

docs/en/concepts/testing.mdx

@@ -2,6 +2,7 @@
 title: Testing
 description: Learn how to test your CrewAI Crew and evaluate their performance.
 icon: vial
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/tools.mdx

@@ -2,6 +2,7 @@
 title: Tools
 description: Understanding and leveraging tools within the CrewAI framework for agent collaboration and task execution.
 icon: screwdriver-wrench
+mode: "wide"
 ---
 
 ## Overview

docs/en/concepts/training.mdx

@@ -2,6 +2,7 @@
 title: Training
 description: Learn how to train your CrewAI agents by giving them feedback early on and get consistent results.
 icon: dumbbell
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/features/agent-repositories.mdx

@@ -2,6 +2,7 @@
 title: 'Agent Repositories'
 description: 'Learn how to use Agent Repositories to share and reuse your agents across teams and projects'
 icon: 'database'
+mode: "wide"
 ---
 
 Agent Repositories allow enterprise users to store, share, and reuse agent definitions across teams and projects. This feature enables organizations to maintain a centralized library of standardized agents, promoting consistency and reducing duplication of effort.

docs/en/enterprise/features/hallucination-guardrail.mdx

@@ -2,6 +2,7 @@
 title: Hallucination Guardrail
 description: "Prevent and detect AI hallucinations in your CrewAI tasks"
 icon: "shield-check"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/features/integrations.mdx

@@ -2,6 +2,7 @@
 title: Integrations
 description: "Connected applications for your agents to take actions."
 icon: "plug"
+mode: "wide"
 ---
 
 ## Overview
@@ -59,7 +60,7 @@ Before using Authentication Integrations, ensure you have:
 3. Click **Connect** on your desired service from the Authentication Integrations section
 4. Complete the OAuth authentication flow
 5. Grant necessary permissions for your use case
-6. Get your Enterprise Token from your [CrewAI Enterprise](https://app.crewai.com) account page - https://app.crewai.com/crewai_plus/settings/account
+6. All set! Get your Enterprise Token from your [CrewAI Enterprise](https://app.crewai.com) in **Integration** tab
 
 <Frame>
   ![Integrations](/images/enterprise/enterprise_action_auth_token.png)

docs/en/enterprise/features/rbac.mdx

@@ -2,6 +2,7 @@
 title: "Role-Based Access Control (RBAC)"
 description: "Control access to crews, tools, and data with roles, scopes, and granular permissions."
 icon: "shield"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/features/tool-repository.mdx

@@ -2,6 +2,7 @@
 title: Tool Repository
 description: "Using the Tool Repository to manage your tools"
 icon: "toolbox"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/features/traces.mdx

@@ -2,6 +2,7 @@
 title: Traces
 description: "Using Traces to monitor your Crews"
 icon: "timeline"
+mode: "wide"
 ---
 
 ## Overview
@@ -141,6 +142,16 @@ Traces are invaluable for troubleshooting issues with your crews:
   </Step>
 </Steps>
 
+## Performance and batching
+
+CrewAI batches trace uploads to reduce overhead on high-volume runs:
+
+- A TraceBatchManager buffers events and sends them in batches via the Plus API client
+- Reduces network chatter and improves reliability on flaky connections
+- Automatically enabled in the default trace listener; no configuration needed
+
+This yields more stable tracing under load while preserving detailed task/agent telemetry.
+
 <Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
   Contact our support team for assistance with trace analysis or any other CrewAI Enterprise features.
 </Card>

docs/en/enterprise/features/webhook-streaming.mdx

@@ -2,6 +2,7 @@
 title: Webhook Streaming
 description: "Using Webhook Streaming to stream events to your webhook"
 icon: "webhook"
+mode: "wide"
 ---
 
 ## Overview
@@ -62,16 +63,96 @@ As requests are sent over HTTP, the order of events can't be guaranteed. If you
 
 CrewAI supports both system events and custom events in Enterprise Event Streaming. These events are sent to your configured webhook endpoint during crew and flow execution.
 
-- `crew_kickoff_started`
-- `crew_step_started`
-- `crew_step_completed`
-- `crew_execution_completed`
-- `llm_call_started`
-- `llm_call_completed`
-- `tool_usage_started`
-- `tool_usage_completed`
-- `crew_test_failed`
-- *...and others*
+### Flow Events:
+
+  - flow_created
+  - flow_started
+  - flow_finished
+  - flow_plot
+  - method_execution_started
+  - method_execution_finished
+  - method_execution_failed
+
+### Agent Events:
+
+  - agent_execution_started
+  - agent_execution_completed
+  - agent_execution_error
+  - lite_agent_execution_started
+  - lite_agent_execution_completed
+  - lite_agent_execution_error
+  - agent_logs_started
+  - agent_logs_execution
+  - agent_evaluation_started
+  - agent_evaluation_completed
+  - agent_evaluation_failed
+
+### Crew Events:
+
+  - crew_kickoff_started
+  - crew_kickoff_completed
+  - crew_kickoff_failed
+  - crew_train_started
+  - crew_train_completed
+  - crew_train_failed
+  - crew_test_started
+  - crew_test_completed
+  - crew_test_failed
+  - crew_test_result
+
+### Task Events:
+
+  - task_started
+  - task_completed
+  - task_failed
+  - task_evaluation
+
+### Tool Usage Events:
+
+  - tool_usage_started
+  - tool_usage_finished
+  - tool_usage_error
+  - tool_validate_input_error
+  - tool_selection_error
+  - tool_execution_error
+
+### LLM Events:
+
+  - llm_call_started
+  - llm_call_completed
+  - llm_call_failed
+  - llm_stream_chunk
+
+### LLM Guardrail Events:
+
+  - llm_guardrail_started
+  - llm_guardrail_completed
+
+### Memory Events:
+
+  - memory_query_started
+  - memory_query_completed
+  - memory_query_failed
+  - memory_save_started
+  - memory_save_completed
+  - memory_save_failed
+  - memory_retrieval_started
+  - memory_retrieval_completed
+
+### Knowledge Events:
+
+  - knowledge_search_query_started
+  - knowledge_search_query_completed
+  - knowledge_search_query_failed
+  - knowledge_query_started
+  - knowledge_query_completed
+  - knowledge_query_failed
+
+### Reasoning Events:
+
+  - agent_reasoning_started
+  - agent_reasoning_completed
+  - agent_reasoning_failed
 
 Event names match the internal event bus. See [GitHub source](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) for the full list.
 

docs/en/enterprise/guides/automation-triggers.mdx

@@ -2,6 +2,7 @@
 title: "Automation Triggers"
 description: "Automatically execute your CrewAI workflows when specific events occur in connected integrations"
 icon: "bolt"
+mode: "wide"
 ---
 
 Automation triggers enable you to automatically run your CrewAI deployments when specific events occur in your connected integrations, creating powerful event-driven workflows that respond to real-time changes in your business systems.
@@ -96,6 +97,13 @@ class MyAutomatedCrew:
 
 The crew will automatically receive and can access the trigger payload through the standard CrewAI context mechanisms.
 
+<Note>
+  Crew and Flow inputs can include `crewai_trigger_payload`. CrewAI automatically injects this payload:
+  - Tasks: appended to the first task's description by default ("Trigger Payload: {crewai_trigger_payload}")
+  - Control via `allow_crewai_trigger_context`: set `True` to always inject, `False` to never inject
+  - Flows: any `@start()` method that accepts a `crewai_trigger_payload` parameter will receive it
+</Note>
+
 ### Integration with Flows
 
 For flows, you have more control over how trigger data is handled:

docs/en/enterprise/guides/azure-openai-setup.mdx

@@ -2,6 +2,7 @@
 title: "Azure OpenAI Setup"
 description: "Configure Azure OpenAI with Crew Studio for enterprise LLM connections"
 icon: "microsoft"
+mode: "wide"
 ---
 
 This guide walks you through connecting Azure OpenAI with Crew Studio for seamless enterprise AI operations.
@@ -9,12 +10,12 @@ This guide walks you through connecting Azure OpenAI with Crew Studio for seamle
 ## Setup Process
 
 <Steps>
-    <Step title="Access Azure OpenAI Studio">
-        1. In Azure, go to `Azure AI Services > select your deployment > open Azure OpenAI Studio`.
+    <Step title="Access Azure AI Foundry">
+        1. In Azure, go to [Azure AI Foundry](https://ai.azure.com/) > select your Azure OpenAI deployment.
         2. On the left menu, click `Deployments`. If you don't have one, create a deployment with your desired model.
         3. Once created, select your deployment and locate the `Target URI` and `Key` on the right side of the page. Keep this page open, as you'll need this information.
             <Frame>
-                <img src="/images/enterprise/azure-openai-studio.png" alt="Azure OpenAI Studio" />
+                <img src="/images/enterprise/azure-openai-studio.png" alt="Azure AI Foundry" />
             </Frame>
     </Step>
 
@@ -48,4 +49,4 @@ If you encounter issues:
 - Verify the Target URI format matches the expected pattern
 - Check that the API key is correct and has proper permissions
 - Ensure network access is configured to allow CrewAI connections
-- Confirm the deployment model matches what you've configured in CrewAI 
+- Confirm the deployment model matches what you've configured in CrewAI 

docs/en/enterprise/guides/build-crew.mdx

@@ -2,6 +2,7 @@
 title: "Build Crew"
 description: "A Crew is a group of agents that work together to complete a task."
 icon: "people-arrows"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/guides/deploy-crew.mdx

@@ -2,6 +2,7 @@
 title: "Deploy Crew"
 description: "Deploying a Crew on CrewAI Enterprise"
 icon: "rocket"
+mode: "wide"
 ---
 
 <Note>

docs/en/enterprise/guides/enable-crew-studio.mdx

@@ -2,6 +2,7 @@
 title: "Enable Crew Studio"
 description: "Enabling Crew Studio on CrewAI Enterprise"
 icon: "comments"
+mode: "wide"
 ---
 
 <Tip>

docs/en/enterprise/guides/hubspot-trigger.mdx

@@ -2,6 +2,7 @@
 title: "HubSpot Trigger"
 description: "Trigger CrewAI crews directly from HubSpot Workflows"
 icon: "hubspot"
+mode: "wide"
 ---
 
 This guide provides a step-by-step process to set up HubSpot triggers for CrewAI Enterprise, enabling you to initiate crews directly from HubSpot Workflows.

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

@@ -2,6 +2,7 @@
 title: "HITL Workflows"
 description: "Learn how to implement Human-In-The-Loop workflows in CrewAI for enhanced decision-making"
 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.

docs/en/enterprise/guides/kickoff-crew.mdx

@@ -2,6 +2,7 @@
 title: "Kickoff Crew"
 description: "Kickoff a Crew on CrewAI Enterprise"
 icon: "flag-checkered"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/guides/react-component-export.mdx

@@ -2,6 +2,7 @@
 title: "React Component Export"
 description: "Learn how to export and integrate CrewAI Enterprise React components into your applications"
 icon: "react"
+mode: "wide"
 ---
 
 This guide explains how to export CrewAI Enterprise crews as React components and integrate them into your own applications.

docs/en/enterprise/guides/salesforce-trigger.mdx

@@ -2,6 +2,7 @@
 title: "Salesforce Trigger"
 description: "Trigger CrewAI crews from Salesforce workflows for CRM automation"
 icon: "salesforce"
+mode: "wide"
 ---
 
 CrewAI Enterprise can be triggered from Salesforce to automate customer relationship management workflows and enhance your sales operations.

docs/en/enterprise/guides/slack-trigger.mdx

@@ -2,6 +2,7 @@
 title: "Slack Trigger"
 description: "Trigger CrewAI crews directly from Slack using slash commands"
 icon: "slack"
+mode: "wide"
 ---
 
 This guide explains how to start a crew directly from Slack using CrewAI triggers.

docs/en/enterprise/guides/team-management.mdx

@@ -2,6 +2,7 @@
 title: "Team Management"
 description: "Learn how to invite and manage team members in your CrewAI Enterprise organization"
 icon: "users"
+mode: "wide"
 ---
 
 As an administrator of a CrewAI Enterprise account, you can easily invite new team members to join your organization. This guide will walk you through the process step-by-step.

docs/en/enterprise/guides/update-crew.mdx

@@ -2,6 +2,7 @@
 title: "Update Crew"
 description: "Updating a Crew on CrewAI Enterprise"
 icon: "pencil"
+mode: "wide"
 ---
 
 <Note>

docs/en/enterprise/guides/webhook-automation.mdx

@@ -2,6 +2,7 @@
 title: "Webhook Automation"
 description: "Automate CrewAI Enterprise workflows using webhooks with platforms like ActivePieces, Zapier, and Make.com"
 icon: "webhook"
+mode: "wide"
 ---
 
 CrewAI Enterprise allows you to automate your workflow using webhooks. This article will guide you through the process of setting up and using webhooks to kickoff your crew execution, with a focus on integration with ActivePieces, a workflow automation platform similar to Zapier and Make.com.
@@ -79,14 +80,24 @@ CrewAI Enterprise allows you to automate your workflow using webhooks. This arti
 
 ## Webhook Output Examples
 
+**Note:** Any `meta` object provided in your kickoff request will be included in all webhook payloads, allowing you to track requests and maintain context across the entire crew execution lifecycle.
+
 <Tabs>
     <Tab title="Step Webhook">
         `stepWebhookUrl` - Callback that will be executed upon each agent inner thought
 
         ```json
         {
-            "action": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
-            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
+            "prompt": "Research the financial industry for potential AI solutions",
+            "thought": "I need to conduct preliminary research on the financial industry",
+            "tool": "research_tool",
+            "tool_input": "financial industry AI solutions",
+            "result": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
+            "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
+            "meta": {
+                "requestId": "travel-req-123",
+                "source": "web-app"
+            }
         }
         ```
     </Tab>
@@ -95,8 +106,21 @@ CrewAI Enterprise allows you to automate your workflow using webhooks. This arti
 
         ```json
         {
-            "description": "Using the information gathered from the lead's data, conduct preliminary research on the lead's industry, company background, and potential use cases for crewai. Focus on finding relevant data that can aid in scoring the lead and planning a strategy to pitch them crewai.The financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
-            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0"
+            "description": "Using the information gathered from the lead's data, conduct preliminary research on the lead's industry, company background, and potential use cases for crewai. Focus on finding relevant data that can aid in scoring the lead and planning a strategy to pitch them crewai.",
+            "name": "Industry Research Task",
+            "expected_output": "Detailed research report on the financial industry",
+            "summary": "The financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.",
+            "agent": "Research Agent",
+            "output": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance.",
+            "output_json": {
+                "industry": "financial",
+                "key_opportunities": ["digital customer engagement", "risk management", "regulatory compliance"]
+            },
+            "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
+            "meta": {
+                "requestId": "travel-req-123",
+                "source": "web-app"
+            }
         }
         ```
     </Tab>
@@ -105,8 +129,9 @@ CrewAI Enterprise allows you to automate your workflow using webhooks. This arti
 
         ```json
         {
-            "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
-            "result": {
+            "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0",
+            "result": "**Final Analysis Report**\n\nLead Score: Customer service enhancement and compliance are particularly relevant.\n\nTalking Points:\n- Highlight how crewai's AI solutions can transform customer service\n- Discuss crewai's potential for sustainability goals\n- Emphasize compliance capabilities\n- Stress adaptability for various operation scales",
+            "result_json": {
                 "lead_score": "Customer service enhancement, and compliance are particularly relevant.",
                 "talking_points": [
                     "Highlight how crewai's AI solutions can transform customer service with automated, personalized experiences and 24/7 support, improving both customer satisfaction and operational efficiency.",
@@ -114,6 +139,15 @@ CrewAI Enterprise allows you to automate your workflow using webhooks. This arti
                     "Emphasize crewai's ability to enhance compliance with evolving regulations through efficient data processing and reporting, reducing the risk of non-compliance penalties.",
                     "Stress the adaptability of crewai to support both extensive multinational operations and smaller, targeted projects, ensuring the solution grows with the institution's needs."
                 ]
+            },
+            "token_usage": {
+                "total_tokens": 1250,
+                "prompt_tokens": 800,
+                "completion_tokens": 450
+            },
+            "meta": {
+                "requestId": "travel-req-123",
+                "source": "web-app"
             }
         }
         ```

docs/en/enterprise/guides/zapier-trigger.mdx

@@ -2,6 +2,7 @@
 title: "Zapier Trigger"
 description: "Trigger CrewAI crews from Zapier workflows to automate cross-app workflows"
 icon: "bolt"
+mode: "wide"
 ---
 
 This guide will walk you through the process of setting up Zapier triggers for CrewAI Enterprise, allowing you to automate workflows between CrewAI Enterprise and other applications.

docs/en/enterprise/integrations/asana.mdx

@@ -2,6 +2,7 @@
 title: Asana Integration
 description: "Team task and project coordination with Asana integration for CrewAI."
 icon: "circle"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/box.mdx

@@ -2,6 +2,7 @@
 title: Box Integration
 description: "File storage and document management with Box integration for CrewAI."
 icon: "box"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/clickup.mdx

@@ -2,6 +2,7 @@
 title: ClickUp Integration
 description: "Task and productivity management with ClickUp integration for CrewAI."
 icon: "list-check"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/github.mdx

@@ -2,6 +2,7 @@
 title: GitHub Integration
 description: "Repository and issue management with GitHub integration for CrewAI."
 icon: "github"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/gmail.mdx

@@ -2,6 +2,7 @@
 title: Gmail Integration
 description: "Email and contact management with Gmail integration for CrewAI."
 icon: "envelope"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/google_calendar.mdx

@@ -2,6 +2,7 @@
 title: Google Calendar Integration
 description: "Event and schedule management with Google Calendar integration for CrewAI."
 icon: "calendar"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/google_sheets.mdx

@@ -2,6 +2,7 @@
 title: Google Sheets Integration
 description: "Spreadsheet data synchronization with Google Sheets integration for CrewAI."
 icon: "google"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/hubspot.mdx

@@ -2,6 +2,7 @@
 title: "HubSpot Integration"
 description: "Manage companies and contacts in HubSpot with CrewAI."
 icon: "briefcase"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/jira.mdx

@@ -2,6 +2,7 @@
 title: Jira Integration
 description: "Issue tracking and project management with Jira integration for CrewAI."
 icon: "bug"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/linear.mdx

@@ -2,6 +2,7 @@
 title: Linear Integration
 description: "Software project and bug tracking with Linear integration for CrewAI."
 icon: "list-check"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/notion.mdx

@@ -2,6 +2,7 @@
 title: Notion Integration
 description: "Page and database management with Notion integration for CrewAI."
 icon: "book"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/salesforce.mdx

@@ -2,6 +2,7 @@
 title: Salesforce Integration
 description: "CRM and sales automation with Salesforce integration for CrewAI."
 icon: "salesforce"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/shopify.mdx

@@ -2,6 +2,7 @@
 title: Shopify Integration
 description: "E-commerce and online store management with Shopify integration for CrewAI."
 icon: "shopify"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/slack.mdx

@@ -2,6 +2,7 @@
 title: Slack Integration
 description: "Team communication and collaboration with Slack integration for CrewAI."
 icon: "slack"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/stripe.mdx

@@ -2,6 +2,7 @@
 title: Stripe Integration
 description: "Payment processing and subscription management with Stripe integration for CrewAI."
 icon: "stripe"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/integrations/zendesk.mdx

@@ -2,6 +2,7 @@
 title: Zendesk Integration
 description: "Customer support and helpdesk management with Zendesk integration for CrewAI."
 icon: "headset"
+mode: "wide"
 ---
 
 ## Overview

docs/en/enterprise/introduction.mdx

@@ -2,6 +2,7 @@
 title: "CrewAI Enterprise"
 description: "Deploy, monitor, and scale your AI agent workflows"
 icon: "globe"
+mode: "wide"
 ---
 
 ## Introduction

docs/en/enterprise/resources/frequently-asked-questions.mdx

@@ -2,6 +2,7 @@
 title: FAQs
 description: "Frequently asked questions about CrewAI Enterprise"
 icon: "circle-question"
+mode: "wide"
 ---
 
 <AccordionGroup>

docs/en/examples/cookbooks.mdx

@@ -2,6 +2,7 @@
 title: CrewAI Cookbooks
 description: Feature-focused quickstarts and notebooks for learning patterns fast.
 icon: book
+mode: "wide"
 ---
 
 ## Quickstarts & Demos

docs/en/examples/example.mdx

@@ -2,6 +2,7 @@
 title: CrewAI Examples
 description: Explore curated examples organized by Crews, Flows, Integrations, and Notebooks.
 icon: rocket-launch
+mode: "wide"
 ---
 
 ## Crews

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

@@ -2,6 +2,7 @@
 title: Customizing Prompts
 description: Dive deeper into low-level prompt customization for CrewAI, enabling super custom and complex use cases for different models and languages.
 icon: message-pen
+mode: "wide"
 ---
 
 ## Why Customize Prompts?

docs/en/guides/advanced/fingerprinting.mdx

@@ -2,6 +2,7 @@
 title: Fingerprinting
 description: Learn how to use CrewAI's fingerprinting system to uniquely identify and track components throughout their lifecycle.
 icon: fingerprint
+mode: "wide"
 ---
 
 ## Overview

docs/en/guides/agents/crafting-effective-agents.mdx

@@ -2,6 +2,7 @@
 title: Crafting Effective Agents
 description: Learn best practices for designing powerful, specialized AI agents that collaborate effectively to solve complex problems.
 icon: robot
+mode: "wide"
 ---
 
 ## The Art and Science of Agent Design

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

@@ -2,6 +2,7 @@
 title: Evaluating Use Cases for CrewAI
 description: Learn how to assess your AI application needs and choose the right approach between Crews and Flows based on complexity and precision requirements.
 icon: scale-balanced
+mode: "wide"
 ---
 
 ## Understanding the Decision Framework

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

@@ -2,6 +2,7 @@
 title: Build Your First Crew
 description: Step-by-step tutorial to create a collaborative AI team that works together to solve complex problems.
 icon: users-gear
+mode: "wide"
 ---
 
 ## Unleashing the Power of Collaborative AI

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

@@ -2,6 +2,7 @@
 title: Build Your First Flow
 description: Learn how to create structured, event-driven workflows with precise control over execution.
 icon: diagram-project
+mode: "wide"
 ---
 
 ## Taking Control of AI Workflows with Flows

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

@@ -2,6 +2,7 @@
 title: Mastering Flow State Management
 description: A comprehensive guide to managing, persisting, and leveraging state in CrewAI Flows for building robust AI applications.
 icon: diagram-project
+mode: "wide"
 ---
 
 ## Understanding the Power of State in Flows
@@ -348,6 +349,31 @@ class SelectivePersistFlow(Flow):
 
 ## Advanced State Patterns
 
+### Conditional starts and resumable execution
+
+Flows support conditional `@start()` and resumable execution for HITL/cyclic scenarios:
+
+```python
+from crewai.flow.flow import Flow, start, listen, and_, or_
+
+class ResumableFlow(Flow):
+    @start()  # unconditional start
+    def init(self):
+        ...
+
+    # Conditional start: run after "init" or external trigger name
+    @start("init")
+    def maybe_begin(self):
+        ...
+
+    @listen(and_(init, maybe_begin))
+    def proceed(self):
+        ...
+```
+
+- Conditional `@start()` accepts a method name, a router label, or a callable condition.
+- During resume, listeners continue from prior checkpoints; cycle/router branches honor resumption flags.
+
 ### State-Based Conditional Logic
 
 You can use state to implement complex conditional logic in your flows:

docs/en/installation.mdx

@@ -2,6 +2,7 @@
 title: Installation
 description: Get started with CrewAI - Install, configure, and build your first AI crew
 icon: wrench
+mode: "wide"
 ---
 
 ## Video Tutorial
@@ -30,6 +31,12 @@ Watch this video tutorial for a step-by-step demonstration of the installation p
   If you need to update Python, visit [python.org/downloads](https://python.org/downloads)
 </Note>
 
+<Note>
+  **OpenAI SDK Requirement**
+
+  CrewAI 0.175.0 requires `openai >= 1.13.3`. If you manage dependencies yourself, ensure your environment satisfies this constraint to avoid import/runtime issues.
+</Note>
+
 CrewAI uses the `uv` as its dependency management and package handling tool. It simplifies project setup and execution, offering a seamless experience.
 
 If you haven't installed `uv` yet, follow **step 1** to quickly get it set up on your system, else you can skip to **step 2**.

docs/en/introduction.mdx

@@ -2,6 +2,7 @@
 title: Introduction
 description: Build AI agent teams that work together to tackle complex tasks
 icon: handshake
+mode: "wide"
 ---
 
 # What is CrewAI?

docs/en/learn/before-and-after-kickoff-hooks.mdx

@@ -1,6 +1,7 @@
 ---
 title: Before and After Kickoff Hooks
 description: Learn how to use before and after kickoff hooks in CrewAI
+mode: "wide"
 ---
 
 CrewAI provides hooks that allow you to execute code before and after a crew's kickoff. These hooks are useful for preprocessing inputs or post-processing results.

docs/en/learn/bring-your-own-agent.mdx

@@ -2,6 +2,7 @@
 title: Bring your own agent
 description: Learn how to bring your own agents that work within a Crew.
 icon: robots
+mode: "wide"
 ---
 
 Interoperability is a core concept in CrewAI. This guide will show you how to bring your own agents that work within a Crew.

docs/en/learn/coding-agents.mdx

@@ -2,6 +2,7 @@
 title: Coding Agents
 description: Learn how to enable your CrewAI Agents to write and execute code, and explore advanced features for enhanced functionality.
 icon: rectangle-code
+mode: "wide"
 ---
 
 ## Introduction

docs/en/learn/conditional-tasks.mdx

@@ -2,6 +2,7 @@
 title: Conditional Tasks
 description: Learn how to use conditional tasks in a crewAI kickoff
 icon: diagram-subtask
+mode: "wide"
 ---
 
 ## Introduction

docs/en/learn/create-custom-tools.mdx

@@ -2,6 +2,7 @@
 title: Create Custom Tools
 description: Comprehensive guide on crafting, using, and managing custom tools within the CrewAI framework, including new functionalities and error handling.
 icon: hammer
+mode: "wide"
 ---
 
 ## Creating and Utilizing Tools in CrewAI

docs/en/learn/custom-llm.mdx

@@ -2,6 +2,7 @@
 title: Custom LLM Implementation
 description: Learn how to create custom LLM implementations in CrewAI.
 icon: code
+mode: "wide"
 ---
 
 ## Overview

docs/en/learn/custom-manager-agent.mdx

@@ -2,6 +2,7 @@
 title: Custom Manager Agent
 description: Learn how to set a custom agent as the manager in CrewAI, providing more control over task management and coordination.
 icon: user-shield
+mode: "wide"
 ---
 
 # Setting a Specific Agent as Manager in CrewAI

docs/en/learn/customizing-agents.mdx

@@ -2,6 +2,7 @@
 title: Customize Agents
 description: A comprehensive guide to tailoring agents for specific roles, tasks, and advanced customizations within the CrewAI framework.
 icon: user-pen
+mode: "wide"
 ---
 
 ## Customizable Attributes

docs/en/learn/dalle-image-generation.mdx

@@ -2,6 +2,7 @@
 title: "Image Generation with DALL-E"
 description: "Learn how to use DALL-E for AI-powered image generation in your CrewAI projects"
 icon: "image"
+mode: "wide"
 ---
 
 CrewAI supports integration with OpenAI's DALL-E, allowing your AI agents to generate images as part of their tasks. This guide will walk you through how to set up and use the DALL-E tool in your CrewAI projects.

docs/en/learn/force-tool-output-as-result.mdx

@@ -2,6 +2,7 @@
 title: Force Tool Output as Result
 description: Learn how to force tool output as the result in an Agent's task in CrewAI.
 icon: wrench-simple
+mode: "wide"
 ---
 
 ## Introduction

docs/en/learn/hierarchical-process.mdx

@@ -2,6 +2,7 @@
 title: Hierarchical Process
 description: A comprehensive guide to understanding and applying the hierarchical process within your CrewAI projects, updated to reflect the latest coding practices and functionalities.
 icon: sitemap
+mode: "wide"
 ---
 
 ## Introduction

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

@@ -2,6 +2,7 @@
 title: "Human-in-the-Loop (HITL) Workflows"
 description: "Learn how to implement Human-in-the-Loop workflows in CrewAI for enhanced decision-making"
 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.

docs/en/learn/human-input-on-execution.mdx

@@ -2,6 +2,7 @@
 title: Human Input on Execution
 description: Integrating CrewAI with human input during execution in complex decision-making processes and leveraging the full capabilities of the agent's attributes and tools.
 icon: user-check
+mode: "wide"
 ---
 
 ## Human input in agent execution

docs/en/learn/kickoff-async.mdx

@@ -2,6 +2,7 @@
 title: Kickoff Crew Asynchronously
 description: Kickoff a Crew Asynchronously
 icon: rocket-launch
+mode: "wide"
 ---
 
 ## Introduction

docs/en/learn/kickoff-for-each.mdx

@@ -2,6 +2,7 @@
 title: Kickoff Crew for Each
 description: Kickoff Crew for Each Item in a List
 icon: at
+mode: "wide"
 ---
 
 ## Introduction

docs/en/learn/llm-connections.mdx

@@ -2,6 +2,7 @@
 title: Connect to any LLM
 description: Comprehensive guide on integrating CrewAI with various Large Language Models (LLMs) using LiteLLM, including supported providers and configuration options.
 icon: brain-circuit
+mode: "wide"
 ---
 
 ## Connect CrewAI to LLMs

docs/en/learn/llm-selection-guide.mdx

@@ -2,6 +2,7 @@
 title: 'Strategic LLM Selection Guide'
 description: 'Strategic framework for choosing the right LLM for your CrewAI AI agents and writing effective task and agent definitions'
 icon: 'brain-circuit'
+mode: "wide"
 ---
 
 ## The CrewAI Approach to LLM Selection