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

docs/docs.json

@@ -79,6 +79,101 @@
                   "en/quickstart"
                 ]
               },
+              {
+                "group": "AI Docs",
+                "pages": [
+                  "en/ai/overview",
+                  {
+                    "group": "Flows",
+                    "icon": "arrow-progress",
+                    "pages": [
+                      "en/ai/flows/index",
+                      "en/ai/flows/reference",
+                      "en/ai/flows/patterns",
+                      "en/ai/flows/troubleshooting",
+                      "en/ai/flows/examples"
+                    ]
+                  },
+                  {
+                    "group": "Agents",
+                    "icon": "user",
+                    "pages": [
+                      "en/ai/agents/index",
+                      "en/ai/agents/reference",
+                      "en/ai/agents/patterns",
+                      "en/ai/agents/troubleshooting",
+                      "en/ai/agents/examples"
+                    ]
+                  },
+                  {
+                    "group": "Crews",
+                    "icon": "users",
+                    "pages": [
+                      "en/ai/crews/index",
+                      "en/ai/crews/reference",
+                      "en/ai/crews/patterns",
+                      "en/ai/crews/troubleshooting",
+                      "en/ai/crews/examples"
+                    ]
+                  },
+                  {
+                    "group": "LLMs",
+                    "icon": "microchip-ai",
+                    "pages": [
+                      "en/ai/llms/index",
+                      "en/ai/llms/reference",
+                      "en/ai/llms/patterns",
+                      "en/ai/llms/troubleshooting",
+                      "en/ai/llms/examples"
+                    ]
+                  },
+                  {
+                    "group": "Memory",
+                    "icon": "database",
+                    "pages": [
+                      "en/ai/memory/index",
+                      "en/ai/memory/reference",
+                      "en/ai/memory/patterns",
+                      "en/ai/memory/troubleshooting",
+                      "en/ai/memory/examples"
+                    ]
+                  },
+                  {
+                    "group": "Tools",
+                    "icon": "wrench",
+                    "pages": [
+                      "en/ai/tools/index",
+                      "en/ai/tools/reference",
+                      "en/ai/tools/patterns",
+                      "en/ai/tools/troubleshooting",
+                      "en/ai/tools/examples"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Core Concepts",
+                "pages": [
+                  "en/concepts/agents",
+                  "en/concepts/tasks",
+                  "en/concepts/crews",
+                  "en/concepts/flows",
+                  "en/concepts/production-architecture",
+                  "en/concepts/knowledge",
+                  "en/concepts/llms",
+                  "en/concepts/files",
+                  "en/concepts/processes",
+                  "en/concepts/collaboration",
+                  "en/concepts/training",
+                  "en/concepts/memory",
+                  "en/concepts/reasoning",
+                  "en/concepts/planning",
+                  "en/concepts/testing",
+                  "en/concepts/cli",
+                  "en/concepts/tools",
+                  "en/concepts/event-listener"
+                ]
+              },
               {
                 "group": "Guides",
                 "pages": [
@@ -128,29 +223,6 @@
                   }
                 ]
               },
-              {
-                "group": "Core Concepts",
-                "pages": [
-                  "en/concepts/agents",
-                  "en/concepts/tasks",
-                  "en/concepts/crews",
-                  "en/concepts/flows",
-                  "en/concepts/production-architecture",
-                  "en/concepts/knowledge",
-                  "en/concepts/llms",
-                  "en/concepts/files",
-                  "en/concepts/processes",
-                  "en/concepts/collaboration",
-                  "en/concepts/training",
-                  "en/concepts/memory",
-                  "en/concepts/reasoning",
-                  "en/concepts/planning",
-                  "en/concepts/testing",
-                  "en/concepts/cli",
-                  "en/concepts/tools",
-                  "en/concepts/event-listener"
-                ]
-              },
               {
                 "group": "MCP Integration",
                 "pages": [
@@ -331,6 +403,7 @@
                   "en/learn/human-input-on-execution",
                   "en/learn/human-in-the-loop",
                   "en/learn/human-feedback-in-flows",
+                  "en/learn/flowstate-chat-history",
                   "en/learn/kickoff-async",
                   "en/learn/kickoff-for-each",
                   "en/learn/llm-connections",
@@ -483,7 +556,6 @@
               {
                 "group": "Examples",
                 "pages": [
-                  "en/examples/example",
                   "en/examples/cookbooks"
                 ]
               }
@@ -1482,6 +1554,18 @@
       "source": "/api-reference",
       "destination": "/en/api-reference/introduction"
     },
+    {
+      "source": "/",
+      "destination": "/en/introduction"
+    },
+    {
+      "source": "/en",
+      "destination": "/en/introduction"
+    },
+    {
+      "source": "/en/examples/example",
+      "destination": "/en/examples/cookbooks"
+    },
     {
       "source": "/introduction",
       "destination": "/en/introduction"
@@ -1578,4 +1662,4 @@
       "reddit": "https://www.reddit.com/r/crewAIInc/"
     }
   }
-}
+}

docs/en/ai/agents/examples.mdx

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

docs/en/ai/agents/index.mdx

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

docs/en/ai/agents/patterns.mdx

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

docs/en/ai/agents/reference.mdx

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

docs/en/ai/agents/troubleshooting.mdx

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

docs/en/ai/crews/examples.mdx

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

docs/en/ai/crews/index.mdx

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

docs/en/ai/crews/patterns.mdx

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

docs/en/ai/crews/reference.mdx

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

docs/en/ai/crews/troubleshooting.mdx

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

docs/en/ai/flows/examples.mdx

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

docs/en/ai/flows/index.mdx

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

docs/en/ai/flows/patterns.mdx

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

docs/en/ai/flows/reference.mdx

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

docs/en/ai/flows/troubleshooting.mdx

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

docs/en/ai/llms/examples.mdx

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

docs/en/ai/llms/index.mdx

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

docs/en/ai/llms/patterns.mdx

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

docs/en/ai/llms/reference.mdx

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

docs/en/ai/llms/troubleshooting.mdx

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

docs/en/ai/memory/examples.mdx

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

docs/en/ai/memory/index.mdx

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

docs/en/ai/memory/patterns.mdx

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

docs/en/ai/memory/reference.mdx

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

docs/en/ai/memory/troubleshooting.mdx

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

docs/en/ai/overview.mdx

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

docs/en/ai/tools/examples.mdx

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

docs/en/ai/tools/index.mdx

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

docs/en/ai/tools/patterns.mdx

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

docs/en/ai/tools/reference.mdx

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

docs/en/ai/tools/troubleshooting.mdx

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

docs/en/concepts/agents.mdx

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

docs/en/concepts/crews.mdx

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

docs/en/concepts/flows.mdx

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

docs/en/concepts/memory.mdx

@@ -156,6 +156,7 @@ class ResearchFlow(Flow):
 ```
 
 See the [Flows documentation](/concepts/flows) for more on memory in Flows.
+For a production-style conversational pattern that combines Flow state and memory, see [Flowstate Chat History](/en/learn/flowstate-chat-history).
 
 
 ## Hierarchical Scopes

docs/en/concepts/planning.mdx

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

docs/en/concepts/processes.mdx

@@ -12,11 +12,20 @@ mode: "wide"
   These processes ensure tasks are distributed and executed efficiently, in alignment with a predefined strategy.
 </Tip>
 
+## When to Use Each Process
+
+- Use `sequential` when task order is fixed and outputs feed directly into the next task.
+- Use `hierarchical` when you need a manager to delegate and validate work dynamically.
+
+## When Not to Use Hierarchical
+
+- You do not need dynamic delegation.
+- You cannot provide a reliable `manager_llm` or `manager_agent`.
+
 ## Process Implementations
 
 - **Sequential**: Executes tasks sequentially, ensuring tasks are completed in an orderly progression.
 - **Hierarchical**: Organizes tasks in a managerial hierarchy, where tasks are delegated and executed based on a structured chain of command. A manager language model (`manager_llm`) or a custom manager agent (`manager_agent`) must be specified in the crew to enable the hierarchical process, facilitating the creation and management of tasks by the manager.
-- **Consensual Process (Planned)**: Aiming for collaborative decision-making among agents on task execution, this process type introduces a democratic approach to task management within CrewAI. It is planned for future development and is not currently implemented in the codebase.
 
 ## The Role of Processes in Teamwork
 Processes enable individual agents to operate as a cohesive unit, streamlining their efforts to achieve common objectives with efficiency and coherence.
@@ -59,9 +68,17 @@ Emulates a corporate hierarchy, CrewAI allows specifying a custom manager agent
 
 ## Process Class: Detailed Overview
 
-The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`). The consensual process is planned for future inclusion, emphasizing our commitment to continuous development and innovation.
+The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`).
 
 ## Conclusion
 
 The structured collaboration facilitated by processes within CrewAI is crucial for enabling systematic teamwork among agents. 
-This documentation has been updated to reflect the latest features, enhancements, and the planned integration of the Consensual Process, ensuring users have access to the most current and comprehensive information.
+## Common Failure Modes
+
+### Hierarchical process fails at startup
+- Cause: missing `manager_llm` or `manager_agent`.
+- Fix: provide one of them explicitly in crew configuration.
+
+### Sequential process produces weak outputs
+- Cause: task boundaries/context are underspecified.
+- Fix: improve task descriptions, expected outputs, and task context chaining.

docs/en/concepts/testing.mdx

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

docs/en/concepts/tools.mdx

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

docs/en/examples/cookbooks.mdx

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

docs/en/examples/example.mdx

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

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

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

docs/en/index.mdx

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

docs/en/introduction.mdx

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

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

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