docs: trim SSO page to SaaS focus, Factory details live in replicated-config

Add SSO documentation page covering all supported identity providers
for both SaaS (AMP) and Factory deployments.

Includes:
- Provider overview (WorkOS, Entra ID, Okta, Auth0, Keycloak)
- SaaS vs Factory SSO availability
- Step-by-step setup guides per provider with env vars
- CLI authentication via Device Authorization Grant
- RBAC integration overview
- Troubleshooting common SSO issues
- Complete environment variables reference

Placed in the Manage nav group alongside RBAC.

.github/security.md

@@ -1,50 +1,12 @@
 ## CrewAI Security Policy
 
-We are committed to protecting the confidentiality, integrity, and availability of the CrewAI ecosystem. This policy explains how to report potential vulnerabilities and what you can expect from us when you do.
-
-### Scope
-
-We welcome reports for vulnerabilities that could impact:
-
-- CrewAI-maintained source code and repositories
-- CrewAI-operated infrastructure and services
-- Official CrewAI releases, packages, and distributions
-
-Issues affecting clearly unaffiliated third-party services or user-generated content are out of scope, unless you can demonstrate a direct impact on CrewAI systems or customers.
+We are committed to protecting the confidentiality, integrity, and availability of the
+CrewAI ecosystem.
 
 ### How to Report
 
-- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests, or social media.
-- Email detailed reports to **security@crewai.com** with the subject line `Security Report`.
-- If you need to share large files or sensitive artifacts, mention it in your email and we will coordinate a secure transfer method.
+Please submit reports to **crewai-vdp-ess@submit.bugcrowd.com**
 
-### What to Include
-
-Providing comprehensive information enables us to validate the issue quickly:
-
-- **Vulnerability overview** — a concise description and classification (e.g., RCE, privilege escalation)
-- **Affected components** — repository, branch, tag, or deployed service along with relevant file paths or endpoints
-- **Reproduction steps** — detailed, step-by-step instructions; include logs, screenshots, or screen recordings when helpful
-- **Proof-of-concept** — exploit details or code that demonstrates the impact (if available)
-- **Impact analysis** — severity assessment, potential exploitation scenarios, and any prerequisites or special configurations
-
-### Our Commitment
-
-- **Acknowledgement:** We aim to acknowledge your report within two business days.
-- **Communication:** We will keep you informed about triage results, remediation progress, and planned release timelines.
-- **Resolution:** Confirmed vulnerabilities will be prioritized based on severity and fixed as quickly as possible.
-- **Recognition:** We currently do not run a bug bounty program; any rewards or recognition are issued at CrewAI's discretion.
-
-### Coordinated Disclosure
-
-We ask that you allow us a reasonable window to investigate and remediate confirmed issues before any public disclosure. We will coordinate publication timelines with you whenever possible.
-
-### Safe Harbor
-
-We will not pursue or support legal action against individuals who, in good faith:
-
-- Follow this policy and refrain from violating any applicable laws
-- Avoid privacy violations, data destruction, or service disruption
-- Limit testing to systems in scope and respect rate limits and terms of service
-
-If you are unsure whether your testing is covered, please contact us at **security@crewai.com** before proceeding.
+- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests,
+  or social media
+- Reports submitted via channels other than this Bugcrowd submission email will not be reviewed and will be dismissed

.github/workflows/docs-broken-links.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: "latest"
+          node-version: "22"
 
       - name: Install Mintlify CLI
         run: npm i -g mintlify

docs/ar/changelog.mdx

@@ -4,6 +4,191 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="27 مارس 2026">
+  ## v1.13.0rc1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## ما الذي تغير
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.13.0a2
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 مارس 2026">
+  ## v1.13.0a2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار
+  - تحسين مرونة إصدار المؤسسات وتجربة المستخدم
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار للإصدار v1.13.0a1
+
+  ## المساهمون
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 مارس 2026">
+  ## v1.13.0a1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح الروابط المعطلة في سير العمل الوثائقي عن طريق تثبيت Node على LTS 22
+  - مسح ذاكرة التخزين المؤقت لـ uv للحزم المنشورة حديثًا في الإصدار المؤسسي
+
+  ### الوثائق
+  - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر
+  - تحديث سجل التغييرات والإصدار للإصدار v1.12.2
+
+  ## المساهمون
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.2
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة مرحلة إصدار المؤسسات إلى إصدار أدوات المطورين
+
+  ### إصلاحات الأخطاء
+  - الحفاظ على قيمة إرجاع الطريقة كإخراج تدفق لـ @human_feedback مع emit
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.1
+  - مراجعة سياسة الأمان وتعليمات الإبلاغ
+
+  ## المساهمون
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.1
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة request_id إلى HumanFeedbackRequestedEvent
+  - إضافة Qdrant Edge كخلفية تخزين لنظام الذاكرة
+  - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات
+  - إضافة دعم اللغة العربية إلى سجل التغييرات وأدوات الإصدار
+  - إضافة ترجمة باللغة العربية الفصحى لجميع الوثائق
+  - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر
+  - إضافة مهارات الوكيل
+  - تنفيذ root_scope تلقائيًا لعزل الذاكرة الهيكلية
+  - تنفيذ مزودين متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope)
+
+  ### إصلاحات الأخطاء
+  - إصلاح بيانات اعتماد غير صحيحة لدفع دفعات التتبع (404)
+  - حل العديد من الأخطاء في نظام تدفق HITL
+  - إصلاح حفظ ذاكرة الوكيل
+  - حل جميع أخطاء mypy الصارمة عبر حزمة crewai
+  - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta
+  - إصلاح خطأ القيمة عند عدم دعم الملفات
+  - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق
+  - إصلاح جميع أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات النوع في CI
+  - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6)
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.0
+  - إضافة CONTRIBUTING.md
+  - إضافة دليل لاستخدام CrewAI بدون LiteLLM
+
+  ## المساهمون
+
+  @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @lucasgomide، @nicoferdi96
+
+</Update>
+
+<Update label="25 مارس 2026">
+  ## v1.12.0
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة
+  - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات
+  - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار
+  - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق
+  - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر
+  - تنفيذ مهارات الوكيل
+  - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهرمية
+  - تنفيذ موفري خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope)
+
+  ### إصلاح الأخطاء
+  - إصلاح بيانات الاعتماد السيئة لدفع دفعات التتبع (404)
+  - حل العديد من الأخطاء في نظام تدفق HITL
+  - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI
+  - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools
+  - حل جميع أخطاء mypy عبر حزمة crewai
+  - إصلاح حفظ الذاكرة في الوكيل
+  - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta
+  - رفع خطأ القيمة عند عدم دعم الملفات
+  - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق
+  - استخدام فحص None بدلاً من isinstance للذاكرة في تعلم التغذية الراجعة البشرية
+  - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6)
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.0
+  - إضافة CONTRIBUTING.md
+  - إضافة دليل لاستخدام CrewAI بدون LiteLLM
+
+  ### إعادة الهيكلة
+  - إعادة هيكلة لتجنب تكرار تنفيذ المهام المتزامنة / غير المتزامنة وبدء التشغيل في الوكيل
+  - تبسيط الأنابيب الداخلية من litellm (عد الرموز، ردود النداء، اكتشاف الميزات، الأخطاء)
+
+  ## المساهمون
+
+  @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @nicoferdi96
+
+</Update>
+
+<Update label="26 مارس 2026">
+  ## v1.12.0a3
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح بيانات الاعتماد الخاطئة لدفع دفعات التتبع (404)
+  - حل العديد من الأخطاء في نظام تدفق HITL
+
+  ### الوثائق
+  - تحديث سجل التغييرات والإصدار لـ v1.12.0a2
+
+  ## المساهمون
+
+  @akaKuruma, @greysonlalonde
+
+</Update>
+
 <Update label="25 مارس 2026">
   ## v1.12.0a2
 

docs/en/changelog.mdx

@@ -4,6 +4,191 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Mar 27, 2026">
+  ## v1.13.0rc1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## What's Changed
+
+  ### Documentation
+  - Update changelog and version for v1.13.0a2
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Mar 27, 2026">
+  ## v1.13.0a2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## What's Changed
+
+  ### Features
+  - Auto-update deployment test repo during release
+  - Improve enterprise release resilience and UX
+
+  ### Documentation
+  - Update changelog and version for v1.13.0a1
+
+  ## Contributors
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="Mar 27, 2026">
+  ## v1.13.0a1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix broken links in documentation workflow by pinning Node to LTS 22
+  - Bust the uv cache for freshly published packages in enterprise release
+
+  ### Documentation
+  - Add comprehensive RBAC permissions matrix and deployment guide
+  - Update changelog and version for v1.12.2
+
+  ## Contributors
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.2
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## What's Changed
+
+  ### Features
+  - Add enterprise release phase to devtools release
+
+  ### Bug Fixes
+  - Preserve method return value as flow output for @human_feedback with emit
+
+  ### Documentation
+  - Update changelog and version for v1.12.1
+  - Revise security policy and reporting instructions
+
+  ## Contributors
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.1
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## What's Changed
+
+  ### Features
+  - Add request_id to HumanFeedbackRequestedEvent
+  - Add Qdrant Edge storage backend for memory system
+  - Add docs-check command to analyze changes and generate docs with translations
+  - Add Arabic language support to changelog and release tooling
+  - Add modern standard Arabic translation of all documentation
+  - Add logout command in CLI
+  - Add agent skills
+  - Implement automatic root_scope for hierarchical memory isolation
+  - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Bug Fixes
+  - Fix bad credentials for traces batch push (404)
+  - Resolve multiple bugs in HITL flow system
+  - Fix agent memory saving
+  - Resolve all strict mypy errors across crewai package
+  - Fix use of __router_paths__ for listener+router methods in FlowMeta
+  - Fix value error on no file support
+  - Correct litellm quarantine wording in docs
+  - Fix all mypy errors in crewai-files and add all packages to CI type checks
+  - Pin litellm upper bound to last tested version (1.82.6)
+
+  ### Documentation
+  - Update changelog and version for v1.12.0
+  - Add CONTRIBUTING.md
+  - Add guide for using CrewAI without LiteLLM
+
+  ## Contributors
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="Mar 25, 2026">
+  ## v1.12.0
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## What's Changed
+
+  ### Features
+  - Add Qdrant Edge storage backend for memory system
+  - Add docs-check command to analyze changes and generate docs with translations
+  - Add Arabic language support to changelog and release tooling
+  - Add modern standard Arabic translation of all documentation
+  - Add logout command in CLI
+  - Implement agent skills
+  - Implement automatic root_scope for hierarchical memory isolation
+  - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Bug Fixes
+  - Fix bad credentials for traces batch push (404)
+  - Resolve multiple bugs in HITL flow system
+  - Resolve mypy errors in crewai-files and add all packages to CI type checks
+  - Resolve all strict mypy errors across crewai-tools package
+  - Resolve all mypy errors across crewai package
+  - Fix memory saving in agent
+  - Fix usage of __router_paths__ for listener+router methods in FlowMeta
+  - Raise value error on no file support
+  - Correct litellm quarantine wording in docs
+  - Use None check instead of isinstance for memory in human feedback learn
+  - Pin litellm upper bound to last tested version (1.82.6)
+
+  ### Documentation
+  - Update changelog and version for v1.12.0
+  - Add CONTRIBUTING.md
+  - Add guide for using CrewAI without LiteLLM
+
+  ### Refactoring
+  - Refactor to deduplicate sync/async task execution and kickoff in agent
+  - Simplify internal plumbing from litellm (token counting, callbacks, feature detection, errors)
+
+  ## Contributors
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
+<Update label="Mar 26, 2026">
+  ## v1.12.0a3
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix bad credentials for traces batch push (404) 
+  - Resolve multiple bugs in HITL flow system
+
+  ### Documentation
+  - Update changelog and version for v1.12.0a2
+
+  ## Contributors
+
+  @akaKuruma, @greysonlalonde
+
+</Update>
+
 <Update label="Mar 25, 2026">
   ## v1.12.0a2
 

docs/en/enterprise/features/rbac.mdx

@@ -7,11 +7,13 @@ mode: "wide"
 
 ## Overview
 
-RBAC in CrewAI AMP enables secure, scalable access management through a combination of organization‑level roles and automation‑level visibility controls.
+RBAC in CrewAI AMP enables secure, scalable access management through two layers:
+
+1. **Feature permissions** — control what each role can do across the platform (manage, read, or no access)
+2. **Entity-level permissions** — fine-grained access on individual automations, environment variables, LLM connections, and Git repositories
 
 <Frame>
   <img src="/images/enterprise/users_and_roles.png" alt="RBAC overview in CrewAI AMP" />
-
 </Frame>
 
 ## Users and Roles
@@ -39,6 +41,13 @@ You can configure users and roles in Settings → Roles.
   </Step>
 </Steps>
 
+### Predefined Roles
+
+| Role       | Description                                                                 |
+| :--------- | :-------------------------------------------------------------------------- |
+| **Owner**  | Full access to all features and settings. Cannot be restricted.             |
+| **Member** | Read access to most features, manage access to Studio projects. Cannot modify organization or default settings. |
+
 ### Configuration summary
 
 | Area                  | Where to configure                 | Options                                 |
@@ -46,23 +55,80 @@ You can configure users and roles in Settings → Roles.
 | Users & Roles         | Settings → Roles                   | Predefined: Owner, Member; Custom roles |
 | Automation visibility | Automation → Settings → Visibility | Private; Whitelist users/roles          |
 
-## Automation‑level Access Control
+---
 
-In addition to organization‑wide roles, CrewAI Automations support fine‑grained visibility settings that let you restrict access to specific automations by user or role.
+## Feature Permissions Matrix
 
-This is useful for:
+Every role has a permission level for each feature area. The three levels are:
+
+- **Manage** — full read/write access (create, edit, delete)
+- **Read** — view-only access
+- **No access** — feature is hidden/inaccessible
+
+| Feature                   | Owner   | Member (default) | Description                                                     |
+| :------------------------ | :------ | :--------------- | :-------------------------------------------------------------- |
+| `usage_dashboards`        | Manage  | Read             | View usage metrics and analytics                                |
+| `crews_dashboards`        | Manage  | Read             | View deployment dashboards, access automation details           |
+| `invitations`             | Manage  | Read             | Invite new members to the organization                          |
+| `training_ui`             | Manage  | Read             | Access training/fine-tuning interfaces                          |
+| `tools`                   | Manage  | Read             | Create and manage tools                                         |
+| `agents`                  | Manage  | Read             | Create and manage agents                                        |
+| `environment_variables`   | Manage  | Read             | Create and manage environment variables                         |
+| `llm_connections`         | Manage  | Read             | Configure LLM provider connections                              |
+| `default_settings`        | Manage  | No access        | Modify organization-wide default settings                       |
+| `organization_settings`   | Manage  | No access        | Manage billing, plans, and organization configuration           |
+| `studio_projects`         | Manage  | Manage           | Create and edit projects in Studio                              |
+
+<Tip>
+  When creating a custom role, you can set each feature independently to **Manage**, **Read**, or **No access** to match your team's needs.
+</Tip>
+
+---
+
+## Deploying from GitHub or Zip
+
+One of the most common RBAC questions is: _"What permissions does a team member need to deploy?"_
+
+### Deploy from GitHub
+
+To deploy an automation from a GitHub repository, a user needs:
+
+1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard where deployments are created
+2. **Git repository access** (if entity-level RBAC for Git repositories is enabled): the user's role must be granted access to the specific Git repository via entity-level permissions
+3. **`studio_projects`: `Manage`** — if building the crew in Studio before deploying
+
+### Deploy from Zip
+
+To deploy an automation from a Zip file upload, a user needs:
+
+1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard
+2. **Zip deployments enabled**: the organization must not have disabled zip deployments in organization settings
+
+### Quick Reference: Minimum Permissions for Deployment
+
+| Action               | Required feature permissions          | Additional requirements                          |
+| :------------------- | :------------------------------------ | :----------------------------------------------- |
+| Deploy from GitHub   | `crews_dashboards: Read`              | Git repo entity access (if Git RBAC is enabled)  |
+| Deploy from Zip      | `crews_dashboards: Read`              | Zip deployments must be enabled at the org level |
+| Build in Studio      | `studio_projects: Manage`             | —                                                |
+| Configure LLM keys   | `llm_connections: Manage`             | —                                                |
+| Set environment vars  | `environment_variables: Manage`       | Entity-level access (if entity RBAC is enabled)  |
+
+---
+
+## Automation‑level Access Control (Entity Permissions)
+
+In addition to organization‑wide roles, CrewAI supports fine‑grained entity-level permissions that restrict access to individual resources.
+
+### Automation Visibility
+
+Automations support visibility settings that restrict access by user or role. This is useful for:
 
 - Keeping sensitive or experimental automations private
 - Managing visibility across large teams or external collaborators
 - Testing automations in isolated contexts
 
-Deployments can be configured as private, meaning only whitelisted users and roles will be able to:
-
-- View the deployment
-- Run it or interact with its API
-- Access its logs, metrics, and settings
-
-The organization owner always has access, regardless of visibility settings.
+Deployments can be configured as private, meaning only whitelisted users and roles will be able to interact with them.
 
 You can configure automation‑level access control in Automation → Settings → Visibility tab.
 
@@ -99,9 +165,92 @@ You can configure automation‑level access control in Automation → Settings
 
 <Frame>
   <img src="/images/enterprise/visibility.png" alt="Automation Visibility settings in CrewAI AMP" />
-
 </Frame>
 
+### Deployment Permission Types
+
+When granting entity-level access to a specific automation, you can assign these permission types:
+
+| Permission           | What it allows                                      |
+| :------------------- | :-------------------------------------------------- |
+| `run`                | Execute the automation and use its API               |
+| `traces`             | View execution traces and logs                       |
+| `manage_settings`    | Edit, redeploy, rollback, or delete the automation   |
+| `human_in_the_loop`  | Respond to human-in-the-loop (HITL) requests         |
+| `full_access`        | All of the above                                     |
+
+### Entity-level RBAC for Other Resources
+
+When entity-level RBAC is enabled, access to these resources can also be controlled per user or role:
+
+| Resource               | Controlled by                    | Description                                           |
+| :--------------------- | :------------------------------- | :---------------------------------------------------- |
+| Environment variables  | Entity RBAC feature flag         | Restrict which roles/users can view or manage specific env vars |
+| LLM connections        | Entity RBAC feature flag         | Restrict access to specific LLM provider configurations |
+| Git repositories       | Git repositories RBAC org setting | Restrict which roles/users can access specific connected repos |
+
+---
+
+## Common Role Patterns
+
+While CrewAI ships with Owner and Member roles, most teams benefit from creating custom roles. Here are common patterns:
+
+### Developer Role
+
+A role for team members who build and deploy automations but don't manage organization settings.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Read       |
+| `crews_dashboards`        | Manage     |
+| `invitations`             | Read       |
+| `training_ui`             | Read       |
+| `tools`                   | Manage     |
+| `agents`                  | Manage     |
+| `environment_variables`   | Manage     |
+| `llm_connections`         | Read       |
+| `default_settings`        | No access  |
+| `organization_settings`   | No access  |
+| `studio_projects`         | Manage     |
+
+### Viewer / Stakeholder Role
+
+A role for non-technical stakeholders who need to monitor automations and view results.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Read       |
+| `crews_dashboards`        | Read       |
+| `invitations`             | No access  |
+| `training_ui`             | Read       |
+| `tools`                   | Read       |
+| `agents`                  | Read       |
+| `environment_variables`   | No access  |
+| `llm_connections`         | No access  |
+| `default_settings`        | No access  |
+| `organization_settings`   | No access  |
+| `studio_projects`         | Read       |
+
+### Ops / Platform Admin Role
+
+A role for platform operators who manage infrastructure settings but may not build agents.
+
+| Feature                   | Permission |
+| :------------------------ | :--------- |
+| `usage_dashboards`        | Manage     |
+| `crews_dashboards`        | Manage     |
+| `invitations`             | Manage     |
+| `training_ui`             | Read       |
+| `tools`                   | Read       |
+| `agents`                  | Read       |
+| `environment_variables`   | Manage     |
+| `llm_connections`         | Manage     |
+| `default_settings`        | Manage     |
+| `organization_settings`   | Read       |
+| `studio_projects`         | Read       |
+
+---
+
 <Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
   Contact our support team for assistance with RBAC questions.
 </Card>

docs/en/enterprise/features/sso.mdx

@@ -0,0 +1,194 @@
+---
+title: Single Sign-On (SSO)
+icon: "key"
+description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory
+---
+
+## Overview
+
+CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management.
+
+### Supported Providers
+
+| Provider | SaaS | Factory | Protocol |
+|---|---|---|---|
+| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC |
+| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 |
+| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC |
+| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC |
+| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC |
+
+### Key Capabilities
+
+- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support
+- **Device Authorization Grant** flow for CLI authentication
+- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions
+- **MFA enforcement** delegated to your identity provider
+- **User provisioning** through IdP assignment (users/groups)
+
+---
+
+## SaaS SSO
+
+### Default Authentication
+
+CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required.
+
+### Enterprise Custom SSO
+
+Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured:
+
+1. Your team members authenticate through your organization's IdP
+2. Access control and MFA policies are enforced by your IdP
+3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure`
+
+### CLI Defaults (SaaS)
+
+| Setting | Default Value |
+|---|---|
+| `enterprise_base_url` | `https://app.crewai.com` |
+| `oauth2_provider` | `workos` |
+| `oauth2_domain` | `login.crewai.com` |
+
+---
+
+## Factory SSO
+
+Factory (self-hosted) deployments support SSO with the following identity providers:
+
+- **Microsoft Entra ID** (Azure AD)
+- **Okta**
+- **Keycloak**
+- **Auth0**
+- **WorkOS**
+
+Each provider requires registering an application in your IdP and configuring the corresponding environment variables in your Helm `values.yaml`.
+
+<Note>
+  Detailed setup guides for each provider — including step-by-step IdP registration, environment variable reference, and CLI enablement — are available in your **Factory admin documentation** (shipped with your Factory installation).
+</Note>
+
+---
+
+## CLI Authentication
+
+The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials.
+
+### Quick Setup
+
+For Factory installations, the CLI can auto-configure all OAuth2 settings:
+
+```bash
+crewai enterprise configure https://your-factory-url.app
+```
+
+This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically.
+
+Then authenticate:
+
+```bash
+crewai login
+```
+
+<Note>
+  Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak.
+</Note>
+
+### Manual CLI Configuration
+
+If you need to configure the CLI manually, use `crewai config set`:
+
+```bash
+# Set the provider
+crewai config set oauth2_provider okta
+
+# Set provider-specific values
+crewai config set oauth2_domain your-domain.okta.com
+crewai config set oauth2_client_id your-client-id
+crewai config set oauth2_audience api://default
+
+# Set the enterprise base URL
+crewai config set enterprise_base_url https://your-factory-url.app
+```
+
+### CLI Configuration Reference
+
+| Setting | Description | Example |
+|---|---|---|
+| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` |
+| `oauth2_provider` | Provider name | `workos`, `okta`, `auth0`, `entra_id`, `keycloak` |
+| `oauth2_domain` | Provider domain | `your-domain.okta.com` |
+| `oauth2_client_id` | OAuth2 client ID | `0oaqnwji7pGW7VT6T697` |
+| `oauth2_audience` | API audience identifier | `api://default` |
+
+View current configuration:
+
+```bash
+crewai config list
+```
+
+### How Device Authorization Works
+
+1. Run `crewai login` — the CLI requests a device code from your IdP
+2. A verification URL and code are displayed in your terminal
+3. Your browser opens to the verification URL
+4. Enter the code and authenticate with your IdP credentials
+5. The CLI receives an access token and stores it locally
+
+---
+
+## Role-Based Access Control (RBAC)
+
+CrewAI Platform provides granular RBAC that integrates with your SSO provider. Permissions can be scoped to individual resources including dashboards, automations, and environment variables.
+
+- **Predefined roles** come out of the box with standard permission sets
+- **Custom roles** can be created with any combination of Read, Write, and Manage permissions
+- **Per-resource assignment** — limit specific automations to individual users or roles
+
+For detailed RBAC configuration, see the [RBAC documentation](/enterprise/features/rbac).
+
+---
+
+## Troubleshooting
+
+### CLI Login Fails (Device Authorization)
+
+**Symptom:** `crewai login` returns an error or times out.
+
+**Fix:**
+- Verify that Device Authorization Grant is enabled in your IdP
+- Check that your CLI is configured correctly: `crewai config list`
+- Ensure your CrewAI CLI version meets the minimum requirements for your provider
+
+### Token Validation Errors
+
+**Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login.
+
+**Fix:**
+- Verify that your OAuth2 audience and authorization server settings match your IdP configuration exactly
+- For SaaS: contact your CrewAI account team if errors persist after verifying CLI settings
+
+### 403 Forbidden After Login
+
+**Symptom:** User authenticates successfully but gets 403 errors.
+
+**Fix:**
+- Check that the user is assigned to the CrewAI application in your IdP
+- Verify the user has the appropriate role assignment in your IdP
+
+### CLI Can't Reach CrewAI Instance
+
+**Symptom:** `crewai enterprise configure` fails to connect.
+
+**Fix:**
+- Verify the instance URL is reachable from your machine
+- Check that `enterprise_base_url` is set correctly: `crewai config list`
+- Ensure TLS certificates are valid and trusted
+
+---
+
+## Next Steps
+
+- [Installation Guide](/installation) — Get started with CrewAI
+- [Quickstart](/quickstart) — Build your first crew
+- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management

docs/en/enterprise/guides/training-crews.mdx

@@ -1,132 +0,0 @@
----
-title: "Training Crews"
-description: "Train your deployed crews directly from the CrewAI AMP platform to improve agent performance over time"
-icon: "dumbbell"
-mode: "wide"
----
-
-Training lets you improve crew performance by running iterative training sessions directly from the **Training** tab in CrewAI AMP. The platform uses **auto-train mode** — it handles the iterative process automatically, unlike CLI training which requires interactive human feedback per iteration.
-
-After training completes, CrewAI evaluates agent outputs and consolidates feedback into actionable suggestions for each agent. These suggestions are then applied to future crew runs to improve output quality.
-
-<Tip>
-  For details on how CrewAI training works under the hood, see the [Training Concepts](/en/concepts/training) page.
-</Tip>
-
-## Prerequisites
-
-<CardGroup cols={2}>
-  <Card title="Active deployment" icon="rocket">
-    You need a CrewAI AMP account with an active deployment in **Ready** status (Crew type).
-  </Card>
-  <Card title="Run permission" icon="key">
-    Your account must have run permission for the deployment you want to train.
-  </Card>
-</CardGroup>
-
-## How to train a crew
-
-<Steps>
-  <Step title="Open the Training tab">
-    Navigate to **Deployments**, click your deployment, then select the **Training** tab.
-  </Step>
-
-  <Step title="Enter a training name">
-    Provide a **Training Name** — this becomes the `.pkl` filename used to store training results. For example, "Expert Mode Training" produces `expert_mode_training.pkl`.
-  </Step>
-
-  <Step title="Fill in the crew inputs">
-    Enter the crew's input fields. These are the same inputs you'd provide for a normal kickoff — they're dynamically loaded based on your crew's configuration.
-  </Step>
-
-  <Step title="Start training">
-    Click **Train Crew**. The button changes to "Training..." with a spinner while the process runs.
-
-    Behind the scenes:
-    - A training record is created for your deployment
-    - The platform calls the deployment's auto-train endpoint
-    - The crew runs its iterations automatically — no manual feedback required
-  </Step>
-
-  <Step title="Monitor progress">
-    The **Current Training Status** panel displays:
-    - **Status** — Current state of the training run
-    - **Nº Iterations** — Number of training iterations configured
-    - **Filename** — The `.pkl` file being generated
-    - **Started At** — When training began
-    - **Training Inputs** — The inputs you provided
-  </Step>
-</Steps>
-
-## Understanding training results
-
-Once training completes, you'll see per-agent result cards with the following information:
-
-- **Agent Role** — The name/role of the agent in your crew
-- **Final Quality** — A score from 0 to 10 evaluating the agent's output quality
-- **Final Summary** — A summary of the agent's performance during training
-- **Suggestions** — Actionable recommendations for improving the agent's behavior
-
-### Editing suggestions
-
-You can refine the suggestions for any agent:
-
-<Steps>
-  <Step title="Click Edit">
-    On any agent's result card, click the **Edit** button next to the suggestions.
-  </Step>
-
-  <Step title="Modify suggestions">
-    Update the suggestions text to better reflect the improvements you want.
-  </Step>
-
-  <Step title="Save changes">
-    Click **Save**. The edited suggestions sync back to the deployment and are used in all future runs.
-  </Step>
-</Steps>
-
-## Using trained data
-
-To apply training results to your crew:
-
-1. Note the **Training Filename** (the `.pkl` file) from your completed training session.
-2. Specify this filename in your deployment's kickoff or run configuration.
-3. The crew automatically loads the training file and applies the stored suggestions to each agent.
-
-This means agents benefit from the feedback generated during training on every subsequent run.
-
-## Previous trainings
-
-The bottom of the Training tab displays a **history of all past training sessions** for the deployment. Use this to review previous training runs, compare results, or select a different training file to use.
-
-## Error handling
-
-If a training run fails, the status panel shows an error state along with a message describing what went wrong.
-
-Common causes of training failures:
-- **Deployment runtime not updated** — Ensure your deployment is running the latest version
-- **Crew execution errors** — Issues within the crew's task logic or agent configuration
-- **Network issues** — Connectivity problems between the platform and the deployment
-
-## Limitations
-
-<Info>
-  Keep these constraints in mind when planning your training workflow:
-  - **One active training at a time** per deployment — wait for the current run to finish before starting another
-  - **Auto-train mode only** — the platform does not support interactive per-iteration feedback like the CLI does
-  - **Training data is deployment-specific** — training results are tied to the specific deployment instance and version
-</Info>
-
-## Related resources
-
-<CardGroup cols={3}>
-  <Card title="Training Concepts" icon="book" href="/en/concepts/training">
-    Learn how CrewAI training works under the hood.
-  </Card>
-  <Card title="Kickoff Crew" icon="play" href="/en/enterprise/guides/kickoff-crew">
-    Run your deployed crew from the AMP platform.
-  </Card>
-  <Card title="Deploy to AMP" icon="cloud-arrow-up" href="/en/enterprise/guides/deploy-to-amp">
-    Get your crew deployed and ready for training.
-  </Card>
-</CardGroup>

docs/ko/changelog.mdx

@@ -4,6 +4,191 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 3월 27일">
+  ## v1.13.0rc1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## 변경 사항
+
+  ### 문서
+  - v1.13.0a2의 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 3월 27일">
+  ## v1.13.0a2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## 변경 사항
+
+  ### 기능
+  - 릴리스 중 자동 업데이트 배포 테스트 리포지토리
+  - 기업 릴리스의 복원력 및 사용자 경험 개선
+
+  ### 문서
+  - v1.13.0a1에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="2026년 3월 27일">
+  ## v1.13.0a1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - Node를 LTS 22로 고정하여 문서 작업 흐름의 끊어진 링크 수정
+  - 기업 릴리스에서 새로 게시된 패키지의 uv 캐시 초기화
+
+  ### 문서
+  - 포괄적인 RBAC 권한 매트릭스 및 배포 가이드 추가
+  - v1.12.2에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.2
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## 변경 사항
+
+  ### 기능
+  - devtools 릴리스에 기업 릴리스 단계 추가
+
+  ### 버그 수정
+  - @human_feedback과 함께 emit을 사용할 때 메서드 반환 값을 흐름 출력으로 유지
+
+  ### 문서
+  - v1.12.1에 대한 변경 로그 및 버전 업데이트
+  - 보안 정책 및 보고 지침 수정
+
+  ## 기여자
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.1
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## 변경 사항
+
+  ### 기능
+  - HumanFeedbackRequestedEvent에 request_id 추가
+  - 메모리 시스템을 위한 Qdrant Edge 저장소 백엔드 추가
+  - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가
+  - 변경 로그 및 릴리스 도구에 아랍어 지원 추가
+  - 모든 문서에 대한 현대 표준 아랍어 번역 추가
+  - CLI에 로그아웃 명령어 추가
+  - 에이전트 기술 추가
+  - 계층적 메모리 격리를 위한 자동 root_scope 구현
+  - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### 버그 수정
+  - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404)
+  - HITL 흐름 시스템의 여러 버그 해결
+  - 에이전트 메모리 저장 수정
+  - crewai 패키지 전반에 걸쳐 모든 엄격한 mypy 오류 해결
+  - FlowMeta의 listener+router 메서드에 대한 __router_paths__ 사용 수정
+  - 파일 지원이 없는 경우 값 오류 수정
+  - 문서에서 litellm 격리 단어 수정
+  - crewai-files의 모든 mypy 오류 수정 및 모든 패키지를 CI 유형 검사에 추가
+  - litellm의 상한을 마지막 테스트된 버전 (1.82.6)으로 고정
+
+  ### 문서
+  - v1.12.0에 대한 변경 로그 및 버전 업데이트
+  - CONTRIBUTING.md 추가
+  - LiteLLM 없이 CrewAI를 사용하는 가이드 추가
+
+  ## 기여자
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="2026년 3월 25일">
+  ## v1.12.0
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## 변경 사항
+
+  ### 기능
+  - 메모리 시스템을 위한 Qdrant Edge 스토리지 백엔드 추가
+  - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가
+  - 변경 로그 및 릴리스 도구에 아랍어 지원 추가
+  - 모든 문서의 현대 표준 아랍어 번역 추가
+  - CLI에 로그아웃 명령어 추가
+  - 에이전트 기술 구현
+  - 계층적 메모리 격리를 위한 자동 root_scope 구현
+  - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### 버그 수정
+  - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404)
+  - HITL 흐름 시스템의 여러 버그 해결
+  - crewai-files의 mypy 오류 해결 및 모든 패키지를 CI 타입 검사에 추가
+  - crewai-tools 패키지 전반의 모든 엄격한 mypy 오류 해결
+  - crewai 패키지 전반의 모든 mypy 오류 해결
+  - 에이전트의 메모리 절약 수정
+  - FlowMeta에서 listener+router 메서드의 __router_paths__ 사용 수정
+  - 파일 지원이 없을 때 값 오류 발생
+  - 문서에서 litellm 격리 단어 수정
+  - 인간 피드백 학습에서 메모리에 대한 isinstance 대신 None 체크 사용
+  - litellm의 상한을 마지막 테스트된 버전(1.82.6)으로 고정
+
+  ### 문서
+  - v1.12.0에 대한 변경 로그 및 버전 업데이트
+  - CONTRIBUTING.md 추가
+  - LiteLLM 없이 CrewAI를 사용하는 가이드 추가
+
+  ### 리팩토링
+  - 에이전트에서 동기/비동기 작업 실행 및 시작을 중복 제거하도록 리팩토링
+  - litellm의 내부 플러밍 단순화 (토큰 카운팅, 콜백, 기능 감지, 오류)
+
+  ## 기여자
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
+<Update label="2026년 3월 26일">
+  ## v1.12.0a3
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404)
+  - HITL 흐름 시스템의 여러 버그 해결
+
+  ### 문서
+  - v1.12.0a2에 대한 변경 로그 및 버전 업데이트
+
+  ## 기여자
+
+  @akaKuruma, @greysonlalonde
+
+</Update>
+
 <Update label="2026년 3월 25일">
   ## v1.12.0a2
 

docs/pt-BR/changelog.mdx

@@ -4,6 +4,191 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="27 mar 2026">
+  ## v1.13.0rc1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1)
+
+  ## O que Mudou
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.13.0a2
+
+  ## Contribuidores
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 mar 2026">
+  ## v1.13.0a2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Repositório de teste de implantação de autoatualização durante o lançamento
+  - Melhorar a resiliência e a experiência do usuário na versão empresarial
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.13.0a1
+
+  ## Contribuidores
+
+  @greysonlalonde
+
+</Update>
+
+<Update label="27 mar 2026">
+  ## v1.13.0a1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir links quebrados no fluxo de documentação fixando o Node na LTS 22
+  - Limpar o cache uv para pacotes recém-publicados na versão empresarial
+
+  ### Documentação
+  - Adicionar uma matriz abrangente de permissões RBAC e guia de implantação
+  - Atualizar o changelog e a versão para v1.12.2
+
+  ## Contributors
+
+  @greysonlalonde, @iris-clawd, @joaomdmoura
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.2
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar fase de lançamento empresarial ao lançamento do devtools
+
+  ### Correções de Bugs
+  - Preservar o valor de retorno do método como saída de fluxo para @human_feedback com emit
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.1
+  - Revisar política de segurança e instruções de relatório
+
+  ## Contributors
+
+  @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.1
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar request_id ao HumanFeedbackRequestedEvent
+  - Adicionar backend de armazenamento Qdrant Edge para sistema de memória
+  - Adicionar comando docs-check para analisar mudanças e gerar documentação com traduções
+  - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento
+  - Adicionar tradução em árabe padrão moderno de toda a documentação
+  - Adicionar comando de logout na CLI
+  - Adicionar habilidades de agente
+  - Implementar root_scope automático para isolamento hierárquico de memória
+  - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Correções de Bugs
+  - Corrigir credenciais incorretas para envio em lote de traces (404)
+  - Resolver múltiplos bugs no sistema de fluxo HITL
+  - Corrigir salvamento de memória do agente
+  - Resolver todos os erros estritos do mypy no pacote crewai
+  - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta
+  - Corrigir erro de valor em caso de suporte a nenhum arquivo
+  - Corrigir redação da quarentena do litellm na documentação
+  - Corrigir todos os erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI
+  - Fixar limite superior do litellm na última versão testada (1.82.6)
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.0
+  - Adicionar CONTRIBUTING.md
+  - Adicionar guia para usar CrewAI sem LiteLLM
+
+  ## Contribuidores
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96
+
+</Update>
+
+<Update label="25 mar 2026">
+  ## v1.12.0
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Adicionar backend de armazenamento Qdrant Edge para sistema de memória
+  - Adicionar comando docs-check para analisar mudanças e gerar documentos com traduções
+  - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento
+  - Adicionar tradução em árabe padrão moderno de toda a documentação
+  - Adicionar comando de logout na CLI
+  - Implementar habilidades de agente
+  - Implementar root_scope automático para isolamento hierárquico de memória
+  - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope)
+
+  ### Correções de Bugs
+  - Corrigir credenciais inválidas para envio em lote de rastros (404)
+  - Resolver múltiplos bugs no sistema de fluxo HITL
+  - Resolver erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI
+  - Resolver todos os erros estritos do mypy no pacote crewai-tools
+  - Resolver todos os erros do mypy no pacote crewai
+  - Corrigir economia de memória no agente
+  - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta
+  - Levantar erro de valor em caso de suporte a arquivos inexistente
+  - Corrigir a redação da quarentena do litellm na documentação
+  - Usar verificação de None em vez de isinstance para memória no aprendizado de feedback humano
+  - Fixar limite superior do litellm na última versão testada (1.82.6)
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.0
+  - Adicionar CONTRIBUTING.md
+  - Adicionar guia para usar CrewAI sem LiteLLM
+
+  ### Refatoração
+  - Refatorar para desduplicar execução de tarefas síncronas/assíncronas e início no agente
+  - Simplificar a infraestrutura interna do litellm (contagem de tokens, callbacks, detecção de recursos, erros)
+
+  ## Contribuidores
+
+  @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96
+
+</Update>
+
+<Update label="26 mar 2026">
+  ## v1.12.0a3
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir credenciais inválidas para envio em lote de rastros (404)
+  - Resolver múltiplos bugs no sistema de fluxo HITL
+
+  ### Documentação
+  - Atualizar changelog e versão para v1.12.0a2
+
+  ## Contributors
+
+  @akaKuruma, @greysonlalonde
+
+</Update>
+
 <Update label="25 mar 2026">
   ## v1.12.0a2
 

lib/crewai-files/src/crewai_files/__init__.py

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.12.0a2"
+__version__ = "1.13.0rc1"

lib/crewai-tools/pyproject.toml

@@ -11,7 +11,7 @@ dependencies = [
     "pytube~=15.0.0",
     "requests~=2.32.5",
     "docker~=7.1.0",
-    "crewai==1.12.0a2",
+    "crewai==1.13.0rc1",
     "tiktoken~=0.8.0",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -309,4 +309,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.12.0a2"
+__version__ = "1.13.0rc1"

lib/crewai/pyproject.toml

@@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.12.0a2",
+    "crewai-tools==1.13.0rc1",
 ]
 embeddings = [
     "tiktoken~=0.8.0"

lib/crewai/src/crewai/__init__.py

@@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.12.0a2"
+__version__ = "1.13.0rc1"
 _telemetry_submitted = False
 
 

lib/crewai/src/crewai/cli/plus_api.py

@@ -196,6 +196,16 @@ class PlusAPI:
             timeout=30,
         )
 
+    def mark_ephemeral_trace_batch_as_failed(
+        self, trace_batch_id: str, error_message: str
+    ) -> httpx.Response:
+        return self._make_request(
+            "PATCH",
+            f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}",
+            json={"status": "failed", "failure_reason": error_message},
+            timeout=30,
+        )
+
     def get_mcp_configs(self, slugs: list[str]) -> httpx.Response:
         """Get MCP server configurations for the given slugs."""
         return self._make_request(

lib/crewai/src/crewai/cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a2"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a2"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [project.scripts]

lib/crewai/src/crewai/cli/templates/tool/pyproject.toml

@@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.12.0a2"
+    "crewai[tools]==1.13.0rc1"
 ]
 
 [tool.crewai]

lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py

@@ -1,3 +1,4 @@
+from datetime import datetime, timezone
 import logging
 import uuid
 import webbrowser
@@ -100,20 +101,50 @@ class FirstTimeTraceHandler:
                     user_context=user_context,
                     execution_metadata=execution_metadata,
                     use_ephemeral=True,
+                    skip_context_check=True,
                 )
+
+                if not self.batch_manager.trace_batch_id:
+                    self._gracefully_fail(
+                        "Backend batch creation failed, cannot send events."
+                    )
+                    self._reset_batch_state()
+                    return
+
                 self.batch_manager.backend_initialized = True
 
-            if self.batch_manager.event_buffer:
-                self.batch_manager._send_events_to_backend()
+            # Capture values before send/finalize consume them
+            events_count = len(self.batch_manager.event_buffer)
+            batch_id = self.batch_manager.trace_batch_id
+            # Read duration non-destructively — _finalize_backend_batch will consume it
+            start_time = self.batch_manager.execution_start_times.get("execution")
+            duration_ms = (
+                int((datetime.now(timezone.utc) - start_time).total_seconds() * 1000)
+                if start_time
+                else 0
+            )
 
-            self.batch_manager.finalize_batch()
+            if self.batch_manager.event_buffer:
+                send_status = self.batch_manager._send_events_to_backend()
+                if send_status == 500 and self.batch_manager.trace_batch_id:
+                    self.batch_manager._mark_batch_as_failed(
+                        self.batch_manager.trace_batch_id,
+                        "Error sending events to backend",
+                    )
+                    self._reset_batch_state()
+                    return
+
+            self.batch_manager._finalize_backend_batch(events_count)
             self.ephemeral_url = self.batch_manager.ephemeral_trace_url
 
             if not self.ephemeral_url:
-                self._show_local_trace_message()
+                self._show_local_trace_message(events_count, duration_ms, batch_id)
+
+            self._reset_batch_state()
 
         except Exception as e:
             self._gracefully_fail(f"Backend initialization failed: {e}")
+            self._reset_batch_state()
 
     def _display_ephemeral_trace_link(self) -> None:
         """Display the ephemeral trace link to the user and automatically open browser."""
@@ -185,6 +216,19 @@ To enable tracing later, do any one of these:
         console.print(panel)
         console.print()
 
+    def _reset_batch_state(self) -> None:
+        """Reset batch manager state to allow future executions to re-initialize."""
+        if not self.batch_manager:
+            return
+        self.batch_manager.batch_owner_type = None
+        self.batch_manager.batch_owner_id = None
+        self.batch_manager.current_batch = None
+        self.batch_manager.event_buffer.clear()
+        self.batch_manager.trace_batch_id = None
+        self.batch_manager.is_current_batch_ephemeral = False
+        self.batch_manager.backend_initialized = False
+        self.batch_manager._cleanup_batch_data()
+
     def _gracefully_fail(self, error_message: str) -> None:
         """Handle errors gracefully without disrupting user experience."""
         console = Console()
@@ -192,7 +236,9 @@ To enable tracing later, do any one of these:
 
         logger.debug(f"First-time trace error: {error_message}")
 
-    def _show_local_trace_message(self) -> None:
+    def _show_local_trace_message(
+        self, events_count: int = 0, duration_ms: int = 0, batch_id: str | None = None
+    ) -> None:
         """Show message when traces were collected locally but couldn't be uploaded."""
         if self.batch_manager is None:
             return
@@ -203,9 +249,9 @@ To enable tracing later, do any one of these:
 📊 Your execution traces were collected locally!
 
 Unfortunately, we couldn't upload them to the server right now, but here's what we captured:
-• {len(self.batch_manager.event_buffer)} trace events
-• Execution duration: {self.batch_manager.calculate_duration("execution")}ms
-• Batch ID: {self.batch_manager.trace_batch_id}
+• {events_count} trace events
+• Execution duration: {duration_ms}ms
+• Batch ID: {batch_id}
 
 ✅ Tracing has been enabled for future runs!
 Your preference has been saved. Future Crew/Flow executions will automatically collect traces.

lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from logging import getLogger
 from threading import Condition, Lock
+import time
 from typing import Any
 import uuid
 
@@ -98,7 +99,7 @@ class TraceBatchManager:
                 self._initialize_backend_batch(
                     user_context, execution_metadata, use_ephemeral
                 )
-                self.backend_initialized = True
+                self.backend_initialized = self.trace_batch_id is not None
 
             self._batch_ready_cv.notify_all()
             return self.current_batch
@@ -108,14 +109,15 @@ class TraceBatchManager:
         user_context: dict[str, str],
         execution_metadata: dict[str, Any],
         use_ephemeral: bool = False,
+        skip_context_check: bool = False,
     ) -> None:
         """Send batch initialization to backend"""
 
-        if not is_tracing_enabled_in_context():
-            return
+        if not skip_context_check and not is_tracing_enabled_in_context():
+            return None
 
         if not self.plus_api or not self.current_batch:
-            return
+            return None
 
         try:
             payload = {
@@ -142,19 +144,53 @@ class TraceBatchManager:
                 payload["ephemeral_trace_id"] = self.current_batch.batch_id
                 payload["user_identifier"] = get_user_id()
 
-            response = (
-                self.plus_api.initialize_ephemeral_trace_batch(payload)
-                if use_ephemeral
-                else self.plus_api.initialize_trace_batch(payload)
-            )
+            max_retries = 1
+            response = None
+
+            try:
+                for attempt in range(max_retries + 1):
+                    response = (
+                        self.plus_api.initialize_ephemeral_trace_batch(payload)
+                        if use_ephemeral
+                        else self.plus_api.initialize_trace_batch(payload)
+                    )
+                    if response is not None and response.status_code < 500:
+                        break
+                    if attempt < max_retries:
+                        logger.debug(
+                            f"Trace batch init attempt {attempt + 1} failed "
+                            f"(status={response.status_code if response else 'None'}), retrying..."
+                        )
+                        time.sleep(0.2)
+            except Exception as e:
+                logger.warning(
+                    f"Error initializing trace batch: {e}. Continuing without tracing."
+                )
+                self.trace_batch_id = None
+                return None
 
             if response is None:
                 logger.warning(
                     "Trace batch initialization failed gracefully. Continuing without tracing."
                 )
-                return
+                self.trace_batch_id = None
+                return None
+
+            # Fall back to ephemeral on auth failure (expired/revoked token)
+            if response.status_code in [401, 403] and not use_ephemeral:
+                logger.warning(
+                    "Auth rejected by server, falling back to ephemeral tracing."
+                )
+                self.is_current_batch_ephemeral = True
+                return self._initialize_backend_batch(
+                    user_context,
+                    execution_metadata,
+                    use_ephemeral=True,
+                    skip_context_check=skip_context_check,
+                )
 
             if response.status_code in [201, 200]:
+                self.is_current_batch_ephemeral = use_ephemeral
                 response_data = response.json()
                 self.trace_batch_id = (
                     response_data["trace_id"]
@@ -165,11 +201,22 @@ class TraceBatchManager:
                 logger.warning(
                     f"Trace batch initialization returned status {response.status_code}. Continuing without tracing."
                 )
+                self.trace_batch_id = None
 
         except Exception as e:
             logger.warning(
                 f"Error initializing trace batch: {e}. Continuing without tracing."
             )
+            self.trace_batch_id = None
+
+    def _mark_batch_as_failed(self, trace_batch_id: str, error_message: str) -> None:
+        """Mark a trace batch as failed, routing to the correct endpoint."""
+        if self.is_current_batch_ephemeral:
+            self.plus_api.mark_ephemeral_trace_batch_as_failed(
+                trace_batch_id, error_message
+            )
+        else:
+            self.plus_api.mark_trace_batch_as_failed(trace_batch_id, error_message)
 
     def begin_event_processing(self) -> None:
         """Mark that an event handler started processing (for synchronization)."""
@@ -260,7 +307,7 @@ class TraceBatchManager:
             logger.error(
                 "Event handler timeout - marking batch as failed due to incomplete events"
             )
-            self.plus_api.mark_trace_batch_as_failed(
+            self._mark_batch_as_failed(
                 self.trace_batch_id,
                 "Timeout waiting for event handlers - events incomplete",
             )
@@ -284,7 +331,7 @@ class TraceBatchManager:
             events_sent_to_backend_status = self._send_events_to_backend()
             self.event_buffer = original_buffer
             if events_sent_to_backend_status == 500 and self.trace_batch_id:
-                self.plus_api.mark_trace_batch_as_failed(
+                self._mark_batch_as_failed(
                     self.trace_batch_id, "Error sending events to backend"
                 )
                 return None
@@ -364,13 +411,16 @@ class TraceBatchManager:
                 logger.error(
                     f"❌ Failed to finalize trace batch: {response.status_code} - {response.text}"
                 )
-                self.plus_api.mark_trace_batch_as_failed(
-                    self.trace_batch_id, response.text
-                )
+                self._mark_batch_as_failed(self.trace_batch_id, response.text)
 
         except Exception as e:
             logger.error(f"❌ Error finalizing trace batch: {e}")
-            self.plus_api.mark_trace_batch_as_failed(self.trace_batch_id, str(e))
+            try:
+                self._mark_batch_as_failed(self.trace_batch_id, str(e))
+            except Exception:
+                logger.debug(
+                    "Could not mark trace batch as failed (network unavailable)"
+                )
 
     def _cleanup_batch_data(self) -> None:
         """Clean up batch data after successful finalization to free memory"""

lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py

@@ -235,8 +235,11 @@ class TraceCollectionListener(BaseEventListener):
 
         @event_bus.on(FlowStartedEvent)
         def on_flow_started(source: Any, event: FlowStartedEvent) -> None:
-            if not self.batch_manager.is_batch_initialized():
-                self._initialize_flow_batch(source, event)
+            # Always call _initialize_flow_batch to claim ownership.
+            # If batch was already initialized by a concurrent action event
+            # (race condition), initialize_batch() returns early but
+            # batch_owner_type is still correctly set to "flow".
+            self._initialize_flow_batch(source, event)
             self._handle_trace_event("flow_started", source, event)
 
         @event_bus.on(MethodExecutionStartedEvent)
@@ -266,7 +269,12 @@ class TraceCollectionListener(BaseEventListener):
 
         @event_bus.on(CrewKickoffStartedEvent)
         def on_crew_started(source: Any, event: CrewKickoffStartedEvent) -> None:
-            if not self.batch_manager.is_batch_initialized():
+            if self.batch_manager.batch_owner_type != "flow":
+                # Always call _initialize_crew_batch to claim ownership.
+                # If batch was already initialized by a concurrent action event
+                # (race condition with DefaultEnvEvent), initialize_batch() returns
+                # early but batch_owner_type is still correctly set to "crew".
+                # Skip only when a parent flow already owns the batch.
                 self._initialize_crew_batch(source, event)
             self._handle_trace_event("crew_kickoff_started", source, event)
 
@@ -772,7 +780,7 @@ class TraceCollectionListener(BaseEventListener):
                 "crew_name": getattr(source, "name", "Unknown Crew"),
                 "crewai_version": get_crewai_version(),
             }
-            self.batch_manager.initialize_batch(user_context, execution_metadata)
+            self._initialize_batch(user_context, execution_metadata)
 
         self.batch_manager.begin_event_processing()
         try:

lib/crewai/src/crewai/events/types/flow_events.py

@@ -178,12 +178,15 @@ class HumanFeedbackRequestedEvent(FlowEvent):
         output: The method output shown to the human for review.
         message: The message displayed when requesting feedback.
         emit: Optional list of possible outcomes for routing.
+        request_id: Platform-assigned identifier for this feedback request,
+            used for correlating the request across system boundaries.
     """
 
     method_name: str
     output: Any
     message: str
     emit: list[str] | None = None
+    request_id: str | None = None
     type: str = "human_feedback_requested"
 
 
@@ -198,9 +201,12 @@ class HumanFeedbackReceivedEvent(FlowEvent):
         method_name: Name of the method that received feedback.
         feedback: The raw text feedback provided by the human.
         outcome: The collapsed outcome string (if emit was specified).
+        request_id: Platform-assigned identifier for this feedback request,
+            used for correlating the response back to its originating request.
     """
 
     method_name: str
     feedback: str
     outcome: str | None = None
+    request_id: str | None = None
     type: str = "human_feedback_received"

lib/crewai/src/crewai/events/utils/console_formatter.py

@@ -127,6 +127,9 @@ To update, run: uv sync --upgrade-package crewai"""
 
     def _show_tracing_disabled_message_if_needed(self) -> None:
         """Show tracing disabled message if tracing is not enabled."""
+        from crewai.events.listeners.tracing.trace_listener import (
+            TraceCollectionListener,
+        )
         from crewai.events.listeners.tracing.utils import (
             has_user_declined_tracing,
             is_tracing_enabled_in_context,
@@ -136,6 +139,12 @@ To update, run: uv sync --upgrade-package crewai"""
         if should_suppress_tracing_messages():
             return
 
+        # Don't show "disabled" message when the first-time handler will show
+        # the trace prompt after execution completes (avoids confusing mid-flow messages)
+        listener = TraceCollectionListener._instance  # type: ignore[misc]
+        if listener and listener.first_time_handler.is_first_time:
+            return
+
         if not is_tracing_enabled_in_context():
             if has_user_declined_tracing():
                 message = """Info: Tracing is disabled.

lib/crewai/src/crewai/flow/async_feedback/providers.py

@@ -182,7 +182,7 @@ class ConsoleProvider:
                 console.print(message, style="yellow")
                 console.print()
 
-                response = input(">>> \n").strip()
+                response = input(">>> ").strip()
             else:
                 response = input(f"{message} ").strip()
 

lib/crewai/src/crewai/flow/async_feedback/types.py

@@ -63,6 +63,32 @@ class PendingFeedbackContext:
     llm: dict[str, Any] | str | None = None
     requested_at: datetime = field(default_factory=datetime.now)
 
+    @staticmethod
+    def _make_json_safe(value: Any) -> Any:
+        """Convert a value to a JSON-serializable form.
+
+        Handles Pydantic models, dataclasses, and arbitrary objects by
+        progressively falling back to string representation.
+        """
+        if value is None or isinstance(value, (str, int, float, bool)):
+            return value
+        if isinstance(value, (list, tuple)):
+            return [PendingFeedbackContext._make_json_safe(v) for v in value]
+        if isinstance(value, dict):
+            return {
+                k: PendingFeedbackContext._make_json_safe(v) for k, v in value.items()
+            }
+
+        from pydantic import BaseModel
+
+        if isinstance(value, BaseModel):
+            return value.model_dump(mode="json")
+        import dataclasses
+
+        if dataclasses.is_dataclass(value) and not isinstance(value, type):
+            return PendingFeedbackContext._make_json_safe(dataclasses.asdict(value))
+        return str(value)
+
     def to_dict(self) -> dict[str, Any]:
         """Serialize context to a dictionary for persistence.
 
@@ -73,11 +99,11 @@ class PendingFeedbackContext:
             "flow_id": self.flow_id,
             "flow_class": self.flow_class,
             "method_name": self.method_name,
-            "method_output": self.method_output,
+            "method_output": self._make_json_safe(self.method_output),
             "message": self.message,
             "emit": self.emit,
             "default_outcome": self.default_outcome,
-            "metadata": self.metadata,
+            "metadata": self._make_json_safe(self.metadata),
             "llm": self.llm,
             "requested_at": self.requested_at.isoformat(),
         }

lib/crewai/src/crewai/flow/flow.py

@@ -883,6 +883,9 @@ class Flow(Generic[T], metaclass=FlowMeta):
         self.human_feedback_history: list[HumanFeedbackResult] = []
         self.last_human_feedback: HumanFeedbackResult | None = None
         self._pending_feedback_context: PendingFeedbackContext | None = None
+        # Per-method stash for real @human_feedback output (keyed by method name)
+        # Used to decouple routing outcome from method return value when emit is set
+        self._human_feedback_method_outputs: dict[str, Any] = {}
         self.suppress_flow_events: bool = suppress_flow_events
 
         # User input history (for self.ask())
@@ -1223,9 +1226,6 @@ class Flow(Generic[T], metaclass=FlowMeta):
         # Mark that we're resuming execution
         instance._is_execution_resuming = True
 
-        # Mark the method as completed (it ran before pausing)
-        instance._completed_methods.add(FlowMethodName(pending_context.method_name))
-
         return instance
 
     @property
@@ -1380,7 +1380,8 @@ class Flow(Generic[T], metaclass=FlowMeta):
         self.human_feedback_history.append(result)
         self.last_human_feedback = result
 
-        # Clear pending context after processing
+        self._completed_methods.add(FlowMethodName(context.method_name))
+
         self._pending_feedback_context = None
 
         # Clear pending feedback from persistence
@@ -1403,7 +1404,10 @@ class Flow(Generic[T], metaclass=FlowMeta):
         # This allows methods to re-execute in loops (e.g., implement_changes → suggest_changes → implement_changes)
         self._is_execution_resuming = False
 
-        final_result: Any = result
+        if emit and collapsed_outcome is None:
+            collapsed_outcome = default_outcome or emit[0]
+            result.outcome = collapsed_outcome
+
         try:
             if emit and collapsed_outcome:
                 self._method_outputs.append(collapsed_outcome)
@@ -1421,7 +1425,8 @@ class Flow(Generic[T], metaclass=FlowMeta):
             from crewai.flow.async_feedback.types import HumanFeedbackPending
 
             if isinstance(e, HumanFeedbackPending):
-                # Auto-save pending feedback (create default persistence if needed)
+                self._pending_feedback_context = e.context
+
                 if self._persistence is None:
                     from crewai.flow.persistence import SQLiteFlowPersistence
 
@@ -1455,6 +1460,8 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 return e
             raise
 
+        final_result = self._method_outputs[-1] if self._method_outputs else result
+
         # Emit flow finished
         crewai_event_bus.emit(
             self,
@@ -2286,6 +2293,17 @@ class Flow(Generic[T], metaclass=FlowMeta):
                 result = await result
 
             self._method_outputs.append(result)
+
+            # For @human_feedback methods with emit, the result is the collapsed outcome
+            # (e.g., "approved") used for routing. But we want the actual method output
+            # to be the stored result (for final flow output). Replace the last entry
+            # if a stashed output exists. Dict-based stash is concurrency-safe and
+            # handles None return values (presence in dict = stashed, not value).
+            if method_name in self._human_feedback_method_outputs:
+                self._method_outputs[-1] = self._human_feedback_method_outputs.pop(
+                    method_name
+                )
+
             self._method_execution_counts[method_name] = (
                 self._method_execution_counts.get(method_name, 0) + 1
             )
@@ -2314,7 +2332,6 @@ class Flow(Generic[T], metaclass=FlowMeta):
             if isinstance(e, HumanFeedbackPending):
                 e.context.method_name = method_name
 
-                # Auto-save pending feedback (create default persistence if needed)
                 if self._persistence is None:
                     from crewai.flow.persistence import SQLiteFlowPersistence
 
@@ -3133,10 +3150,16 @@ class Flow(Generic[T], metaclass=FlowMeta):
                     if outcome.lower() == response_clean.lower():
                         return outcome
 
-                # Partial match
+                # Partial match (longest wins, first on length ties)
+                response_lower = response_clean.lower()
+                best_outcome: str | None = None
+                best_len = -1
                 for outcome in outcomes:
-                    if outcome.lower() in response_clean.lower():
-                        return outcome
+                    if outcome.lower() in response_lower and len(outcome) > best_len:
+                        best_outcome = outcome
+                        best_len = len(outcome)
+                if best_outcome is not None:
+                    return best_outcome
 
                 # Fallback to first outcome
                 logger.warning(

lib/crewai/src/crewai/flow/human_feedback.py

@@ -116,10 +116,11 @@ def _deserialize_llm_from_context(
         return LLM(model=llm_data)
 
     if isinstance(llm_data, dict):
-        model = llm_data.pop("model", None)
+        data = dict(llm_data)
+        model = data.pop("model", None)
         if not model:
             return None
-        return LLM(model=model, **llm_data)
+        return LLM(model=model, **data)
     return None
 
 
@@ -450,12 +451,12 @@ def human_feedback(
 
         # -- Core feedback helpers ------------------------------------
 
-        def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str:
-            """Request feedback using provider or default console."""
+        def _build_feedback_context(
+            flow_instance: Flow[Any], method_output: Any
+        ) -> tuple[Any, Any]:
+            """Build the PendingFeedbackContext and resolve the effective provider."""
             from crewai.flow.async_feedback.types import PendingFeedbackContext
 
-            # Build context for provider
-            # Use flow_id property which handles both dict and BaseModel states
             context = PendingFeedbackContext(
                 flow_id=flow_instance.flow_id or "unknown",
                 flow_class=f"{flow_instance.__class__.__module__}.{flow_instance.__class__.__name__}",
@@ -468,15 +469,53 @@ def human_feedback(
                 llm=llm if isinstance(llm, str) else _serialize_llm_for_context(llm),
             )
 
-            # Determine effective provider:
             effective_provider = provider
             if effective_provider is None:
                 from crewai.flow.flow_config import flow_config
 
                 effective_provider = flow_config.hitl_provider
 
+            return context, effective_provider
+
+        def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str:
+            """Request feedback using provider or default console (sync)."""
+            context, effective_provider = _build_feedback_context(
+                flow_instance, method_output
+            )
+
             if effective_provider is not None:
-                return effective_provider.request_feedback(context, flow_instance)
+                feedback_result = effective_provider.request_feedback(
+                    context, flow_instance
+                )
+                if asyncio.iscoroutine(feedback_result):
+                    raise TypeError(
+                        f"Provider {type(effective_provider).__name__}.request_feedback() "
+                        "returned a coroutine in a sync flow method. Use an async flow "
+                        "method or a synchronous provider."
+                    )
+                return str(feedback_result)
+            return flow_instance._request_human_feedback(
+                message=message,
+                output=method_output,
+                metadata=metadata,
+                emit=emit,
+            )
+
+        async def _request_feedback_async(
+            flow_instance: Flow[Any], method_output: Any
+        ) -> str:
+            """Request feedback, awaiting the provider if it returns a coroutine."""
+            context, effective_provider = _build_feedback_context(
+                flow_instance, method_output
+            )
+
+            if effective_provider is not None:
+                feedback_result = effective_provider.request_feedback(
+                    context, flow_instance
+                )
+                if asyncio.iscoroutine(feedback_result):
+                    return str(await feedback_result)
+                return str(feedback_result)
             return flow_instance._request_human_feedback(
                 message=message,
                 output=method_output,
@@ -524,10 +563,11 @@ def human_feedback(
             flow_instance.human_feedback_history.append(result)
             flow_instance.last_human_feedback = result
 
-            # Return based on mode
             if emit:
-                # Return outcome for routing
-                return collapsed_outcome  # type: ignore[return-value]
+                if collapsed_outcome is None:
+                    collapsed_outcome = default_outcome or emit[0]
+                    result.outcome = collapsed_outcome
+                return collapsed_outcome
             return result
 
         if asyncio.iscoroutinefunction(func):
@@ -540,7 +580,7 @@ def human_feedback(
                 if learn and getattr(self, "memory", None) is not None:
                     method_output = _pre_review_with_lessons(self, method_output)
 
-                raw_feedback = _request_feedback(self, method_output)
+                raw_feedback = await _request_feedback_async(self, method_output)
                 result = _process_feedback(self, method_output, raw_feedback)
 
                 # Distill: extract lessons from output + feedback, store in memory
@@ -551,6 +591,13 @@ def human_feedback(
                 ):
                     _distill_and_store_lessons(self, method_output, raw_feedback)
 
+                # Stash the real method output for final flow result when emit is set
+                # (result is the collapsed outcome string for routing, but we want to
+                # preserve the actual method output as the flow's final result)
+                # Uses per-method dict for concurrency safety and to handle None returns
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
                 return result
 
             wrapper: Any = async_wrapper
@@ -575,6 +622,13 @@ def human_feedback(
                 ):
                     _distill_and_store_lessons(self, method_output, raw_feedback)
 
+                # Stash the real method output for final flow result when emit is set
+                # (result is the collapsed outcome string for routing, but we want to
+                # preserve the actual method output as the flow's final result)
+                # Uses per-method dict for concurrency safety and to handle None returns
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
                 return result
 
             wrapper = sync_wrapper

lib/crewai/src/crewai/llm.py

@@ -483,8 +483,8 @@ class LLM(BaseLLM):
                 for prefix in ["gpt-", "gpt-35-", "o1", "o3", "o4", "azure-"]
             )
 
-        # OpenAI-compatible providers - accept any model name since these
-        # providers host many different models with varied naming conventions
+        # OpenAI-compatible providers - most accept any model name, but some
+        # (DeepSeek, Dashscope) restrict to their own model prefixes
         if provider == "deepseek":
             return model_lower.startswith("deepseek")
 

lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py

@@ -239,7 +239,8 @@ class OpenAICompatibleCompletion(OpenAICompletion):
         if base_url:
             resolved = base_url
         elif config.base_url_env:
-            resolved = os.getenv(config.base_url_env, config.base_url)
+            env_value = os.getenv(config.base_url_env)
+            resolved = env_value if env_value else config.base_url
         else:
             resolved = config.base_url
 
@@ -274,9 +275,11 @@ class OpenAICompatibleCompletion(OpenAICompletion):
     def supports_function_calling(self) -> bool:
         """Check if the provider supports function calling.
 
-        All modern OpenAI-compatible providers support function calling.
+        Delegates to the parent OpenAI implementation which handles
+        edge cases like o1 models (which may be routed through
+        OpenRouter or other compatible providers).
 
         Returns:
-            True, as all supported providers have function calling support.
+            Whether the model supports function calling.
         """
-        return True
+        return super().supports_function_calling()

lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py

@@ -1,7 +1,7 @@
 """Tests for OpenAI-compatible providers."""
 
 import os
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 import pytest
 
@@ -133,7 +133,7 @@ class TestOpenAICompatibleCompletion:
             with pytest.raises(ValueError, match="API key required"):
                 OpenAICompatibleCompletion(model="deepseek-chat", provider="deepseek")
         finally:
-            if original:
+            if original is not None:
                 os.environ[env_key] = original
 
     def test_api_key_from_env(self):

lib/crewai/tests/test_human_feedback_decorator.py

@@ -246,7 +246,7 @@ class TestHumanFeedbackExecution:
     @patch("builtins.input", return_value="")
     @patch("builtins.print")
     def test_empty_feedback_with_default_outcome(self, mock_print, mock_input):
-        """Test empty feedback uses default_outcome."""
+        """Test empty feedback uses default_outcome for routing, but flow returns method output."""
 
         class TestFlow(Flow):
             @start()
@@ -264,14 +264,16 @@ class TestHumanFeedbackExecution:
         with patch.object(flow, "_request_human_feedback", return_value=""):
             result = flow.kickoff()
 
-        assert result == "needs_work"
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "Content"
         assert flow.last_human_feedback is not None
+        # But the outcome is still correctly set for routing purposes
         assert flow.last_human_feedback.outcome == "needs_work"
 
     @patch("builtins.input", return_value="Approved!")
     @patch("builtins.print")
     def test_feedback_collapsing(self, mock_print, mock_input):
-        """Test that feedback is collapsed to an outcome."""
+        """Test that feedback is collapsed to an outcome for routing, but flow returns method output."""
 
         class TestFlow(Flow):
             @start()
@@ -291,8 +293,10 @@ class TestHumanFeedbackExecution:
         ):
             result = flow.kickoff()
 
-        assert result == "approved"
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "Content"
         assert flow.last_human_feedback is not None
+        # But the outcome is still correctly set for routing purposes
         assert flow.last_human_feedback.outcome == "approved"
 
 
@@ -591,3 +595,162 @@ class TestHumanFeedbackLearn:
         assert config.learn is True
         # llm defaults to "gpt-4o-mini" at the function level
         assert config.llm == "gpt-4o-mini"
+
+
+class TestHumanFeedbackFinalOutputPreservation:
+    """Tests for preserving method return value as flow's final output when @human_feedback with emit is terminal.
+
+    This addresses the bug where the flow's final output was the collapsed outcome string (e.g., 'approved')
+    instead of the method's actual return value when a @human_feedback method with emit is the final method.
+    """
+
+    @patch("builtins.input", return_value="Looks good!")
+    @patch("builtins.print")
+    def test_final_output_is_method_return_not_collapsed_outcome(
+        self, mock_print, mock_input
+    ):
+        """When @human_feedback with emit is the final method, flow output is the method's return value."""
+
+        class FinalHumanFeedbackFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review this content:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def generate_and_review(self):
+                # This dict should be the final output, NOT the string 'approved'
+                return {"title": "My Article", "content": "Article content here", "status": "ready"}
+
+        flow = FinalHumanFeedbackFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="Looks great, approved!"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # The final output should be the actual method return value, not the collapsed outcome
+        assert isinstance(result, dict), f"Expected dict, got {type(result).__name__}: {result}"
+        assert result == {"title": "My Article", "content": "Article content here", "status": "ready"}
+        # But the outcome should still be tracked in last_human_feedback
+        assert flow.last_human_feedback is not None
+        assert flow.last_human_feedback.outcome == "approved"
+
+    @patch("builtins.input", return_value="approved")
+    @patch("builtins.print")
+    def test_routing_still_works_with_downstream_listener(self, mock_print, mock_input):
+        """When @human_feedback has a downstream listener, routing still triggers the listener."""
+        publish_called = []
+
+        class RoutingFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def review(self):
+                return {"content": "original content"}
+
+            @listen("approved")
+            def publish(self):
+                publish_called.append(True)
+                return {"published": True, "timestamp": "2024-01-01"}
+
+        flow = RoutingFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="LGTM"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # The downstream listener should have been triggered
+        assert len(publish_called) == 1, "publish() should have been called"
+        # The final output should be from the listener, not the human_feedback method
+        assert result == {"published": True, "timestamp": "2024-01-01"}
+
+    @patch("builtins.input", return_value="")
+    @patch("builtins.print")
+    @pytest.mark.asyncio
+    async def test_async_human_feedback_final_output_preserved(self, mock_print, mock_input):
+        """Async @human_feedback methods also preserve the real return value."""
+
+        class AsyncFinalFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review async content:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+                default_outcome="approved",
+            )
+            async def async_generate(self):
+                return {"async_data": "value", "computed": 42}
+
+        flow = AsyncFinalFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value=""),
+        ):
+            result = await flow.kickoff_async()
+
+        # The final output should be the dict, not "approved"
+        assert isinstance(result, dict), f"Expected dict, got {type(result).__name__}: {result}"
+        assert result == {"async_data": "value", "computed": 42}
+        assert flow.last_human_feedback.outcome == "approved"
+
+    @patch("builtins.input", return_value="feedback")
+    @patch("builtins.print")
+    def test_method_outputs_contains_real_output(self, mock_print, mock_input):
+        """The _method_outputs list should contain the real method output, not the collapsed outcome."""
+
+        class OutputTrackingFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def generate(self):
+                return {"data": "real output"}
+
+        flow = OutputTrackingFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value="approved"),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            flow.kickoff()
+
+        # _method_outputs should contain the real output
+        assert len(flow._method_outputs) == 1
+        assert flow._method_outputs[0] == {"data": "real output"}
+
+    @patch("builtins.input", return_value="looks good")
+    @patch("builtins.print")
+    def test_none_return_value_is_preserved(self, mock_print, mock_input):
+        """A method returning None should preserve None as flow output, not the outcome string."""
+
+        class NoneReturnFlow(Flow):
+            @start()
+            @human_feedback(
+                message="Review:",
+                emit=["approved", "rejected"],
+                llm="gpt-4o-mini",
+            )
+            def process(self):
+                # Method does work but returns None (implicit)
+                pass
+
+        flow = NoneReturnFlow()
+
+        with (
+            patch.object(flow, "_request_human_feedback", return_value=""),
+            patch.object(flow, "_collapse_to_outcome", return_value="approved"),
+        ):
+            result = flow.kickoff()
+
+        # Final output should be None (the method's real return), not "approved"
+        assert result is None, f"Expected None, got {result!r}"
+        assert flow.last_human_feedback.outcome == "approved"

lib/crewai/tests/test_human_feedback_integration.py

@@ -708,7 +708,7 @@ class TestEdgeCases:
     @patch("builtins.input", return_value="")
     @patch("builtins.print")
     def test_empty_feedback_first_outcome_fallback(self, mock_print, mock_input):
-        """Test that empty feedback without default uses first outcome."""
+        """Test that empty feedback without default uses first outcome for routing, but returns method output."""
 
         class FallbackFlow(Flow):
             @start()
@@ -726,12 +726,15 @@ class TestEdgeCases:
         with patch.object(flow, "_request_human_feedback", return_value=""):
             result = flow.kickoff()
 
-        assert result == "first"  # Falls back to first outcome
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "content"
+        # But outcome is still set to first for routing purposes
+        assert flow.last_human_feedback.outcome == "first"
 
     @patch("builtins.input", return_value="whitespace only   ")
     @patch("builtins.print")
     def test_whitespace_only_feedback_treated_as_empty(self, mock_print, mock_input):
-        """Test that whitespace-only feedback is treated as empty."""
+        """Test that whitespace-only feedback is treated as empty for routing, but returns method output."""
 
         class WhitespaceFlow(Flow):
             @start()
@@ -749,7 +752,10 @@ class TestEdgeCases:
         with patch.object(flow, "_request_human_feedback", return_value="   "):
             result = flow.kickoff()
 
-        assert result == "reject"  # Uses default because feedback is empty after strip
+        # Flow result is the method's return value, NOT the collapsed outcome
+        assert result == "content"
+        # But outcome is set to default because feedback is empty after strip
+        assert flow.last_human_feedback.outcome == "reject"
 
     @patch("builtins.input", return_value="feedback")
     @patch("builtins.print")

lib/crewai/tests/tracing/test_tracing.py

@@ -7,6 +7,7 @@ from crewai.events.listeners.tracing.first_time_trace_handler import (
     FirstTimeTraceHandler,
 )
 from crewai.events.listeners.tracing.trace_batch_manager import (
+    TraceBatch,
     TraceBatchManager,
 )
 from crewai.events.listeners.tracing.trace_listener import (
@@ -657,6 +658,16 @@ class TestTraceListenerSetup:
 
             trace_listener.first_time_handler.collected_events = True
 
+            mock_batch_response = MagicMock()
+            mock_batch_response.status_code = 201
+            mock_batch_response.json.return_value = {
+                "trace_id": "mock-trace-id",
+                "ephemeral_trace_id": "mock-ephemeral-trace-id",
+                "access_code": "TRACE-mock",
+            }
+            mock_events_response = MagicMock()
+            mock_events_response.status_code = 200
+
             with (
                 patch.object(
                     trace_listener.first_time_handler,
@@ -666,6 +677,40 @@ class TestTraceListenerSetup:
                 patch.object(
                     trace_listener.first_time_handler, "_display_ephemeral_trace_link"
                 ) as mock_display_link,
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "initialize_trace_batch",
+                    return_value=mock_batch_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "initialize_ephemeral_trace_batch",
+                    return_value=mock_batch_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "send_trace_events",
+                    return_value=mock_events_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "send_ephemeral_trace_events",
+                    return_value=mock_events_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "finalize_trace_batch",
+                    return_value=mock_events_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager.plus_api,
+                    "finalize_ephemeral_trace_batch",
+                    return_value=mock_events_response,
+                ),
+                patch.object(
+                    trace_listener.batch_manager,
+                    "_cleanup_batch_data",
+                ),
             ):
                 crew.kickoff()
                 wait_for_event_handlers()
@@ -918,3 +963,676 @@ class TestTraceListenerSetup:
                 mock_init.assert_called_once()
                 payload = mock_init.call_args[0][0]
                 assert "user_identifier" not in payload
+
+
+class TestTraceBatchIdClearedOnFailure:
+    """Tests: trace_batch_id is cleared when _initialize_backend_batch fails."""
+
+    def _make_batch_manager(self):
+        """Create a TraceBatchManager with a pre-set trace_batch_id (simulating first-time user)."""
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.current_batch = TraceBatch(
+            user_context={"privacy_level": "standard"},
+            execution_metadata={"execution_type": "crew", "crew_name": "test"},
+        )
+        bm.trace_batch_id = bm.current_batch.batch_id  # simulate line 96
+        bm.is_current_batch_ephemeral = True
+        return bm
+
+    def test_trace_batch_id_cleared_on_exception(self):
+        """trace_batch_id must be None when the API call raises an exception."""
+        bm = self._make_batch_manager()
+        assert bm.trace_batch_id is not None
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                side_effect=ConnectionError("network down"),
+            ),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id is None
+
+    def test_trace_batch_id_set_on_success(self):
+        """trace_batch_id must be set from the server response on success."""
+        bm = self._make_batch_manager()
+        server_id = "server-ephemeral-trace-id-999"
+
+        mock_response = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=mock_response,
+            ),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id == server_id
+
+    def test_send_events_skipped_when_trace_batch_id_none(self):
+        """_send_events_to_backend must return early when trace_batch_id is None."""
+        bm = self._make_batch_manager()
+        bm.trace_batch_id = None
+        bm.event_buffer = [MagicMock()]  # has events
+
+        with patch.object(
+            bm.plus_api, "send_ephemeral_trace_events"
+        ) as mock_send:
+            result = bm._send_events_to_backend()
+
+        assert result == 500
+        mock_send.assert_not_called()
+
+
+class TestInitializeBackendBatchRetry:
+    """Tests for retry logic in _initialize_backend_batch."""
+
+    def _make_batch_manager(self):
+        """Create a TraceBatchManager with a pre-set trace_batch_id."""
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.current_batch = TraceBatch(
+            user_context={"privacy_level": "standard"},
+            execution_metadata={"execution_type": "crew", "crew_name": "test"},
+        )
+        bm.trace_batch_id = bm.current_batch.batch_id
+        bm.is_current_batch_ephemeral = True
+        return bm
+
+    def test_retries_on_none_response_then_succeeds(self):
+        """Retries when API returns None, succeeds on second attempt."""
+        bm = self._make_batch_manager()
+        server_id = "server-id-after-retry"
+
+        success_response = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                side_effect=[None, success_response],
+            ) as mock_init,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep,
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id == server_id
+        assert mock_init.call_count == 2
+        mock_sleep.assert_called_once_with(0.2)
+
+    def test_retries_on_5xx_then_succeeds(self):
+        """Retries on 500 server error, succeeds on second attempt."""
+        bm = self._make_batch_manager()
+        server_id = "server-id-after-5xx"
+
+        error_response = MagicMock(status_code=500, text="Internal Server Error")
+        success_response = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                side_effect=[error_response, success_response],
+            ) as mock_init,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id == server_id
+        assert mock_init.call_count == 2
+
+    def test_no_retry_on_exception(self):
+        """Exceptions (e.g. timeout, connection error) abort immediately without retry."""
+        bm = self._make_batch_manager()
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                side_effect=ConnectionError("network down"),
+            ) as mock_init,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep,
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id is None
+        assert mock_init.call_count == 1
+        mock_sleep.assert_not_called()
+
+    def test_no_retry_on_4xx(self):
+        """Does NOT retry on 422 — client error is not transient."""
+        bm = self._make_batch_manager()
+
+        error_response = MagicMock(status_code=422, text="Unprocessable Entity")
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=error_response,
+            ) as mock_init,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep,
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id is None
+        assert mock_init.call_count == 1
+        mock_sleep.assert_not_called()
+
+    def test_exhausts_retries_then_clears_batch_id(self):
+        """After all retries fail, trace_batch_id is None."""
+        bm = self._make_batch_manager()
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=None,
+            ) as mock_init,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id is None
+        assert mock_init.call_count == 2  # initial + 1 retry
+
+
+class TestFirstTimeHandlerBackendInitGuard:
+    """Tests: backend_initialized gated on actual batch creation success."""
+
+    def _make_handler_with_manager(self):
+        """Create a FirstTimeTraceHandler wired to a TraceBatchManager."""
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.current_batch = TraceBatch(
+            user_context={"privacy_level": "standard"},
+            execution_metadata={"execution_type": "crew", "crew_name": "test"},
+        )
+        bm.trace_batch_id = bm.current_batch.batch_id
+        bm.is_current_batch_ephemeral = True
+
+        handler = FirstTimeTraceHandler()
+        handler.is_first_time = True
+        handler.collected_events = True
+        handler.batch_manager = bm
+        return handler, bm
+
+    def test_backend_initialized_true_on_success(self):
+        """Events are sent when batch creation succeeds, then state is cleaned up."""
+        handler, bm = self._make_handler_with_manager()
+        server_id = "server-id-abc"
+
+        mock_init_response = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+        mock_send_response = MagicMock(status_code=200)
+
+        trace_batch_id_during_send = None
+
+        def capture_send(*args, **kwargs):
+            nonlocal trace_batch_id_during_send
+            trace_batch_id_during_send = bm.trace_batch_id
+            return mock_send_response
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=mock_init_response,
+            ),
+            patch.object(
+                bm.plus_api,
+                "send_ephemeral_trace_events",
+                side_effect=capture_send,
+            ),
+            patch.object(bm, "_finalize_backend_batch"),
+        ):
+            bm.event_buffer = [MagicMock(to_dict=MagicMock(return_value={}))]
+            handler._initialize_backend_and_send_events()
+
+        # trace_batch_id was set correctly during send
+        assert trace_batch_id_during_send == server_id
+        # State cleaned up after completion (singleton reuse)
+        assert bm.backend_initialized is False
+        assert bm.trace_batch_id is None
+        assert bm.current_batch is None
+
+    def test_backend_initialized_false_on_failure(self):
+        """backend_initialized stays False and events are NOT sent when batch creation fails."""
+        handler, bm = self._make_handler_with_manager()
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=None,  # server call fails
+            ),
+            patch.object(bm, "_send_events_to_backend") as mock_send,
+            patch.object(bm, "_finalize_backend_batch") as mock_finalize,
+            patch.object(handler, "_gracefully_fail") as mock_fail,
+        ):
+            bm.event_buffer = [MagicMock()]
+            handler._initialize_backend_and_send_events()
+
+        assert bm.backend_initialized is False
+        assert bm.trace_batch_id is None
+        mock_send.assert_not_called()
+        mock_finalize.assert_not_called()
+        mock_fail.assert_called_once()
+
+    def test_backend_initialized_false_on_non_2xx(self):
+        """backend_initialized stays False when server returns non-2xx."""
+        handler, bm = self._make_handler_with_manager()
+
+        mock_response = MagicMock(status_code=500, text="Internal Server Error")
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=mock_response,
+            ),
+            patch.object(bm, "_send_events_to_backend") as mock_send,
+            patch.object(bm, "_finalize_backend_batch") as mock_finalize,
+            patch.object(handler, "_gracefully_fail") as mock_fail,
+        ):
+            bm.event_buffer = [MagicMock()]
+            handler._initialize_backend_and_send_events()
+
+        assert bm.backend_initialized is False
+        assert bm.trace_batch_id is None
+        mock_send.assert_not_called()
+        mock_finalize.assert_not_called()
+        mock_fail.assert_called_once()
+
+
+class TestFirstTimeHandlerAlwaysEphemeral:
+    """Tests that first-time handler always uses ephemeral with skip_context_check."""
+
+    def _make_handler_with_manager(self):
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.current_batch = TraceBatch(
+            user_context={"privacy_level": "standard"},
+            execution_metadata={"execution_type": "crew", "crew_name": "test"},
+        )
+        bm.trace_batch_id = bm.current_batch.batch_id
+        bm.is_current_batch_ephemeral = True
+
+        handler = FirstTimeTraceHandler()
+        handler.is_first_time = True
+        handler.collected_events = True
+        handler.batch_manager = bm
+        return handler, bm
+
+    def test_deferred_init_uses_ephemeral_and_skip_context_check(self):
+        """Deferred backend init always uses ephemeral=True and skip_context_check=True."""
+        handler, bm = self._make_handler_with_manager()
+
+        with (
+            patch.object(bm, "_initialize_backend_batch") as mock_init,
+            patch.object(bm, "_send_events_to_backend"),
+            patch.object(bm, "_finalize_backend_batch"),
+        ):
+            mock_init.side_effect = lambda **kwargs: None
+            bm.event_buffer = [MagicMock()]
+            handler._initialize_backend_and_send_events()
+
+            mock_init.assert_called_once()
+            assert mock_init.call_args.kwargs["use_ephemeral"] is True
+            assert mock_init.call_args.kwargs["skip_context_check"] is True
+
+
+class TestAuthFailbackToEphemeral:
+    """Tests for ephemeral fallback when server rejects auth (401/403)."""
+
+    def _make_batch_manager(self):
+        """Create a TraceBatchManager with a pre-set trace_batch_id."""
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.current_batch = TraceBatch(
+            user_context={"privacy_level": "standard"},
+            execution_metadata={"execution_type": "crew", "crew_name": "test"},
+        )
+        bm.trace_batch_id = bm.current_batch.batch_id
+        bm.is_current_batch_ephemeral = False  # authenticated path
+        return bm
+
+    def test_401_non_ephemeral_falls_back_to_ephemeral(self):
+        """A 401 on the non-ephemeral endpoint should retry as ephemeral."""
+        bm = self._make_batch_manager()
+        server_id = "ephemeral-fallback-id"
+
+        auth_rejected = MagicMock(status_code=401, text="Bad credentials")
+        ephemeral_success = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_trace_batch",
+                return_value=auth_rejected,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=ephemeral_success,
+            ) as mock_ephemeral,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=False,
+            )
+
+        assert bm.trace_batch_id == server_id
+        assert bm.is_current_batch_ephemeral is True
+        mock_ephemeral.assert_called_once()
+
+    def test_403_non_ephemeral_falls_back_to_ephemeral(self):
+        """A 403 on the non-ephemeral endpoint should also fall back."""
+        bm = self._make_batch_manager()
+        server_id = "ephemeral-fallback-403"
+
+        forbidden = MagicMock(status_code=403, text="Forbidden")
+        ephemeral_success = MagicMock(
+            status_code=201,
+            json=MagicMock(return_value={"ephemeral_trace_id": server_id}),
+        )
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_trace_batch",
+                return_value=forbidden,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=ephemeral_success,
+            ),
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=False,
+            )
+
+        assert bm.trace_batch_id == server_id
+        assert bm.is_current_batch_ephemeral is True
+
+    def test_401_on_ephemeral_does_not_recurse(self):
+        """A 401 on the ephemeral endpoint should NOT try to fall back again."""
+        bm = self._make_batch_manager()
+        bm.is_current_batch_ephemeral = True
+
+        auth_rejected = MagicMock(status_code=401, text="Bad credentials")
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=auth_rejected,
+            ) as mock_ephemeral,
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=True,
+            )
+
+        assert bm.trace_batch_id is None
+        # Called only once — no recursive fallback
+        mock_ephemeral.assert_called()
+
+    def test_401_fallback_ephemeral_also_fails(self):
+        """If ephemeral fallback also fails, trace_batch_id is cleared."""
+        bm = self._make_batch_manager()
+
+        auth_rejected = MagicMock(status_code=401, text="Bad credentials")
+        ephemeral_fail = MagicMock(status_code=422, text="Validation failed")
+
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_trace_batch",
+                return_value=auth_rejected,
+            ),
+            patch.object(
+                bm.plus_api,
+                "initialize_ephemeral_trace_batch",
+                return_value=ephemeral_fail,
+            ),
+            patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"),
+        ):
+            bm._initialize_backend_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={"execution_type": "crew"},
+                use_ephemeral=False,
+            )
+
+        assert bm.trace_batch_id is None
+
+
+class TestMarkBatchAsFailedRouting:
+    """Tests: _mark_batch_as_failed routes to the correct endpoint."""
+
+    def _make_batch_manager(self, ephemeral: bool = False):
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+            return_value="mock_token",
+        ):
+            bm = TraceBatchManager()
+        bm.is_current_batch_ephemeral = ephemeral
+        return bm
+
+    def test_routes_to_ephemeral_endpoint_when_ephemeral(self):
+        """Ephemeral batches must use mark_ephemeral_trace_batch_as_failed."""
+        bm = self._make_batch_manager(ephemeral=True)
+
+        with patch.object(
+            bm.plus_api, "mark_ephemeral_trace_batch_as_failed"
+        ) as mock_ephemeral, patch.object(
+            bm.plus_api, "mark_trace_batch_as_failed"
+        ) as mock_non_ephemeral:
+            bm._mark_batch_as_failed("batch-123", "some error")
+
+        mock_ephemeral.assert_called_once_with("batch-123", "some error")
+        mock_non_ephemeral.assert_not_called()
+
+    def test_routes_to_non_ephemeral_endpoint_when_not_ephemeral(self):
+        """Non-ephemeral batches must use mark_trace_batch_as_failed."""
+        bm = self._make_batch_manager(ephemeral=False)
+
+        with patch.object(
+            bm.plus_api, "mark_ephemeral_trace_batch_as_failed"
+        ) as mock_ephemeral, patch.object(
+            bm.plus_api, "mark_trace_batch_as_failed"
+        ) as mock_non_ephemeral:
+            bm._mark_batch_as_failed("batch-456", "another error")
+
+        mock_non_ephemeral.assert_called_once_with("batch-456", "another error")
+        mock_ephemeral.assert_not_called()
+
+
+class TestBackendInitializedGatedOnSuccess:
+    """Tests: backend_initialized reflects actual init success on non-first-time path."""
+
+    def test_backend_initialized_true_on_success(self):
+        """backend_initialized is True when _initialize_backend_batch succeeds."""
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces",
+                return_value=False,
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+                return_value="mock_token",
+            ),
+        ):
+            bm = TraceBatchManager()
+            mock_response = MagicMock(
+                status_code=201,
+                json=MagicMock(return_value={"trace_id": "server-id"}),
+            )
+            with patch.object(
+                bm.plus_api, "initialize_trace_batch", return_value=mock_response
+            ):
+                bm.initialize_batch(
+                    user_context={"privacy_level": "standard"},
+                    execution_metadata={"execution_type": "crew"},
+                )
+
+        assert bm.backend_initialized is True
+        assert bm.trace_batch_id == "server-id"
+
+    def test_backend_initialized_false_on_failure(self):
+        """backend_initialized is False when _initialize_backend_batch fails."""
+        with (
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+                return_value=True,
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces",
+                return_value=False,
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token",
+                return_value="mock_token",
+            ),
+        ):
+            bm = TraceBatchManager()
+            with patch.object(
+                bm.plus_api, "initialize_trace_batch", return_value=None
+            ):
+                bm.initialize_batch(
+                    user_context={"privacy_level": "standard"},
+                    execution_metadata={"execution_type": "crew"},
+                )
+
+        assert bm.backend_initialized is False
+        assert bm.trace_batch_id is None

lib/devtools/README.md

@@ -8,18 +8,22 @@ Installed automatically via the workspace (`uv sync`). Requires:
 
 - [GitHub CLI](https://cli.github.com/) (`gh`) — authenticated
 - `OPENAI_API_KEY` env var — for release note generation and translation
+- `ENTERPRISE_REPO` env var — GitHub repo for enterprise releases
+- `ENTERPRISE_VERSION_DIRS` env var — comma-separated directories to bump in the enterprise repo
+- `ENTERPRISE_CREWAI_DEP_PATH` env var — path to the pyproject.toml with the `crewai[tools]` pin in the enterprise repo
 
 ## Commands
 
 ### `devtools release <version>`
 
-Full end-to-end release. Bumps versions, creates PRs, tags, and publishes a GitHub release.
+Full end-to-end release. Bumps versions, creates PRs, tags, publishes a GitHub release, and releases the enterprise repo.
 
 ```
 devtools release 1.10.3
-devtools release 1.10.3a1      # pre-release
-devtools release 1.10.3 --no-edit   # skip editing release notes
-devtools release 1.10.3 --dry-run   # preview without changes
+devtools release 1.10.3a1                # pre-release
+devtools release 1.10.3 --no-edit        # skip editing release notes
+devtools release 1.10.3 --dry-run        # preview without changes
+devtools release 1.10.3 --skip-enterprise  # skip enterprise release phase
 ```
 
 **Flow:**
@@ -31,6 +35,10 @@ devtools release 1.10.3 --dry-run   # preview without changes
 5. Updates changelogs (en, pt-BR, ko) and docs version switcher
 6. Creates docs PR against main, polls until merged
 7. Tags main and creates GitHub release
+8. Triggers PyPI publish workflow
+9. Clones enterprise repo, bumps versions and `crewai[tools]` dep, runs `uv sync`
+10. Creates enterprise bump PR, polls until merged
+11. Tags and creates GitHub release on enterprise repo
 
 ### `devtools bump <version>`
 

lib/devtools/src/crewai_devtools/__init__.py

@@ -1,3 +1,3 @@
 """CrewAI development tools."""
 
-__version__ = "1.12.0a2"
+__version__ = "1.13.0rc1"

lib/devtools/src/crewai_devtools/cli.py

@@ -2,10 +2,13 @@
 
 import os
 from pathlib import Path
+import re
 import subprocess
 import sys
+import tempfile
 import time
 from typing import Final, Literal
+from urllib.request import urlopen
 
 import click
 from dotenv import load_dotenv
@@ -153,12 +156,51 @@ def update_version_in_file(file_path: Path, new_version: str) -> bool:
     return False
 
 
-def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool:
+def update_pyproject_version(file_path: Path, new_version: str) -> bool:
+    """Update the [project] version field in a pyproject.toml file.
+
+    Args:
+        file_path: Path to pyproject.toml file.
+        new_version: New version string.
+
+    Returns:
+        True if version was updated, False otherwise.
+    """
+    if not file_path.exists():
+        return False
+
+    content = file_path.read_text()
+    new_content = re.sub(
+        r'^(version\s*=\s*")[^"]+(")',
+        rf"\g<1>{new_version}\2",
+        content,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if new_content != content:
+        file_path.write_text(new_content)
+        return True
+    return False
+
+
+_DEFAULT_WORKSPACE_PACKAGES: Final[list[str]] = [
+    "crewai",
+    "crewai-tools",
+    "crewai-devtools",
+]
+
+
+def update_pyproject_dependencies(
+    file_path: Path,
+    new_version: str,
+    extra_packages: list[str] | None = None,
+) -> bool:
     """Update workspace dependency versions in pyproject.toml.
 
     Args:
         file_path: Path to pyproject.toml file.
         new_version: New version string.
+        extra_packages: Additional package names to update beyond the defaults.
 
     Returns:
         True if any dependencies were updated, False otherwise.
@@ -170,7 +212,7 @@ def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool:
     lines = content.splitlines()
     updated = False
 
-    workspace_packages = ["crewai", "crewai-tools", "crewai-devtools"]
+    workspace_packages = _DEFAULT_WORKSPACE_PACKAGES + (extra_packages or [])
 
     for i, line in enumerate(lines):
         for pkg in workspace_packages:
@@ -431,12 +473,29 @@ def update_changelog(
     return True
 
 
-def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]:
-    """Update crewai dependency versions in CLI template pyproject.toml files.
+def _pin_crewai_deps(content: str, version: str) -> str:
+    """Replace crewai dependency version pins in a pyproject.toml string.
 
     Handles both pinned (==) and minimum (>=) version specifiers,
     as well as extras like [tools].
 
+    Args:
+        content: File content to transform.
+        version: New version string.
+
+    Returns:
+        Transformed content.
+    """
+    return re.sub(
+        r'"crewai(\[tools\])?(==|>=)[^"]*"',
+        lambda m: f'"crewai{(m.group(1) or "")!s}=={version}"',
+        content,
+    )
+
+
+def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]:
+    """Update crewai dependency versions in CLI template pyproject.toml files.
+
     Args:
         templates_dir: Path to the CLI templates directory.
         new_version: New version string.
@@ -444,16 +503,10 @@ def update_template_dependencies(templates_dir: Path, new_version: str) -> list[
     Returns:
         List of paths that were updated.
     """
-    import re
-
     updated = []
     for pyproject in templates_dir.rglob("pyproject.toml"):
         content = pyproject.read_text()
-        new_content = re.sub(
-            r'"crewai(\[tools\])?(==|>=)[^"]*"',
-            lambda m: f'"crewai{(m.group(1) or "")!s}=={new_version}"',
-            content,
-        )
+        new_content = _pin_crewai_deps(content, new_version)
         if new_content != content:
             pyproject.write_text(new_content)
             updated.append(pyproject)
@@ -607,24 +660,26 @@ def get_github_contributors(commit_range: str) -> list[str]:
 # ---------------------------------------------------------------------------
 
 
-def _poll_pr_until_merged(branch_name: str, label: str) -> None:
-    """Poll a GitHub PR until it is merged. Exit if closed without merging."""
+def _poll_pr_until_merged(
+    branch_name: str, label: str, repo: str | None = None
+) -> None:
+    """Poll a GitHub PR until it is merged. Exit if closed without merging.
+
+    Args:
+        branch_name: Branch name to look up the PR.
+        label: Human-readable label for status messages.
+        repo: Optional GitHub repo (owner/name) for cross-repo PRs.
+    """
     console.print(f"[cyan]Waiting for {label} to be merged...[/cyan]")
+    cmd = ["gh", "pr", "view", branch_name]
+    if repo:
+        cmd.extend(["--repo", repo])
+    cmd.extend(["--json", "state", "--jq", ".state"])
+
     while True:
         time.sleep(10)
         try:
-            state = run_command(
-                [
-                    "gh",
-                    "pr",
-                    "view",
-                    branch_name,
-                    "--json",
-                    "state",
-                    "--jq",
-                    ".state",
-                ]
-            )
+            state = run_command(cmd)
         except subprocess.CalledProcessError:
             state = ""
 
@@ -984,8 +1039,360 @@ def _create_tag_and_release(
     console.print(f"[green]✓[/green] Created GitHub {release_type} for {tag_name}")
 
 
-def _trigger_pypi_publish(tag_name: str) -> None:
-    """Trigger the PyPI publish GitHub Actions workflow."""
+_ENTERPRISE_REPO: Final[str | None] = os.getenv("ENTERPRISE_REPO")
+_ENTERPRISE_VERSION_DIRS: Final[tuple[str, ...]] = tuple(
+    d.strip() for d in os.getenv("ENTERPRISE_VERSION_DIRS", "").split(",") if d.strip()
+)
+_ENTERPRISE_CREWAI_DEP_PATH: Final[str | None] = os.getenv("ENTERPRISE_CREWAI_DEP_PATH")
+_ENTERPRISE_EXTRA_PACKAGES: Final[tuple[str, ...]] = tuple(
+    p.strip()
+    for p in os.getenv("ENTERPRISE_EXTRA_PACKAGES", "").split(",")
+    if p.strip()
+)
+
+
+def _update_enterprise_crewai_dep(pyproject_path: Path, version: str) -> bool:
+    """Update the crewai[tools] pin in an enterprise pyproject.toml.
+
+    Args:
+        pyproject_path: Path to the pyproject.toml file.
+        version: New crewai version string.
+
+    Returns:
+        True if the file was modified.
+    """
+    if not pyproject_path.exists():
+        return False
+
+    content = pyproject_path.read_text()
+    new_content = _pin_crewai_deps(content, version)
+    if new_content != content:
+        pyproject_path.write_text(new_content)
+        return True
+    return False
+
+
+_DEPLOYMENT_TEST_REPO: Final[str] = "crewAIInc/crew_deployment_test"
+
+_PYPI_POLL_INTERVAL: Final[int] = 15
+_PYPI_POLL_TIMEOUT: Final[int] = 600
+
+
+def _update_deployment_test_repo(version: str, is_prerelease: bool) -> None:
+    """Update the deployment test repo to pin the new crewai version.
+
+    Clones the repo, updates the crewai[tools] pin in pyproject.toml,
+    regenerates the lockfile, commits, and pushes directly to main.
+
+    Args:
+        version: New crewai version string.
+        is_prerelease: Whether this is a pre-release version.
+    """
+    console.print(
+        f"\n[bold cyan]Updating {_DEPLOYMENT_TEST_REPO} to {version}[/bold cyan]"
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        repo_dir = Path(tmp) / "crew_deployment_test"
+        run_command(["gh", "repo", "clone", _DEPLOYMENT_TEST_REPO, str(repo_dir)])
+        console.print(f"[green]✓[/green] Cloned {_DEPLOYMENT_TEST_REPO}")
+
+        pyproject = repo_dir / "pyproject.toml"
+        content = pyproject.read_text()
+        new_content = re.sub(
+            r'"crewai\[tools\]==[^"]+"',
+            f'"crewai[tools]=={version}"',
+            content,
+        )
+        if new_content == content:
+            console.print(
+                "[yellow]Warning:[/yellow] No crewai[tools] pin found to update"
+            )
+            return
+        pyproject.write_text(new_content)
+        console.print(f"[green]✓[/green] Updated crewai[tools] pin to {version}")
+
+        lock_cmd = [
+            "uv",
+            "lock",
+            "--refresh-package",
+            "crewai",
+            "--refresh-package",
+            "crewai-tools",
+        ]
+        if is_prerelease:
+            lock_cmd.append("--prerelease=allow")
+
+        max_retries = 10
+        for attempt in range(1, max_retries + 1):
+            try:
+                run_command(lock_cmd, cwd=repo_dir)
+                break
+            except subprocess.CalledProcessError:
+                if attempt == max_retries:
+                    console.print(
+                        f"[red]Error:[/red] uv lock failed after {max_retries} attempts"
+                    )
+                    raise
+                console.print(
+                    f"[yellow]uv lock failed (attempt {attempt}/{max_retries}),"
+                    f" retrying in {_PYPI_POLL_INTERVAL}s...[/yellow]"
+                )
+                time.sleep(_PYPI_POLL_INTERVAL)
+        console.print("[green]✓[/green] Lockfile updated")
+
+        run_command(["git", "add", "pyproject.toml", "uv.lock"], cwd=repo_dir)
+        run_command(
+            ["git", "commit", "-m", f"chore: bump crewai to {version}"],
+            cwd=repo_dir,
+        )
+        run_command(["git", "push"], cwd=repo_dir)
+        console.print(f"[green]✓[/green] Pushed to {_DEPLOYMENT_TEST_REPO}")
+
+
+def _wait_for_pypi(package: str, version: str) -> None:
+    """Poll PyPI until a specific package version is available.
+
+    Args:
+        package: PyPI package name.
+        version: Version string to wait for.
+    """
+    url = f"https://pypi.org/pypi/{package}/{version}/json"
+    deadline = time.monotonic() + _PYPI_POLL_TIMEOUT
+
+    console.print(f"[cyan]Waiting for {package}=={version} to appear on PyPI...[/cyan]")
+    while time.monotonic() < deadline:
+        try:
+            with urlopen(url) as resp:  # noqa: S310
+                if resp.status == 200:
+                    console.print(
+                        f"[green]✓[/green] {package}=={version} is available on PyPI"
+                    )
+                    return
+        except Exception:  # noqa: S110
+            pass
+        time.sleep(_PYPI_POLL_INTERVAL)
+
+    console.print(
+        f"[red]Error:[/red] Timed out waiting for {package}=={version} on PyPI"
+    )
+    sys.exit(1)
+
+
+def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> None:
+    """Clone the enterprise repo, bump versions, and create a release PR.
+
+    Expects ENTERPRISE_REPO, ENTERPRISE_VERSION_DIRS, and
+    ENTERPRISE_CREWAI_DEP_PATH to be validated before calling.
+
+    Args:
+        version: New version string.
+        is_prerelease: Whether this is a pre-release version.
+        dry_run: Show what would be done without making changes.
+    """
+    if (
+        not _ENTERPRISE_REPO
+        or not _ENTERPRISE_VERSION_DIRS
+        or not _ENTERPRISE_CREWAI_DEP_PATH
+    ):
+        console.print("[red]Error:[/red] Enterprise env vars not configured")
+        sys.exit(1)
+
+    enterprise_repo: str = _ENTERPRISE_REPO
+    enterprise_dep_path: str = _ENTERPRISE_CREWAI_DEP_PATH
+
+    console.print(
+        f"\n[bold cyan]Phase 3: Releasing {enterprise_repo} {version}[/bold cyan]"
+    )
+
+    if dry_run:
+        console.print(f"[dim][DRY RUN][/dim] Would clone {enterprise_repo}")
+        for d in _ENTERPRISE_VERSION_DIRS:
+            console.print(f"[dim][DRY RUN][/dim] Would update versions in {d}")
+        console.print(
+            f"[dim][DRY RUN][/dim] Would update crewai[tools] dep in "
+            f"{enterprise_dep_path}"
+        )
+        console.print(
+            "[dim][DRY RUN][/dim] Would create bump PR, wait for merge, "
+            "then tag and release"
+        )
+        return
+
+    with tempfile.TemporaryDirectory() as tmp:
+        repo_dir = Path(tmp) / enterprise_repo.split("/")[-1]
+        console.print(f"Cloning {enterprise_repo}...")
+        run_command(["gh", "repo", "clone", enterprise_repo, str(repo_dir)])
+        console.print(f"[green]✓[/green] Cloned {enterprise_repo}")
+
+        # --- bump versions ---
+        for rel_dir in _ENTERPRISE_VERSION_DIRS:
+            pkg_dir = repo_dir / rel_dir
+            if not pkg_dir.exists():
+                console.print(
+                    f"[yellow]Warning:[/yellow] {rel_dir} not found, skipping"
+                )
+                continue
+
+            for vfile in find_version_files(pkg_dir):
+                if update_version_in_file(vfile, version):
+                    console.print(
+                        f"[green]✓[/green] Updated: {vfile.relative_to(repo_dir)}"
+                    )
+
+            pyproject = pkg_dir / "pyproject.toml"
+            if pyproject.exists():
+                if update_pyproject_version(pyproject, version):
+                    console.print(
+                        f"[green]✓[/green] Updated version in: "
+                        f"{pyproject.relative_to(repo_dir)}"
+                    )
+                if update_pyproject_dependencies(
+                    pyproject, version, extra_packages=list(_ENTERPRISE_EXTRA_PACKAGES)
+                ):
+                    console.print(
+                        f"[green]✓[/green] Updated deps in: "
+                        f"{pyproject.relative_to(repo_dir)}"
+                    )
+
+        # --- update crewai[tools] pin ---
+        enterprise_pyproject = repo_dir / enterprise_dep_path
+        if _update_enterprise_crewai_dep(enterprise_pyproject, version):
+            console.print(
+                f"[green]✓[/green] Updated crewai[tools] dep in {enterprise_dep_path}"
+            )
+
+        _wait_for_pypi("crewai", version)
+
+        console.print("\nSyncing workspace...")
+        sync_cmd = [
+            "uv",
+            "sync",
+            "--refresh-package",
+            "crewai",
+            "--refresh-package",
+            "crewai-tools",
+            "--refresh-package",
+            "crewai-files",
+        ]
+        if is_prerelease:
+            sync_cmd.append("--prerelease=allow")
+
+        max_retries = 10
+        for attempt in range(1, max_retries + 1):
+            try:
+                run_command(sync_cmd, cwd=repo_dir)
+                break
+            except subprocess.CalledProcessError:
+                if attempt == max_retries:
+                    console.print(
+                        f"[red]Error:[/red] uv sync failed after {max_retries} attempts"
+                    )
+                    raise
+                console.print(
+                    f"[yellow]uv sync failed (attempt {attempt}/{max_retries}),"
+                    f" retrying in {_PYPI_POLL_INTERVAL}s...[/yellow]"
+                )
+                time.sleep(_PYPI_POLL_INTERVAL)
+        console.print("[green]✓[/green] Workspace synced")
+
+        # --- branch, commit, push, PR ---
+        branch_name = f"feat/bump-version-{version}"
+        run_command(["git", "checkout", "-b", branch_name], cwd=repo_dir)
+        run_command(["git", "add", "."], cwd=repo_dir)
+        run_command(
+            ["git", "commit", "-m", f"feat: bump versions to {version}"],
+            cwd=repo_dir,
+        )
+        console.print("[green]✓[/green] Changes committed")
+
+        run_command(["git", "push", "-u", "origin", branch_name], cwd=repo_dir)
+        console.print("[green]✓[/green] Branch pushed")
+
+        pr_url = run_command(
+            [
+                "gh",
+                "pr",
+                "create",
+                "--repo",
+                enterprise_repo,
+                "--base",
+                "main",
+                "--title",
+                f"feat: bump versions to {version}",
+                "--body",
+                "",
+            ],
+            cwd=repo_dir,
+        )
+        console.print("[green]✓[/green] Enterprise bump PR created")
+        console.print(f"[cyan]PR URL:[/cyan] {pr_url}")
+
+        _poll_pr_until_merged(branch_name, "enterprise bump PR", repo=enterprise_repo)
+
+        # --- tag and release ---
+        run_command(["git", "checkout", "main"], cwd=repo_dir)
+        run_command(["git", "pull"], cwd=repo_dir)
+
+        tag_name = version
+        run_command(
+            ["git", "tag", "-a", tag_name, "-m", f"Release {version}"],
+            cwd=repo_dir,
+        )
+        run_command(["git", "push", "origin", tag_name], cwd=repo_dir)
+        console.print(f"[green]✓[/green] Pushed tag {tag_name}")
+
+        gh_cmd = [
+            "gh",
+            "release",
+            "create",
+            tag_name,
+            "--repo",
+            enterprise_repo,
+            "--title",
+            tag_name,
+            "--notes",
+            f"Release {version}",
+        ]
+        if is_prerelease:
+            gh_cmd.append("--prerelease")
+
+        run_command(gh_cmd)
+        release_type = "prerelease" if is_prerelease else "release"
+        console.print(
+            f"[green]✓[/green] Created GitHub {release_type} for "
+            f"{enterprise_repo} {tag_name}"
+        )
+
+
+def _trigger_pypi_publish(tag_name: str, wait: bool = False) -> None:
+    """Trigger the PyPI publish GitHub Actions workflow.
+
+    Args:
+        tag_name: The release tag to publish.
+        wait: Block until the workflow run completes.
+    """
+    # Capture the latest run ID before triggering so we can detect the new one
+    prev_run_id = ""
+    if wait:
+        try:
+            prev_run_id = run_command(
+                [
+                    "gh",
+                    "run",
+                    "list",
+                    "--workflow=publish.yml",
+                    "--limit=1",
+                    "--json=databaseId",
+                    "--jq=.[0].databaseId",
+                ]
+            )
+        except subprocess.CalledProcessError:
+            console.print(
+                "[yellow]Note:[/yellow] Could not determine previous workflow run; "
+                "continuing without previous run ID"
+            )
+
     with console.status("[cyan]Triggering PyPI publish workflow..."):
         try:
             run_command(
@@ -1003,6 +1410,42 @@ def _trigger_pypi_publish(tag_name: str) -> None:
             sys.exit(1)
     console.print("[green]✓[/green] Triggered PyPI publish workflow")
 
+    if wait:
+        console.print("[cyan]Waiting for PyPI publish workflow to complete...[/cyan]")
+        run_id = ""
+        deadline = time.monotonic() + 120
+        while time.monotonic() < deadline:
+            time.sleep(5)
+            try:
+                run_id = run_command(
+                    [
+                        "gh",
+                        "run",
+                        "list",
+                        "--workflow=publish.yml",
+                        "--limit=1",
+                        "--json=databaseId",
+                        "--jq=.[0].databaseId",
+                    ]
+                )
+            except subprocess.CalledProcessError:
+                continue
+            if run_id and run_id != prev_run_id:
+                break
+
+        if not run_id or run_id == prev_run_id:
+            console.print(
+                "[red]Error:[/red] Could not find the PyPI publish workflow run"
+            )
+            sys.exit(1)
+
+        try:
+            run_command(["gh", "run", "watch", run_id, "--exit-status"])
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]✗[/red] PyPI publish workflow failed: {e}")
+            sys.exit(1)
+        console.print("[green]✓[/green] PyPI publish workflow completed")
+
 
 # ---------------------------------------------------------------------------
 # CLI commands
@@ -1032,6 +1475,15 @@ def bump(version: str, dry_run: bool, no_push: bool, no_commit: bool) -> None:
         no_push: Don't push changes to remote.
         no_commit: Don't commit changes (just update files).
     """
+    console.print(
+        f"\n[yellow]Note:[/yellow] [bold]devtools bump[/bold] only bumps versions "
+        f"in this repo. It will not tag, publish to PyPI, or release enterprise.\n"
+        f"If you want a full end-to-end release, run "
+        f"[bold]devtools release {version}[/bold] instead."
+    )
+    if not Confirm.ask("Continue with bump only?", default=True):
+        sys.exit(0)
+
     try:
         check_gh_installed()
 
@@ -1136,6 +1588,16 @@ def tag(dry_run: bool, no_edit: bool) -> None:
         dry_run: Show what would be done without making changes.
         no_edit: Skip editing release notes.
     """
+    console.print(
+        "\n[yellow]Note:[/yellow] [bold]devtools tag[/bold] only tags and creates "
+        "a GitHub release for this repo. It will not bump versions, publish to "
+        "PyPI, or release enterprise.\n"
+        "If you want a full end-to-end release, run "
+        "[bold]devtools release <version>[/bold] instead."
+    )
+    if not Confirm.ask("Continue with tag only?", default=True):
+        sys.exit(0)
+
     try:
         cwd = Path.cwd()
         lib_dir = cwd / "lib"
@@ -1226,24 +1688,75 @@ def tag(dry_run: bool, no_edit: bool) -> None:
     "--dry-run", is_flag=True, help="Show what would be done without making changes"
 )
 @click.option("--no-edit", is_flag=True, help="Skip editing release notes")
-def release(version: str, dry_run: bool, no_edit: bool) -> None:
+@click.option(
+    "--skip-enterprise",
+    is_flag=True,
+    help="Skip the enterprise release phase",
+)
+@click.option(
+    "--skip-to-enterprise",
+    is_flag=True,
+    help="Skip phases 1 & 2, run only the enterprise release phase",
+)
+def release(
+    version: str,
+    dry_run: bool,
+    no_edit: bool,
+    skip_enterprise: bool,
+    skip_to_enterprise: bool,
+) -> None:
     """Full release: bump versions, tag, and publish a GitHub release.
 
     Combines bump and tag into a single workflow. Creates a version bump PR,
     waits for it to be merged, then generates release notes, updates docs,
-    creates the tag, and publishes a GitHub release.
+    creates the tag, and publishes a GitHub release. Then bumps versions and
+    releases the enterprise repo.
 
     Args:
         version: New version to set (e.g., 1.0.0, 1.0.0a1).
         dry_run: Show what would be done without making changes.
         no_edit: Skip editing release notes.
+        skip_enterprise: Skip the enterprise release phase.
+        skip_to_enterprise: Skip phases 1 & 2, run only the enterprise release phase.
     """
     try:
         check_gh_installed()
 
+        if skip_enterprise and skip_to_enterprise:
+            console.print(
+                "[red]Error:[/red] Cannot use both --skip-enterprise "
+                "and --skip-to-enterprise"
+            )
+            sys.exit(1)
+
+        if not skip_enterprise or skip_to_enterprise:
+            missing: list[str] = []
+            if not _ENTERPRISE_REPO:
+                missing.append("ENTERPRISE_REPO")
+            if not _ENTERPRISE_VERSION_DIRS:
+                missing.append("ENTERPRISE_VERSION_DIRS")
+            if not _ENTERPRISE_CREWAI_DEP_PATH:
+                missing.append("ENTERPRISE_CREWAI_DEP_PATH")
+            if missing:
+                console.print(
+                    f"[red]Error:[/red] Missing required environment variable(s): "
+                    f"{', '.join(missing)}\n"
+                    f"Set them or pass --skip-enterprise to skip the enterprise release."
+                )
+                sys.exit(1)
+
         cwd = Path.cwd()
         lib_dir = cwd / "lib"
 
+        is_prerelease = _is_prerelease(version)
+
+        if skip_to_enterprise:
+            _release_enterprise(version, is_prerelease, dry_run)
+            console.print(
+                f"\n[green]✓[/green] Enterprise release [bold]{version}[/bold] complete!"
+            )
+            return
+
         if not dry_run:
             console.print("Checking git status...")
             check_git_clean()
@@ -1337,7 +1850,11 @@ def release(version: str, dry_run: bool, no_edit: bool) -> None:
 
         if not dry_run:
             _create_tag_and_release(tag_name, release_notes, is_prerelease)
-            _trigger_pypi_publish(tag_name)
+            _trigger_pypi_publish(tag_name, wait=True)
+            _update_deployment_test_repo(version, is_prerelease)
+
+        if not skip_enterprise:
+            _release_enterprise(version, is_prerelease, dry_run)
 
         console.print(f"\n[green]✓[/green] Release [bold]{version}[/bold] complete!")