rasa-pro 3.14.0a16__py3-none-any.whl → 3.14.0a18__py3-none-any.whl

rasa/builder/project_generator.py

@@ -5,23 +5,25 @@ import os
 import shutil
 from pathlib import Path
 from textwrap import dedent
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Generator, List, Optional
 
 import structlog
 
 from rasa.builder import config
 from rasa.builder.exceptions import ProjectGenerationError, ValidationError
 from rasa.builder.llm_service import get_skill_generation_messages, llm_service
+from rasa.builder.logging_utils import capture_exception_with_context
 from rasa.builder.models import BotFiles
 from rasa.builder.project_info import ProjectInfo, ensure_first_used, load_project_info
 from rasa.builder.template_cache import copy_cache_for_template_if_available
 from rasa.builder.training_service import TrainingInput
 from rasa.builder.validation_service import validate_project
 from rasa.cli.scaffold import ProjectTemplateName, create_initial_project
+from rasa.shared.constants import DEFAULT_MODELS_PATH
 from rasa.shared.core.flows import yaml_flows_io
 from rasa.shared.importers.importer import TrainingDataImporter
 from rasa.shared.utils.yaml import dump_obj_as_yaml_to_string
-from rasa.utils.io import subpath
+from rasa.utils.io import InvalidPathException, subpath
 
 structlogger = structlog.get_logger()
 
@@ -60,7 +62,7 @@ class ProjectGenerator:
         create_initial_project(self.project_folder.as_posix(), template)
         # If a local cache for this template exists, copy it into the project.
         # We no longer download here to avoid blocking project creation.
-        copy_cache_for_template_if_available(template, self.project_folder)
+        await copy_cache_for_template_if_available(template, self.project_folder)
         # needs to happen after caching, as we download/copy .rasa and that would
         # overwrite the project info file in .rasa
         ensure_first_used(self.project_folder)
@@ -233,25 +235,9 @@ class ProjectGenerator:
         """
         bot_files: BotFiles = {}
 
-        for file in self.project_folder.glob("**/*"):
-            # Skip directories
-            if not file.is_file():
-                continue
-
+        for file in self.bot_file_paths():
             relative_path = file.relative_to(self.project_folder)
 
-            # Skip hidden files and directories (any path component starting with '.')
-            # as well as `__pycache__` folders
-            if any(part.startswith(".") for part in relative_path.parts):
-                continue
-
-            if "__pycache__" in relative_path.parts:
-                continue
-
-            # exclude the project_folder / models folder
-            if relative_path.parts[0] == "models":
-                continue
-
             # Exclude the docs directory if specified
             if exclude_docs_directory and relative_path.parts[0] == "docs":
                 continue
@@ -263,7 +249,6 @@ class ProjectGenerator:
                 ]
                 if file.suffix.lstrip(".").lower() not in allowed_file_extensions:
                     continue
-
             # Read file content and store with relative path as key
             try:
                 bot_files[relative_path.as_posix()] = file.read_text(encoding="utf-8")
@@ -274,9 +259,40 @@ class ProjectGenerator:
                     file_path=file.as_posix(),
                 )
                 bot_files[relative_path.as_posix()] = None
-
         return bot_files
 
+    def is_restricted_path(self, path: Path) -> bool:
+        """Check if the path is restricted.
+
+        These paths are excluded from deletion and editing by the user.
+        """
+        relative_path = path.relative_to(self.project_folder)
+
+        # Skip hidden files and directories (any path component starting with '.')
+        # as well as `__pycache__` folders
+        if any(part.startswith(".") for part in relative_path.parts):
+            return True
+
+        if "__pycache__" in relative_path.parts:
+            return True
+
+        # exclude the project_folder / models folder
+        if relative_path.parts[0] == DEFAULT_MODELS_PATH:
+            return True
+
+        return False
+
+    def bot_file_paths(
+        self,
+    ) -> Generator[Path, None, None]:
+        """Get the paths of all bot files."""
+        for file in self.project_folder.glob("**/*"):
+            # Skip directories
+            if not file.is_file() or self.is_restricted_path(file):
+                continue
+
+            yield file
+
     def _get_bot_data_for_llm(self) -> Dict[str, Any]:
         """Get the current bot data for the LLM."""
         file_importer = self._create_importer()
@@ -321,7 +337,7 @@ class ProjectGenerator:
     def update_bot_files(self, files: Dict[str, Optional[str]]) -> None:
         """Update bot files with new content by writing to disk."""
         for filename, content in files.items():
-            file_path = Path(subpath(self.project_folder, filename))
+            file_path = Path(subpath(str(self.project_folder), filename))
             # Disallow updates inside .rasa project metadata directory
             if any(
                 part.startswith(".")
@@ -332,6 +348,95 @@ class ProjectGenerator:
             file_path.parent.mkdir(parents=True, exist_ok=True)
             file_path.write_text(content, encoding="utf-8")
 
+    def ensure_all_files_are_writable(self, files: Dict[str, Optional[str]]) -> None:
+        """Ensure all files are writable."""
+        for filename, content in files.items():
+            file_path = Path(subpath(str(self.project_folder), filename))
+            if self.is_restricted_path(file_path):
+                raise InvalidPathException(
+                    f"This file or folder is restricted from editing: {file_path}"
+                )
+
+    def replace_all_bot_files(self, files: Dict[str, Optional[str]]) -> None:
+        """Replace all bot files with new content, deleting files not in the request.
+
+        Files/folders starting with .rasa/ or models/ are excluded from deletion.
+
+        Args:
+            files: Dictionary mapping file names to their content
+        """
+        self.ensure_all_files_are_writable(files)
+        # Collect all existing files - any files not in the new `files` dict will be
+        # deleted from this set
+        existing_files = set(path.as_posix() for path in self.bot_file_paths())
+
+        # Write all new files
+        for filename, content in files.items():
+            if content is None:
+                continue
+
+            file_path = Path(subpath(str(self.project_folder), filename))
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            try:
+                file_path.write_text(content, encoding="utf-8")
+            except Exception as e:
+                # Log write failure and avoid deleting an existing file by mistake
+                capture_exception_with_context(
+                    e,
+                    "project_generator.replace_all_bot_files.write_error",
+                    extra={"file_path": file_path},
+                )
+                if file_path.as_posix() in existing_files:
+                    # Keep the original file if it already existed
+                    existing_files.discard(file_path.as_posix())
+                continue
+
+            # Remove from deletion set since this file is in the new set of files
+            existing_files.discard(file_path.as_posix())
+
+        # Delete files that weren't in the request
+        for file_to_delete in existing_files:
+            file_path = Path(file_to_delete)
+            try:
+                file_path.unlink()
+            except Exception as e:
+                capture_exception_with_context(
+                    e,
+                    "project_generator.replace_all_bot_files.delete_error",
+                    extra={"file_path": file_path},
+                )
+
+        # Clean up empty directories (except excluded ones)
+        self._cleanup_empty_directories()
+
+    def _cleanup_empty_directories(self) -> None:
+        """Remove empty directories from the project folder.
+
+        Excludes hidden files and directories, and models/ from cleanup.
+        """
+        # Walk directories in reverse order (deepest first)
+        for dirpath, dirnames, filenames in os.walk(self.project_folder, topdown=False):
+            # Skip if this is the project root
+            if dirpath == str(self.project_folder):
+                continue
+
+            if self.is_restricted_path(Path(dirpath)):
+                continue
+
+            relative_path = Path(dirpath).relative_to(self.project_folder)
+
+            try:
+                # Only remove if directory is empty
+                if not os.listdir(dirpath):
+                    os.rmdir(dirpath)
+            except Exception as e:
+                capture_exception_with_context(
+                    e,
+                    "project_generator.cleanup_empty_directories.error",
+                    extra={"directory": relative_path.as_posix()},
+                )
+
     def cleanup(self) -> None:
         """Cleanup the project folder."""
         # remove all the files and folders in the project folder resulting
@@ -339,6 +444,8 @@ class ProjectGenerator:
         for filename in os.listdir(self.project_folder):
             file_path = os.path.join(self.project_folder, filename)
             try:
+                if filename == "lost+found":
+                    continue
                 if os.path.isfile(file_path) or os.path.islink(file_path):
                     os.unlink(file_path)
                 elif os.path.isdir(file_path):

rasa/builder/service.py

@@ -54,8 +54,8 @@ from rasa.builder.guardrails.utils import (
 from rasa.builder.job_manager import job_manager
 from rasa.builder.jobs import (
     run_prompt_to_bot_job,
+    run_replace_all_files_job,
     run_template_to_bot_job,
-    run_update_files_job,
 )
 from rasa.builder.llm_service import llm_service
 from rasa.builder.logging_utils import (
@@ -512,26 +512,31 @@ async def get_bot_files(request: Request) -> HTTPResponse:
         )
 
 
-@bp.route("/files", methods=["PUT"])
-@openapi.summary("Update bot files")
+@bp.route("/files", methods=["POST"])
+@openapi.summary("Replace all bot files")
 @openapi.description(
-    "Updates the bot configuration files and retrains the model. "
-    "Returns immediately with a job ID. Connect to `/job-events/<job_id>` "
-    "for real-time SSE progress tracking."
+    "Replaces all bot configuration files with the provided files, deletes any "
+    "files not included in the request (excluding .rasa/ and models/ directories), "
+    "and retrains the model. Returns immediately with a job ID. Connect to "
+    "`/job-events/<job_id>` for real-time SSE progress tracking."
     "\n\n"
+    "**File Management:**\n"
+    "- All files in the request are written to the project folder\n"
+    "- Files not included in the request are deleted from the project\n"
+    "- Files/folders starting with `.rasa/` or `models/` are excluded from deletion\n\n"
     "**SSE Event Flow:** (available via /job-events/<job_id>)\n"
     "1. `received` - Request received by server\n"
     "2. `validating` - Validating bot configuration files\n"
     "3. `validation_success` - File validation completed successfully\n"
     "4. `training` - Training the bot model with updated files\n"
     "5. `train_success` - Model training completed\n"
-    "6. `done` - Bot files update completed\n\n"
+    "6. `done` - Bot files replacement completed\n\n"
     "**Error Events (can occur at any time):**\n"
     "- `validation_error` - Bot configuration files are invalid\n"
     "- `train_error` - Files updated but training failed\n"
     "- `error` - Unexpected error occurred\n\n"
     "**Usage:**\n"
-    "1. Send PUT request with Content-Type: application/json\n"
+    "1. Send POST request with Content-Type: application/json\n"
     "2. The response will be a JSON object `{job_id: ...}`\n"
     "3. Connect to `/job-events/<job_id>` for a server-sent event stream of progress."
 )
@@ -539,9 +544,11 @@ async def get_bot_files(request: Request) -> HTTPResponse:
 @openapi.body(
     {"application/json": {str: Optional[str]}},
     description=(
-        "A dictionary mapping file names to their updated content. "
-        "The file name should be the name of the file in the project folder. "
-        "Files that are not in the request will not be updated."
+        "A dictionary mapping file names to their complete content. "
+        "All files in the project will be replaced with these files. "
+        "Files not included in the request will be deleted from the project "
+        "(except for .rasa/ and models/ directories). "
+        "The file name should be the relative path from the project root."
     ),
     required=True,
     example={
@@ -558,6 +565,10 @@ async def get_bot_files(request: Request) -> HTTPResponse:
             "  - name: CountVectorsFeaturizer\n"
             "policies:\n  - name: MemoizationPolicy\n  - name: RulePolicy"
         ),
+        "data/nlu.yml": (
+            "version: '3.1'\n"
+            "nlu:\n- intent: greet\n  examples: |\n    - hello\n    - hi"
+        ),
     },
 )
 @openapi.response(
@@ -565,7 +576,7 @@ async def get_bot_files(request: Request) -> HTTPResponse:
     {"application/json": model_to_schema(JobCreateResponse)},
     description=(
         "Job created. Poll or subscribe to /job-events/<job_id> "
-        "for progress and SSE updates."
+        "for progress and SSE updates on file replacement and training."
     ),
 )
 @openapi.response(
@@ -607,8 +618,8 @@ async def get_bot_files(request: Request) -> HTTPResponse:
     schema=str,
 )
 @protected()
-async def update_bot_files(request: Request) -> HTTPResponse:
-    """Update bot files with server-sent events for progress tracking."""
+async def replace_all_bot_files(request: Request) -> HTTPResponse:
+    """Replace all bot files with server-sent events for progress tracking."""
     try:
         bot_files = request.json
     except Exception as exc:
@@ -621,17 +632,17 @@ async def update_bot_files(request: Request) -> HTTPResponse:
 
     try:
         job = job_manager.create_job()
-        request.app.add_task(run_update_files_job(request.app, job, bot_files))
+        request.app.add_task(run_replace_all_files_job(request.app, job, bot_files))
         return response.json(JobCreateResponse(job_id=job.id).model_dump(), status=200)
     except Exception as exc:
         capture_exception_with_context(
             exc,
-            "bot_builder_service.update_bot_files.unexpected_error",
-            tags={"endpoint": "/api/files", "method": "PUT"},
+            "bot_builder_service.replace_all_bot_files.unexpected_error",
+            tags={"endpoint": "/api/files", "method": "POST"},
         )
         return response.json(
             ApiErrorResponse(
-                error="Failed to update bot files", details={"error": str(exc)}
+                error="Failed to replace bot files", details={"error": str(exc)}
             ).model_dump(),
             status=HTTPStatus.INTERNAL_SERVER_ERROR,
         )
@@ -1144,6 +1155,11 @@ async def copilot(request: Request) -> None:
                 latency_ms=int((time.perf_counter() - start_timestamp) * 1000),
                 system_message=generation_context.system_message,
                 chat_history=generation_context.chat_history,
+                last_user_message=(
+                    req.last_message.get_text_content()
+                    if (req.last_message and req.last_message.role == ROLE_USER)
+                    else None
+                ),
                 **copilot_client.usage_statistics.model_dump(),
             )
         )

rasa/builder/template_cache.py

@@ -1,83 +1,26 @@
-import asyncio
 import os
-import shutil
-import tarfile
-import tempfile
 from pathlib import Path
-from typing import Generator
 
 import aiofiles
-import aiohttp
+import aiofiles.os
+import aioshutil
 import structlog
-from sanic import Sanic
 
-import rasa.version
-from rasa.builder.logging_utils import capture_exception_with_context
 from rasa.cli.scaffold import ProjectTemplateName
 
 structlogger = structlog.get_logger()
 
-CACHE_BUCKET_URL = "https://trained-templates.s3.us-east-1.amazonaws.com"
 
 # Root directory for storing downloaded template caches on disk.
-_CACHE_ROOT_DIR = Path(
-    os.getenv(
-        "RASA_TEMPLATE_CACHE_DIR",
-        Path.home().joinpath(".rasa", "template-cache").as_posix(),
-    )
-)
+_CACHE_ROOT_DIR = Path(os.getenv("RASA_TEMPLATE_CACHE_DIR", "/templates"))
 
 
 def _template_cache_dir(template: ProjectTemplateName) -> Path:
     """Return the local cache directory for a given template and version."""
-    return _CACHE_ROOT_DIR / rasa.version.__version__ / template.value
+    return _CACHE_ROOT_DIR / template.value
 
 
-def _cache_root_dir() -> Path:
-    return Path(
-        os.getenv(
-            "RASA_TEMPLATE_CACHE_DIR",
-            Path.home().joinpath(".rasa", "template-cache").as_posix(),
-        )
-    )
-
-
-def _safe_tar_members(
-    tar: tarfile.TarFile, destination_directory: Path
-) -> Generator[tarfile.TarInfo, None, None]:
-    """Yield safe members for extraction to prevent path traversal and links.
-
-    Args:
-        tar: Open tar file handle
-        destination_directory: Directory to which files will be extracted
-
-    Yields:
-        Members that are safe to extract within destination_directory
-    """
-    base_path = destination_directory.resolve()
-
-    for member in tar.getmembers():
-        name = member.name
-        # Skip empty names and absolute paths
-        if not name or name.startswith("/") or name.startswith("\\"):
-            continue
-
-        # Disallow symlinks and hardlinks
-        if member.issym() or member.islnk():
-            continue
-
-        # Compute the final path and ensure it's within base_path
-        target_path = (base_path / name).resolve()
-        try:
-            target_path.relative_to(base_path)
-        except ValueError:
-            # Member would escape the destination directory
-            continue
-
-        yield member
-
-
-def _copytree(src: Path, dst: Path) -> None:
+async def _copytree(src: Path, dst: Path) -> None:
     """Copy directory tree from src to dst, merging into dst.
 
     Existing files are overwritten. Hidden files and directories are included, as
@@ -87,132 +30,14 @@ def _copytree(src: Path, dst: Path) -> None:
     for root, dirs, files in os.walk(src):
         rel_path = Path(root).relative_to(src)
         target_dir = dst / rel_path
-        target_dir.mkdir(parents=True, exist_ok=True)
+        await aiofiles.os.makedirs(target_dir, exist_ok=True)
         for filename in files:
             src_file = Path(root) / filename
             dst_file = target_dir / filename
-            shutil.copy2(src_file, dst_file)
-
-
-async def download_cache_for_template(
-    template: ProjectTemplateName, target_dir: str
-) -> None:
-    # get a temp path for the cache file download
-    temporary_cache_file = tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False)
-
-    try:
-        url = f"{CACHE_BUCKET_URL}/{rasa.version.__version__}-{template.value}.tar.gz"
-        async with aiohttp.ClientSession() as session:
-            async with session.get(url) as response:
-                response.raise_for_status()
-                async with aiofiles.open(temporary_cache_file.name, "wb") as f:
-                    async for chunk in response.content.iter_chunked(1024 * 1024):
-                        await f.write(chunk)
-
-        # extract the cache to the project folder using safe member filtering
-        with tarfile.open(temporary_cache_file.name, "r:gz") as tar:
-            destination = Path(target_dir)
-            destination.mkdir(parents=True, exist_ok=True)
-            tar.extractall(
-                path=destination,
-                members=_safe_tar_members(tar, destination),
-            )
-
-        structlogger.info(
-            "project_generator.download_cache_for_template.success",
-            template=template,
-            event_info=(
-                "Downloaded cache for template, extracted to target directory."
-            ),
-            target_dir=target_dir,
-        )
-    except aiohttp.ClientResponseError as e:
-        if e.status == 403:
-            structlogger.debug(
-                "project_generator.download_cache_for_template.no_cache_found",
-                template=template,
-                event_info=("No cache found for template, continuing without it."),
-                target_dir=target_dir,
-            )
-        else:
-            capture_exception_with_context(
-                e,
-                "project_generator.download_cache_for_template.response_error",
-                extra={
-                    "template": template.value,
-                    "status": str(e.status),
-                    "target_dir": target_dir,
-                },
-            )
-    except Exception as exc:
-        capture_exception_with_context(
-            exc,
-            "project_generator.download_cache_for_template.unexpected_error",
-            extra={"template": template.value, "target_dir": target_dir},
-        )
-    finally:
-        # Clean up the temporary file
-        try:
-            Path(temporary_cache_file.name).unlink(missing_ok=True)
-        except Exception as exc:
-            structlogger.debug(
-                "project_generator.download_cache_for_template.cleanup_error",
-                error=str(exc),
-                template=template,
-                event_info=("Failed to cleanup cache for template, ignoring."),
-            )
-
-
-async def background_download_template_caches(
-    app: Sanic, loop: asyncio.AbstractEventLoop
-) -> None:
-    """Kick off background downloads of template caches if enabled."""
-    try:
-        structlogger.info(
-            "builder.main.background_cache_download.start",
-            event_info=(
-                "Starting background download of template caches for this " "version"
-            ),
-        )
-
-        # Ensure cache root exists
-        _cache_root_dir().mkdir(parents=True, exist_ok=True)
-
-        async def _download(template: ProjectTemplateName) -> None:
-            try:
-                target_dir = _template_cache_dir(template)
-                if target_dir.exists() and any(target_dir.iterdir()):
-                    structlogger.debug(
-                        "builder.main.background_cache_download.skipped",
-                        template=template,
-                        event_info=(
-                            "Skipping download of template cache because it "
-                            "already exists."
-                        ),
-                        target_dir=target_dir,
-                    )
-                    return
-
-                target_dir.mkdir(parents=True, exist_ok=True)
-                await download_cache_for_template(template, target_dir.as_posix())
-            except Exception as exc:
-                structlogger.debug(
-                    "builder.main.background_cache_download.error",
-                    template=template,
-                    error=str(exc),
-                )
-
-        # schedule downloads concurrently without blocking startup
-        for template in ProjectTemplateName:
-            loop.create_task(_download(template))
-    except Exception as exc:
-        structlogger.debug(
-            "builder.main.background_cache_download.unexpected_error",
-            error=str(exc),
-        )
+            await aioshutil.copy2(src_file, dst_file)
 
 
-def copy_cache_for_template_if_available(
+async def copy_cache_for_template_if_available(
     template: ProjectTemplateName, project_folder: Path
 ) -> None:
     """Copy a previously downloaded cache for `template` into `project_folder`.
@@ -222,7 +47,7 @@ def copy_cache_for_template_if_available(
     try:
         cache_dir = _template_cache_dir(template)
         if cache_dir.exists() and any(cache_dir.iterdir()):
-            _copytree(cache_dir, project_folder)
+            await _copytree(cache_dir, project_folder)
             structlogger.info(
                 "project_generator.copy_cache_for_template.success",
                 template=template,

rasa/cli/project_templates/basic/README.md

@@ -0,0 +1,23 @@
+# Basic Rasa Template
+
+A simple, general-purpose conversational agent template that provides essential conversational capabilities.
+
+## 🚀 What's Included
+
+This template provides a foundation for building conversational agents with:
+- **Basic conversational flows**: Greetings, help, feedback, and human handoff
+- **Help system**: Users can ask for assistance and get guided responses
+- **Feedback collection**: Gather user feedback to improve the agent
+- **Human handoff**: Seamlessly transfer conversations to human agents when needed
+
+## 📁 Directory Structure
+
+```
+├── actions/          # Custom Python logic for agent actions
+├── data/            # Conversational flows and training data
+├── domain/          # Agent configuration (slots, responses, actions)
+├── docs/            # Knowledge base documents (optional)
+├── prompts/         # LLM prompts for enhanced responses
+└── config.yml       # Training pipeline configuration
+```
+

rasa/cli/project_templates/basic/actions/actions.md

@@ -0,0 +1,10 @@
+## 📂 `actions/` – The Agent's Toolkit
+
+This folder contains Python files that define custom actions your agent can perform. Actions are pieces of code that run when your agent needs to do something beyond just responding with text.
+
+**What you'll find:**
+- `action_human_handoff.py`: Handles transferring the conversation to a human agent when needed.
+
+**Edit Python files in this folder** to add new custom logic, integrate with APIs, or perform calculations and data processing.
+
+Learn more about custom actions in the [Rasa documentation](https://rasa.com/docs/pro/build/custom-actions).

rasa/cli/project_templates/basic/config.yml

@@ -1,11 +1,11 @@
-# Rasa Assistant Configuration
-# This file controls your assistant's language, message processing pipeline, and conversation policies.
+# Rasa Agent Configuration
+# This file controls your agent's language, message processing pipeline, and conversation policies.
 # For full documentation, see: https://rasa.com/docs/pro/build/configuring-assistant
 recipe: default.v1
 language: en
 
-# The assistant project unique identifier
-# This default value must be replaced with a unique assistant name within your deployment
+# The agent project unique identifier  
+# This default value must be replaced with a unique agent name within your deployment
 assistant_id: placeholder_default
 
 pipeline:

rasa/cli/project_templates/basic/data/data.md

@@ -1,9 +1,8 @@
-## 📂 `data/` – The agent's Business Logic
+## 📂 `data/` – The Agent's Business Logic
 
-This folder holds files that define your agent’s skills using "flows". Each flow is a step-by-step conversation pattern (like a recipe) for handling a user goal (e.g., checking a balance, updating an address).
+This folder holds files that define your agent’s skills using "flows". [1](https://rasa.com/docs/pro/build/writing-flows) Each flow is a step-by-step conversation pattern (like a recipe) for handling a user goal (e.g., checking a balance, updating an address).
 
-**What you’ll find:**
-- Each YAML file = one or more skills.
-- Flows are made of steps: collecting info, calling actions, and responding.
+**What you'll find:**
+- **general/**: Basic conversational flows (greetings, help, feedback, human handoff)
 
-**Edit txt files in this folder** to add new skills, change existing flows, or adjust what the agent asks.
+**Edit YAML files in this folder** to add new skills, change existing flows, or adjust what the agent asks.

rasa/cli/project_templates/basic/domain/domain.md

@@ -1,9 +1,11 @@
-## 📂 `domain/` – The agent’s Brain
+## 📂 `domain/` – The Agent's Brain
 
-This folder contains YAML files that define the agent’s:
-- **Slots**: The agent’s memory (e.g., user's name, account number, address).
-- **Responses**: The messages your bot can say to users (e.g., greetings, confirmations).
-- **Actions**: Custom logic your agent can run (e.g., checking a balance).
+This folder contains YAML files that define the agent's:
+- **Slots**: The agent's memory (e.g., user's name, session info) [1](https://rasa.com/docs/reference/primitives/slots/).
+- **Responses**: The messages your agent can say to users (e.g., greetings, confirmations) [2](https://rasa.com/docs/reference/primitives/responses).
+- **Actions**: Custom logic your agent can run (e.g., handling feedback, human handoff) [3](https://rasa.com/docs/reference/primitives/custom-actions).
 
+**What you'll find:**
+- **general/**: Basic conversational domain elements (greetings, help, feedback)
 
 You can organize the domain as one big file or many small ones. Rasa will automatically merge everything during training [1](https://rasa.com/docs/reference/config/domain).