rasa-pro 3.19.0.dev2__tar.gz → 3.19.0.dev3__tar.gz

{rasa_pro-3.19.0.dev2 → rasa_pro-3.19.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rasa-pro
-Version: 3.19.0.dev2
+Version: 3.19.0.dev3
 Summary: State-of-the-art open-core Conversational AI framework for Enterprises that natively leverages generative AI for effortless assistant development.
 Keywords: nlp,machine-learning,machine-learning-library,bot,bots,botkit,rasa conversational-agents,conversational-ai,chatbot,chatbot-framework,bot-framework
 Author: Rasa Technologies GmbH

{rasa_pro-3.19.0.dev2 → rasa_pro-3.19.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "rasa-pro"
-version = "3.19.0.dev2"
+version = "3.19.0.dev3"
 description = "State-of-the-art open-core Conversational AI framework for Enterprises that natively leverages generative AI for effortless assistant development."
 authors = [ "Rasa Technologies GmbH <hi@rasa.com>",]
 maintainers = [ "Tom Bocklisch <tom@rasa.com>",]
@@ -658,6 +658,7 @@ convention = "google"
 
 
 
+
 [tool.poetry.group.dev.dependencies]
 ruff = ">=0.3.5,<0.4.0"
 docker = "~7.1.0"

{rasa_pro-3.19.0.dev2 → rasa_pro-3.19.0.dev3}/rasa/cli/tools/skills_data/maestro/maestro-building-from-conversations/SKILL.md

@@ -13,7 +13,7 @@ rasa_version: ">=3.18"
 metadata:
   author: rasa
   version: "0.1.0"
-  docs-url: https://github.com/RasaHQ/maestro-docs
+  docs-url: https://rasa-2f7eb63d.mintlify.site
 ---
 
 # Building a Maestro agent from conversations
@@ -103,8 +103,9 @@ account?", "verify identity" — is not part of any one goal. Extract it as a
   → `requires:`), an irreversible action that always waited for explicit
   confirmation (prose + `requires:` on a confirmation key, or `requires_confirmation:` on
   the tool), fixed wording after tool success/failure (`on_success:` /
-  `on_failure:`), a genuine either/or branch (`if:`/`else:` + a `categorical` memory
-  key), an order that is itself the requirement (one ordered block). The full ladder
+  `on_failure:`), a branch the transcripts show going one way or the other (one
+  `if:` marker per case, each stating its own condition), an order that is itself
+  the requirement (one ordered block). The full ladder
   is in `maestro-building-skills`; add levers after you observe drift in testing,
   never speculatively.
 
@@ -165,3 +166,18 @@ of figuring out what "correct" looks like.
   linear; default to prose and add levers only for behavior that must be guaranteed.
 - Don't ship tools that only `raise NotImplementedError` — stub realistic fake data
   behind a `TODO` so the agent runs end to end.
+
+## Further reading
+
+Full Maestro documentation: https://rasa-2f7eb63d.mintlify.site
+
+Fetch `https://rasa-2f7eb63d.mintlify.site/llms.txt` for the page index, or
+`https://rasa-2f7eb63d.mintlify.site/llms-full.txt` for every page in one file.
+Read the specific page when this file is not enough; do not guess syntax.
+
+Most relevant here:
+
+- [Instructions](https://rasa-2f7eb63d.mintlify.site/concepts/instructions): what belongs in a prose body
+- [skill.md reference](https://rasa-2f7eb63d.mintlify.site/reference/skill-md): the full frontmatter and body contract
+- [Progressive control guides](https://rasa-2f7eb63d.mintlify.site/build-guide/tool-constraints): choosing the narrowest lever for an observed drift
+- [Conditions](https://rasa-2f7eb63d.mintlify.site/reference/conditions): the expression grammar

{rasa_pro-3.19.0.dev2 → rasa_pro-3.19.0.dev3}/rasa/cli/tools/skills_data/maestro/maestro-building-skills/SKILL.md

@@ -11,7 +11,7 @@ rasa_version: ">=3.18"
 metadata:
   author: rasa
   version: "0.1.1"
-  docs-url: https://github.com/RasaHQ/maestro-docs
+  docs-url: https://rasa-2f7eb63d.mintlify.site
 ---
 
 # Building Maestro skills
@@ -52,7 +52,7 @@ only when observed behavior must become guaranteed behavior. Every lever is addi
 
 ```markdown skills/card_replace/skill.md
 ---
-name: card_replace
+name: Card Replace
 description: Replace a credit card -- lost, stolen, damaged, or not received
 ---
 
@@ -68,8 +68,13 @@ confirm the order, and process the replacement.
 ```
 
 Write the body like instructions to a competent human agent: what to gather, what
-order matters (softly), what to offer when. Reference tools as `@tool.<name>`,
-ordered blocks as `@block.<id>`, other skills as `@skill.<name>`.
+order matters (softly), what to offer when. The skill id is the folder name
+(`card_replace`); `name:` is only a display label.
+
+Name tools in plain prose ("then call `lock_card`"), since they are already in the
+model's schema while the skill is active. Two tokens do exist: `@block.<block_id>`
+for an ordered block in this skill, and `@skill.<skill_id>` for another skill.
+Both take ids, never display names.
 
 ## Tools
 
@@ -99,20 +104,20 @@ async def lock_card(
   Every key you `set` must be declared in a `memory.yml` schema — `rasa train`
   rejects undeclared writes (`undeclared_memory_write`).
 - Return `ToolResult(llm_response=...)` — the LLM reads this as the tool's result.
-  `ToolResult(next=[RunTool(...), ActivateSkill(...)])` overrides control flow
-  (e.g. hand off after max auth failures).
+  Write to memory for anything later steps or `requires:` conditions need.
 - Tools outside the skill folder need frontmatter declaration:
 
 ```yaml
 import_tools:
   - get_customer_info        # shared: from tools/ at agent root
-  - mcp/crm:lookup_account   # MCP server "crm" from integrations.yml
 ```
 
-- Resolution order: skill-local → shared → MCP. First match wins.
-- Naming: `set_<memory_entry>` can validate/clean a value during collection (raise
-  `InvalidMemoryValue` to reject). **`ask_<memory_entry>` is not implemented yet** —
-  ask for the value in prose instead of relying on that hook.
+- A skill-local tool wins over a shared tool of the same name. Resolved once at
+  model load.
+- To validate or clean a value right after it is written, define
+  `run_after_setting_<memory_entry>` in the same `tools.py`. It is an internal
+  hook, never offered to the LLM; return a JSON payload with a non-null `error`
+  to reject the write and roll it back. Ask for values in prose.
 
 ### Interruptions
 
@@ -160,7 +165,7 @@ don't add levers speculatively.
 | Calls a tool before its inputs exist | `tool_constraints` → `requires:` | frontmatter |
 | Executes an irreversible action without asking | In-flow prose confirmation + `requires:` on a confirmation memory key (e.g. `order_confirmed`), or `requires_confirmation:` on the tool in `tool_constraints` | body + frontmatter |
 | Fixed wording after a gated tool succeeds or fails | `on_success:` / `on_failure:` on the tool + templates in `responses.yml` | frontmatter |
-| Follows the wrong branch / mixes workflows | `if:` / `else:` markers | body |
+| Follows the wrong branch / mixes workflows | one `if:` marker per case | body |
 | Paraphrases wording that must be exact (legal, compliance) | `utter:` triggers + `responses.yml` | frontmatter |
 | Skips or reorders steps where order IS the requirement | ordered block | body |
 | Enters the skill when it shouldn't | skill-level `requires:` | frontmatter |
@@ -183,9 +188,11 @@ responses emitted after the tool result (success vs error payload).
 ```yaml
 tool_constraints:
   - lock_card:
-      requires: selected_card_id
+      requires: "session.project.selected_card_id"
   - process_card_replacement:
-      requires: order_confirmed and shipping_type
+      requires: >
+        session.card_replace.order_confirmed
+        and session.card_replace.shipping_type
       requires_confirmation:
         enabled: true
         utter_for_confirmation: utter_ask_replacement_confirmation
@@ -207,32 +214,48 @@ after placeholder substitution, dispatch fails closed instead of pausing
 silently. If a supplied denial resolves to blank text, the engine warns and lets
 the LLM respond (same as omitting that name).
 
-`requires:` is a **string** memory expression, not a map: a bare key
-(`selected_card_id`), a boolean combination (`order_confirmed and shipping_type`,
-`not fraud_report_filed`), or a comparison (`replacement_reason == 'stolen'`). The
-map form (`selected_card_id: { exists: true }`) is rejected — `requires` must be a
-string. Keys may be namespaced: `session.<skill>.<key>` for skill-scoped memory,
-`session.project.<key>` for project-wide memory (the reference examples use the
-namespaced form). It removes the tool from the LLM's schema until the expression is
-true — it cannot call what it cannot see. Every key referenced must be declared in a
-`memory.yml` schema. `tool_constraints` are enforced no matter who triggers the tool
-(LLM or ordered-block step).
+`requires:` is a **string** memory expression. The map form
+(`selected_card_id: { exists: true }`) is rejected.
+
+Every memory reference is three segments: `session.<skill_id>.<entry>` for a
+skill's own memory, `session.project.<entry>` for project-wide memory. A bare key
+is rejected at validation with `Unknown name '<key>' in condition expression`, so
+`requires: selected_card_id` does not work. Within that form you can write a
+truthiness check (`session.project.selected_card_id`), a boolean combination
+(`session.card_replace.order_confirmed and session.card_replace.shipping_type`,
+`not session.card_replace.fraud_report_filed`), or a comparison
+(`session.card_replace.replacement_reason == 'stolen'`). Use a folded `>` scalar
+when the expression spans lines.
 
-### Scoped instructions (`if:`/`else:`)
+A closed gate removes the tool from the LLM's schema, so it cannot call what it
+cannot see. Every key referenced must be declared in a `memory.yml` schema.
+`tool_constraints` are enforced no matter who triggers the tool, the LLM or an
+ordered-block `execute_tool:` step.
 
-Deterministic branching without restructuring. Requires a `categorical` entry in
-`memory.yml`; the framework strips non-matching paragraphs from the prompt once the
-entry is set:
+### Scoped instructions (`if:`)
+
+Deterministic branching without restructuring. Pairs well with a `categorical`
+entry in `memory.yml`; the framework strips non-matching paragraphs from the
+prompt once the entry is set:
 
 ```markdown
-if: replacement_reason is stolen
+if: session.card_replace.replacement_reason == 'stolen'
 Tell the customer the card will be locked for their protection.
-Confirm, then call @tool.lock_card.
+Confirm, then call lock_card.
 
-if: replacement_reason is lost or replacement_reason is not_received
-Call @tool.check_transactions and review recent transactions with them.
+if: session.card_replace.replacement_reason == 'lost' or session.card_replace.replacement_reason == 'not_received'
+Call check_transactions and review recent transactions with them.
 ```
 
+A prose `if:` condition is **the rest of that one line**. YAML folding does not
+apply here: `if: >` followed by indented lines makes the condition the literal
+`>` and turns the condition text into the paragraph body. Keep it on one line,
+however long.
+
+There is one marker, `if:`. Write one paragraph per case, each stating its own
+condition; `else:` in prose fails to compile. For exclusive either/or routing,
+use an ordered block's `next:` branches.
+
 ```yaml skills/card_replace/memory.yml
 schema:
   public:
@@ -276,35 +299,43 @@ requirement (compliance, multi-step approval). Prefer the hybrid form — one bl
 inside prose, referenced with `@block.<id>`:
 
 ```markdown
-Ask why they need a replacement. Once the reason is collected invoke @block.pick_card
-
-:::ordered_block
-	id: pick_card
-	steps:
-    - id: check_eligibility
-      execute_tool: card_replace_eligibility
-    - id: fetch_cards
-      execute_tool: get_customer_info
-    - id: select_card
-      instructions: show user's cards and let them pick one
-      complete_when: "selected_card_id" is not null
+Ask why they need a replacement. Once the reason is recorded, invoke
+@block.pick_card to check eligibility and settle which card this applies to.
+
+:::ordered_block id=pick_card
+steps:
+  - id: check_eligibility
+    execute_tool: card_replace_eligibility
+  - id: fetch_cards
+    execute_tool: get_customer_info
+  - id: select_card
+    instructions: Show the customer their cards and ask which one needs replacing.
+    complete_when: "session.project.selected_card_id"
 :::
 ```
 
-Step types: `execute_tool:` (framework calls, no LLM), `instructions:` +
+The id is a **fence attribute** (`:::ordered_block id=pick_card`), not a YAML key
+inside the body. The body is YAML, so indent with spaces; a tab fails the parse.
+
+Step types: `execute_tool:` (framework calls the tool, no LLM), `instructions:` +
 `complete_when:` (LLM converses inside the step), `noop: true` + `next:`
-(deterministic routing), `collect:` + `utter:` (framework collects a value). A block
-enforces local order only — users can still interrupt to another skill; the block
-resumes at the same step.
+(deterministic routing), `collect:` + `utterance:` (framework collects a value,
+`utterance:` naming the question). Note `utterance:`, not `utter:`: a `collect:`
+step given `utter:` is parsed as an action step and the collect is dropped.
+
+A block enforces local order only. Users can still interrupt to another skill; the
+block resumes at the same step.
 
 ## Composition
 
-- `@skill.<name>` in the body runs another skill and *guarantees* the parent
-  resumes with access to the sub-skill's public memory exports. A user-initiated
-  topic change (interrupt) does not guarantee resumption.
-- Default to small focused skills exporting results as `public` memory. Compose
-  when a skill needs another's logic mid-conversation (disputes → transaction
-  lookup).
+- `@skill.<skill_id>` in the body runs another skill and the parent resumes
+  automatically when it finishes. It takes the target's folder name. A
+  user-initiated topic change is parked differently: the engine offers the
+  customer a resume rather than resuming on its own.
+- A skill's `public` fields are readable by every other skill at any time, so
+  there is no export step. Keep `public` small: it is the skill's API.
+- Default to small focused skills. Compose when a skill needs another's logic
+  mid-conversation (disputes needing transaction lookup).
 - The parent must have business logic of its own — a skill that is nothing but
   `@skill.` references is the orchestrator's job, delete it.
 - Cross-skill dependencies go through memory, not direct coupling: gate with
@@ -319,17 +350,30 @@ resumes at the same step.
   the rigid state machines Maestro exists to replace.
 - Don't restate tool results in prose ("the tool returns JSON with...") — the LLM
   sees `llm_response` directly.
-- Don't invent frontmatter fields. The fields the reference examples use are `name`,
-  `description`, `constraints` (a list of `- text:` guardrails, optionally gated with
-  `while:`/`until:`), and `tool_constraints`; `requires`, `import_tools`, `utter`, and
-  `disabled` are documented too. Check the examples and let `rasa train`
-  confirm a field is accepted on your build.
-- Don't trust this file over the running engine. On the current beta build the
-  reference examples are ground truth for exact `skill.md` syntax, and they differ
-  from some of the sugar above: ordered blocks use explicit step fields
-  (`execute_tool:`, `tool:`, `collect:`+`utterance:`, `action:`, `call:`,
-  `noop:`+`next:`) with `if:`/`else:` routing under `next:`; prose refers to tools by
-  plain name; memory expressions use the `session.<scope>.<key>` form. Prefer the
-  example shapes when `@tool.`/`@block.`/`if:` markers or a field are rejected, and
-  treat `rasa train` errors as the final word. The docs at
-  `docs-url` (`llms.txt`) track the target format.
+- Don't invent frontmatter fields. The complete set is `name`, `description`,
+  `requires`, `complete_when`, `import_tools`, `tool_constraints`, `utter`, and
+  `disabled`. Unknown keys are ignored rather than rejected, so a typo silently
+  does nothing.
+- Don't use a bare memory key in any condition. `requires:`, `if:`,
+  `complete_when:`, `utter:` `when:`, and `next:` branches all take the same
+  three-segment form: `session.<skill_id>.<entry>` or `session.project.<entry>`.
+- Don't treat `rasa train` as optional. It is the validation gate for undeclared
+  memory writes, unknown response names, and malformed conditions, and its errors
+  are authoring feedback rather than build noise.
+
+## Further reading
+
+Full Maestro documentation: https://rasa-2f7eb63d.mintlify.site
+
+Fetch `https://rasa-2f7eb63d.mintlify.site/llms.txt` for the page index, or
+`https://rasa-2f7eb63d.mintlify.site/llms-full.txt` for every page in one file.
+Read the specific page when this file is not enough; do not guess syntax.
+
+Most relevant here:
+
+- [skill.md reference](https://rasa-2f7eb63d.mintlify.site/reference/skill-md): frontmatter properties, body format, jump tokens
+- [Conditions](https://rasa-2f7eb63d.mintlify.site/reference/conditions): the expression grammar for requires:, if:, complete_when:, next:
+- [Ordered block steps](https://rasa-2f7eb63d.mintlify.site/reference/ordered-block-steps): step kinds, step fields, branching
+- [Tools reference](https://rasa-2f7eb63d.mintlify.site/reference/tools): ToolContext, ToolResult, gating, post-write hooks, cancellation
+- [memory.yml reference](https://rasa-2f7eb63d.mintlify.site/reference/memory-yml): scopes, types, visibility, access control
+- [Progressive control guides](https://rasa-2f7eb63d.mintlify.site/build-guide/tool-constraints): one lever at a time, with worked examples

rasa_pro-3.19.0.dev3/rasa/cli/tools/skills_data/maestro/maestro-configuring-agent/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: maestro-configuring-agent
+description: >
+  Configures the Maestro project config files: agent.yml (identity, persona, rules,
+  prompt tuning, session settings), integrations.yml (LLM provider, channels
+  including voice ASR/TTS, model groups), memory.yml (schema, cross-skill
+  visibility), and responses.yml (verbatim templates). Use when setting up or
+  changing any of these files.
+license: Apache-2.0
+engine: maestro
+rasa_version: ">=3.18"
+metadata:
+  author: rasa
+  version: "0.1.1"
+  docs-url: https://rasa-2f7eb63d.mintlify.site
+---
+
+# Configuring a Maestro agent
+
+Project layout:
+
+```
+my-agent/
+├── agent.yml             # identity, persona, rules, prompt tuning
+├── integrations.yml      # llm provider + channels
+├── memory.yml            # optional: project-wide shared memory
+├── lib/                  # optional: shared Python imported by tools.py
+└── skills/
+    └── <skill>/
+        ├── skill.md
+        ├── tools.py       # skill-local tools, auto-discovered
+        ├── memory.yml     # optional: skill-scoped memory schema
+        └── responses.yml  # optional
+```
+
+Start minimal: `agent.yml` with an `agent:` block carrying `persona`, plus
+`integrations.yml` with an `llm:` block and a `channels:` block, is a complete
+config. Add sections only when a feature needs them. The engine is selected by
+project layout, so there is no version key to set.
+
+## agent.yml — identity and persona
+
+```yaml agent.yml
+agent:
+  id: telco-support
+  language: en
+  persona: |
+    You are Telco support, a friendly and concise customer service agent.
+
+rules:
+- Help with billing and plan questions only.
+- >
+  Look up the account with the account-lookup tool before quoting a balance:
+  never guess a number.
+
+prompts:
+  text_rules: |
+    Plain sentences only. No markdown or bullet lists.
+
+session_config:
+  session_expiration_time: 60
+```
+
+The file has **two levels**, and mixing them up is the most common mistake:
+
+- Inside `agent:`: `id`, `language`, `persona`. An `agent:` block is required, and
+  `persona` must be a non-empty string inside it. A file with no `agent:` block
+  fails to load with `config.agent.missing_section`; a missing persona fails with
+  `config.agent.missing_persona`.
+- **Top-level siblings** of `agent:`: `rules`, `prompts`, `references`,
+  `conversation`, `session_config`. Nesting these inside `agent:` means they are
+  never read, and unknown keys are ignored rather than rejected, so the mistake is
+  silent.
+
+Notes:
+
+- `persona` sets global tone and identity.
+- `rules` are global do/don't guidance rendered into every prompt (scope limits,
+  tone guards, ordering constraints). Quote any rule containing a colon followed by
+  a space, or write it as a `>` folded scalar; an unquoted colon parses as a YAML
+  mapping and breaks the load.
+- `prompts` overrides individual sections of the system prompt: `text_rules`,
+  `voice_rules`, `ack_rule`, `ack_reminder`, `ack_enabled`, `ack_examples`,
+  `routing_no_active_skill`. Leave one unset to keep its built-in default.
+- `id` is generated and written back into the file when absent.
+
+## integrations.yml — providers and infrastructure
+
+Holds the LLM provider and the channels customers reach the agent through.
+Never put a literal key in this file. Use `api_key_env` in the `llm:` block, which
+names an environment variable and works for every provider. `${ENV_VAR}` expansion
+happens in the `channels:` block, which is read with environment variables
+expanded; `llm:` and `model_groups:` are not.
+
+```yaml integrations.yml
+llm:
+  provider: openai
+  model: gpt-5.1
+  api_base: https://api.openai.com/v1
+  api_key_env: OPENAI_API_KEY    # env var NAME, not ${...}; value read at load time
+
+channels:
+  rest: { enabled: true }        # REST input (evaluation / HTTP channel)
+  inspector: { enabled: true }   # required for `rasa inspect`
+```
+
+`llm` is the single model that drives the agent: one flat block with `provider` at
+its top level, plus `model` (or `deployment` for Azure OpenAI). It is never a
+`model_groups` reference. Providers `openai`, `azure`, and `self-hosted` have
+dedicated clients; any other value is passed to LiteLLM, so `anthropic` or `gemini`
+work by naming the provider and its model.
+
+`channels` declares the channels customers reach the agent through. `rest` and
+`inspector` are the minimum for local work: `rest` is what the evaluation runner
+talks to, and `inspector` is required for `rasa inspect`.
+
+### Voice channels
+
+Speech recognition and synthesis are configured **inside the voice channel entry**,
+under `asr:` and `tts:`. Each takes a `name:` selecting the engine plus that
+engine's own settings:
+
+```yaml integrations.yml
+channels:
+  browser_audio:
+    enabled: true
+    server_url: localhost:5005
+    asr:
+      name: deepgram
+      language_map:
+        en-US:
+          language: en
+          model: flux-general-en
+      eot_threshold: 0.8
+    tts:
+      name: deepgram
+      language_map:
+        en-US:
+          model: aura-2-asteria-en
+```
+
+Built-in ASR engines: `deepgram`, `azure`. Built-in TTS engines: `deepgram`,
+`azure`, `cartesia`, `rime`. The same `asr:` / `tts:` shape applies to every voice
+channel, including `jambonz`, `audiocodes`, and `twilio_media_streams`; what
+differs is the telephony connection.
+
+### model_groups
+
+Optional, and used today by the references embedder. Declare a group and name it
+from `agent.yml`:
+
+```yaml integrations.yml
+model_groups:
+  - id: reference_embeddings
+    models:
+      - provider: openai
+        model: text-embedding-3-large
+```
+
+```yaml agent.yml
+references:
+  embeddings: reference_embeddings
+```
+
+`model_groups` is read from the packaged model rather than the live project, so
+changing the embedding model needs a retrain.
+
+## Knowledge (RAG)
+
+There is no config for this. Put markdown files in a `references/` folder, at the
+agent root or inside a skill, and `rasa train` indexes every `**/*.md` into the
+model. The agent then gets the built-in `search_knowledge` tool automatically.
+
+Both locations feed one index, and a search covers all of it whatever skill is
+active, so write each document to stand on its own.
+
+## memory.yml — state schema
+
+A skill's own state lives in `skills/<skill>/memory.yml`; state shared across skills
+lives in a project-level `memory.yml` at the agent root (it resolves to the
+`project.` namespace). Declare every key a tool writes — `rasa train` rejects
+an undeclared `context.memory.set()` with `undeclared_memory_write`.
+
+```yaml skills/card_replace/memory.yml
+schema:
+  public:                      # readable by every other skill, at any time
+    replacement_reason:
+      type: categorical        # enum_values constrains what the LLM may record
+      enum_values: [lost, stolen, damaged, not_received]
+      description: Why the card is being replaced.
+    selected_card_id:
+      type: text
+      description: Account id of the chosen card.
+  private:                     # internal to this skill
+    eligibility_checked:
+      type: bool
+      description: Whether account eligibility was verified.
+```
+
+Types: `text`, `bool`, `int`, `float`, `list`, `json`, `categorical` (with
+`enum_values`), and `any`. Give each a `description`: it is what the LLM sees when
+deciding whether to record a value.
+
+Add `llm_settable: true` to let the LLM write an entry itself. Leave it off for
+engine-derived values such as eligibility results or computed flags, so the model
+can neither invent nor revise them. A value owned by a `collect:` step is settable
+either way, since the engine asked the user for it directly.
+
+A project-level `memory.yml` uses the same `type`/`description` shape but as a flat
+map of top-level keys, with no `schema:`/`public:`/`private:` wrapper.
+
+Design rule: `public` is the skill's API. Another skill gating on
+`session.project.authenticated` depends only on that key, not on the auth skill
+itself — keep public entries few and stable.
+
+## responses.yml — verbatim text
+
+Lives inside a skill folder, or at the agent root to apply project-wide. The
+framework delivers the text directly and the LLM never rewrites it.
+`{session.<skill_id>.<entry>}` interpolates at delivery time, as does the bare
+`{entry}` form for the skill's own values.
+
+Every `responses.yml` merges into one registry keyed by name, so response names are
+global. Prefix them with the skill they belong to. Declaring a built-in name such as
+`utter_greet` in the project-root file replaces the bundled one.
+
+```yaml skills/card_replace/responses.yml
+responses:
+  utter_recording_notice:
+    - text: >-
+        This interaction may be recorded for quality assurance
+        and training purposes.
+  utter_replacement_failed:
+    - text: >-
+        We were unable to process your replacement. A support ticket has
+        been created. Reference: {session.card_replace.ticket_id}.
+```
+
+Use verbatim responses for wording that must be exact (legal, compliance,
+brand-mandated). Four things reference a response by name:
+
+- a frontmatter `utter:` trigger, with `on: activate` or a `when:` condition
+- `on_success:` / `on_failure:` on a `tool_constraints` entry
+- `utter_for_confirmation` / `utter_on_user_denial` under `requires_confirmation:`
+- an ordered-block `action:` step, or `utterance:` on a `collect:` step
+
+`rasa train` validates every one of those names. Everything else stays prose so the
+agent sounds natural.
+
+## Don't
+
+- Don't put secrets literally in any of these files. Use `api_key_env` in `llm:`
+  and `${ENV_VAR}` in `channels:`.
+- Don't nest `rules`, `prompts`, `references`, `conversation`, or `session_config`
+  inside the `agent:` block. They are top-level siblings, and nesting them is
+  ignored silently.
+- Don't put skill behavior in `persona` or global config; behavior belongs in the
+  owning skill's `skill.md`.
+- Don't create `domain.yml`, `config.yml`, or `credentials.yml` — those are CALM
+  files. LLM and channel config live in `integrations.yml`.
+- Do declare every memory key a tool writes — undeclared `context.memory.set()`
+  writes fail `rasa train` (`undeclared_memory_write`).
+- If `rasa train` rejects a section, read the reference page for that file below
+  before assuming a bug. Its error names the file and key at fault.
+
+## Further reading
+
+Full Maestro documentation: https://rasa-2f7eb63d.mintlify.site
+
+Fetch `https://rasa-2f7eb63d.mintlify.site/llms.txt` for the page index, or
+`https://rasa-2f7eb63d.mintlify.site/llms-full.txt` for every page in one file.
+Read the specific page when this file is not enough; do not guess syntax.
+
+Most relevant here:
+
+- [agent.yml reference](https://rasa-2f7eb63d.mintlify.site/reference/agent-yml): every key, and which are top-level rather than nested
+- [integrations.yml reference](https://rasa-2f7eb63d.mintlify.site/reference/integrations-yml): LLM providers, channels, voice ASR/TTS, model groups
+- [memory.yml reference](https://rasa-2f7eb63d.mintlify.site/reference/memory-yml): skill schema vs project memory, types, access control
+- [responses.yml reference](https://rasa-2f7eb63d.mintlify.site/reference/responses-yml): templates, interpolation, and the four ways a response fires