feat: add persona to agent settings (DEVP-624)

docs/docs/development/resource-architecture.md

@@ -43,12 +43,11 @@ The last two are not peers of the first four. Agent configuration is the leaf la
 | File | Holds |
 |---|---|
 | `rules.txt` | Global behavioral instructions |
-| `personality.yaml` | Tone and manner |
-| `role.yaml` | Who the agent is and what it is for |
+| `persona.txt` | Who the agent is, in free text |
 
 Rules are **always present in the prompt**, on every turn. They are not retrieved and not conditional, which makes them the right home for instructions that are unconditionally true — "always confirm the booking reference before making changes" — and the wrong home for facts, which would consume prompt space even when irrelevant to the current turn.
 
-`personality.yaml` and `role.yaml` are narrower than rules: they accept only `{{attr:}}` and `{{vrbl:}}` references. Behavioral references such as `{{fn:}}` and `{{ho:}}` belong in `rules.txt`.
+`persona.txt` is narrower than rules: it accepts only `{{attr:}}` and `{{vrbl:}}` references. Behavioral references such as `{{fn:}}` and `{{ho:}}` belong in `rules.txt`.
 
 See [agent settings](../reference/resources/agent_settings.md).
 
@@ -234,7 +233,7 @@ See [voice settings](../reference/resources/voice_settings.md), [chat settings](
 |---|---|
 | A new FAQ, policy, or factual answer | Topic (`topics/`) |
 | A global behavioral rule (always do X, never do Y) | `agent_settings/rules.txt` |
-| Agent identity and tone | `agent_settings/personality.yaml` and `role.yaml` |
+| Agent identity and tone | `agent_settings/persona.txt` |
 | A multi-step guided conversation | Flow (`flows/`) |
 | Structured data collection from the caller | Entity + flow |
 | Deterministic branching or routing logic | Function (`functions/`) |

docs/docs/development/working-locally.md

@@ -28,8 +28,7 @@ A typical project structure looks like this:
 ├── _gen/                               # Generated stubs - do not edit
 ├── agent_settings/                     # Agent identity and behavior
 │   ├── languages.yaml                  # Optional
-│   ├── personality.yaml
-│   ├── role.yaml
+│   ├── persona.txt
 │   ├── rules.txt
 │   ├── safety_filters.yaml             # Optional
 │   └── experimental_config.json        # Optional

docs/docs/reference/cli/docs.md

@@ -31,7 +31,7 @@ Available resource names:
 
 | Name | Description |
 |---|---|
-| `agent_settings` | Personality, role, rules |
+| `agent_settings` | Persona, rules |
 | `api_integrations` | External HTTP API definitions |
 | `chat_settings` | Chat greeting, style prompt |
 | `context` | Context files for agent knowledge |

docs/docs/reference/resources.md

@@ -15,7 +15,7 @@ Every resource here follows the same sync process, including [permission-gated v
 
 | Resource | Configures | File |
 |---|---|---|
-| [Agent settings](./resources/agent_settings.md) | Personality, role, and global rules | `agent_settings/` |
+| [Agent settings](./resources/agent_settings.md) | Persona and global rules | `agent_settings/` |
 | [Languages](./resources/languages.md) | Supported languages for a multilingual agent | `agent_settings/languages.yaml` |
 | [Experimental config](./resources/experimental_config.md) | Opt-in experimental platform features | `agent_settings/experimental_config.json` |
 

docs/docs/reference/resources/CLAUDE.MD

@@ -33,7 +33,7 @@ config/entities.yaml
 ## What a/an <resource> contains|controls|is for
 
 <The overview. Use grid cards when there are several sub-parts to introduce
-(e.g. agent settings has personality/role/rules); use plain prose when there's
+(e.g. agent settings has persona/rules); use plain prose when there's
 only one shape.>
 
 ### Fields

docs/docs/reference/resources/agent_settings.md

@@ -1,17 +1,20 @@
 ---
 title: Agent settings
-description: Define the agent's identity, role, and behavioral rules in the PolyAI ADK.
+description: Define the agent's identity, persona, and behavioral rules in the PolyAI ADK.
 ---
 
 # Agent settings
 
 <p class="lead">
 Agent settings define the agent's identity and behavioral rules.
-They live in <code>agent_settings/</code> and are made up of personality, role, and rules resources.
+They live in <code>agent_settings/</code> and are made up of persona and rules resources.
 </p>
 
-!!! note "Personality and role are platform-provisioned — update only"
-    The personality and role resources are created automatically by the platform when a project is created. They always exist on any Agent Studio project and can be updated with `poly push`, but cannot be created from scratch via the ADK. If these files appear in a project directory without matching entries in `.agent_studio_config` — for example, after copying a directory from another project — the push will fail with a "Create operation not supported" error. Always start a new project with [`poly init`](../cli/init.md) and [`poly pull`](../cli/pull.md) rather than copying an existing directory.
+!!! note "The persona is platform-provisioned — update only"
+    The persona resource is created automatically by the platform when a project is created. It always exists on any Agent Studio project and can be updated with `poly push`, but cannot be created from scratch via the ADK. If `persona.txt` appears in a project directory without a matching entry in `.agent_studio_config` — for example, after copying a directory from another project — the push will fail with a "Create operation not supported" error. Always start a new project with [`poly init`](../cli/init.md) and [`poly pull`](../cli/pull.md) rather than copying an existing directory.
+
+!!! warning "Personality and role have been removed"
+    The agent's identity used to be split across `personality.yaml` and `role.yaml`. Agent Studio replaced both with a single free-text persona, so the ADK no longer pulls or pushes them. A project last pulled with an older version still has the two files on disk; they are deleted the first time the project is loaded, and the ADK logs a warning telling you to run [`poly pull`](../cli/pull.md) to fetch `persona.txt`.
 
 These settings shape how the agent presents itself and how it should behave across the conversation.
 
@@ -22,8 +25,7 @@ Agent settings live under:
 ~~~text
 agent_settings/
 ├── languages.yaml                  # Optional
-├── personality.yaml
-├── role.yaml
+├── persona.txt
 ├── rules.txt
 ├── safety_filters.yaml             # Optional
 └── experimental_config.json        # Optional
@@ -33,17 +35,11 @@ agent_settings/
 
 <div class="grid cards" markdown>
 
--   **Personality**
+-   **Persona**
 
     ---
 
-    Controls the agent's tone and conversational style.
-
--   **Role**
-
-    ---
-
-    Defines what the agent is and what kind of job it performs.
+    Describes who the agent is, in free text.
 
 -   **Rules**
 
@@ -71,82 +67,34 @@ agent_settings/
 
 </div>
 
-## Personality
+## Persona
 
-The `personality.yaml` file controls the agent's conversational tone.
+The `persona.txt` file is a free-text description of who the agent is. It is the single field that defines the agent's identity, and it is what the **Role** field in Agent Studio edits.
 
-### Fields
+### Supported references
 
-| Field | Description |
+| Syntax | Meaning |
 |---|---|
-| `adjectives` | Map of personality traits to booleans |
-| `custom` | Free-text personality description |
-
-### Adjectives
-
-Allowed adjective values are:
-
-- `Polite`
-- `Calm`
-- `Kind`
-- `Funny`
-- `Energetic`
-- `Thoughtful`
-- `Other`
-
-If `Other` is set to `true`, no other adjective can be selected.
-
-!!! info "Non-standard adjectives"
-
-    The platform may return adjectives not in the local allowed set (for example, deprecated or newly added adjectives). Validation only fails for adjectives that are **enabled** (`true`) and not in the allowed set. Disabled (`false`) non-standard adjectives pass validation and are silently excluded from the update payload when pushing.
-
-### `custom`
+| `{{attr:attribute_name}}` | [Variant attribute](./variants.md) |
+| `{{vrbl:variable_name}}` | [State variable](./variables.md) |
 
-The `custom` field is a free-text description of the personality.
+These are the same two the personality and role settings accepted, so the persona can vary per [variant](./variants.md) or per call. Behavioral references such as `{{fn:}}` and `{{ho:}}` belong in `rules.txt`.
 
-It supports:
+!!! warning "Attribute references are not tracked"
 
-- `{{attr:...}}`
-- `{{vrbl:...}}`
+    `PersonaReferences` carries a variables map and nothing else, so an `{{attr:}}` reference travels in the persona text but is not recorded as a reference on the resource. The personality and role settings behaved the same way. `poly push` still validates that the attribute exists.
 
 ### Example
 
-~~~yaml
-adjectives:
-  Polite: true
-  Calm: true
-  Kind: true
-custom: ""
+~~~text
+You are a calm and polite concierge for {{vrbl:hotel_name}}. Keep answers short.
 ~~~
 
-## Role
-
-The `role.yaml` file defines what the agent is.
+### Derived personas
 
-This is usually the agent's role, title, or function in the business context.
-
-### Fields
-
-| Field | Description |
-|---|---|
-| `value` | Role name, such as `Customer Service Representative` |
-| `additional_info` | Extra context about the role |
-| `custom` | Free-text role description used when `value` is `other` |
+A project that predates the persona and has never had one authored still pulls a `persona.txt`: the platform derives its content from the project's old personality and role settings, without storing it. Because `poly push` only sends resources whose contents have changed, an untouched file is never pushed back.
 
-If `value` is set to `other`, the `custom` field is used instead.
-
-The `custom` field supports:
-
-- `{{attr:...}}`
-- `{{vrbl:...}}`
-
-### Example
-
-~~~yaml
-value: Customer Service Representative
-additional_info: Handles customer inquiries and bookings
-custom: ""
-~~~
+Editing `persona.txt` and pushing authors a real persona. From that point the content is fixed and no longer derived.
 
 ## Rules
 
@@ -231,7 +179,7 @@ See the [Safety filters reference](./safety_filters.md) for field descriptions,
 
 - keep rules concise and actionable
 - use references instead of hard-coded values
-- use `custom` personality and role text only when you need more than the structured fields provide
+- keep the persona focused on who the agent is, and leave what it should do to the rules
 - treat rules as a global behavioral layer, not a place for detailed flow logic
 
 ## Related pages

docs/docs/reference/resources/chat_settings.md

@@ -78,7 +78,7 @@ Use this for chat-specific guidance such as:
 - using bullet points for lists
 - adjusting formatting for readability
 
-This is separate from the agent's broader personality. Use it to control how the agent communicates specifically in web chat.
+This is separate from the agent's broader persona. Use it to control how the agent communicates specifically in web chat.
 
 ### Fields
 

docs/docs/reference/resources/languages.md

@@ -69,7 +69,7 @@ additional_languages:
 
     ---
 
-    See how `languages.yaml` fits alongside personality, role, and rules.
+    See how `languages.yaml` fits alongside the persona and rules.
     [Open agent settings](./agent_settings.md)
 
 -   **Voice settings**

docs/docs/reference/resources/safety_filters.md

@@ -182,7 +182,7 @@ The same settings can be configured in the Agent Studio UI. The platform docs co
 
     ---
 
-    Configure personality, role, and rules alongside project-level safety filters.
+    Configure the persona and rules alongside project-level safety filters.
     [Open agent settings](./agent_settings.md)
 
 -   **Voice settings**

docs/docs/reference/resources/variants.md

@@ -127,10 +127,9 @@ Use `{{attr:attribute_name}}` in supported text fields such as:
 - flow step prompts
 - [topic](./topics.md) actions (not in `content` or `example_queries`)
 - rules (`rules.txt`)
+- persona (`persona.txt`)
 - greeting (`welcome_message`)
 - disclaimer message
-- personality `custom`
-- role `custom`
 
 ### Example
 

docs/docs/reference/resources/voice_settings.md

@@ -87,7 +87,7 @@ Use this for voice-specific guidance such as:
 - spoken tone
 - conversational pacing
 
-This is separate from the agent's broader personality. Use it to shape how the agent should sound specifically on phone calls.
+This is separate from the agent's broader persona. Use it to shape how the agent should sound specifically on phone calls.
 
 ### Fields
 

docs/docs/tooling/tooling.md

@@ -111,7 +111,7 @@ Tooling slots into the standard [CLI workflow](../reference/cli.md): pull or ini
 
     ---
 
-    Configure personality, role, and rules that define agent behavior.
+    Configure the persona and rules that define agent behavior.
     [Open agent settings](../reference/resources/agent_settings.md)
 
 -   **Flows reference**

docs/docs/tutorials/build-an-agent.md

@@ -152,7 +152,7 @@ Add or edit [knowledge-base topics](../reference/resources/topics.md) used for r
 
 #### Agent settings
 
-Update the [personality, role, and rules](../reference/resources/agent_settings.md) that define the agent's global behavior.
+Update the [persona and rules](../reference/resources/agent_settings.md) that define the agent's global behavior.
 
 #### Flows
 

docs/docs/tutorials/restaurant-booking-agent.md

@@ -74,46 +74,22 @@ You are now on the `booking-flow` branch — pushes go here instead of `main`, l
 
 ## Part 2 — Define the agent
 
-### Personality
+### Persona
 
-Open `agent_settings/personality.yaml`. Adjust the adjectives to suit the Maison brand:
+Open `agent_settings/persona.txt` and describe who the agent is. This is the free-text field Agent Studio shows as **Role**:
 
-~~~yaml
-adjectives:
-  Polite: true
-  Calm: true
-  Kind: true
-custom: ""
+~~~text
+You are the reservations agent for Maison, an upscale French restaurant.
+You are polite, calm, and warm, and you keep answers short.
 ~~~
 
-The file has two fields:
-
-- **`adjectives`** — a map of preset tonal traits. Each is set to `true` or `false`; every selected trait is combined into the agent's personality.
-- **`custom`** — a free-text description that can extend or replace the adjectives. It accepts `{{attr:...}}` and `{{vrbl:...}}` references, so the personality can vary per [variant](../reference/resources/variants.md) or per call.
-
-!!! info "Allowed adjective values"
-
-    `adjectives` keys must come from a fixed set: `Polite`, `Calm`, `Kind`, `Funny`, `Energetic`, `Thoughtful`, and `Other`. Any other key causes `poly push` to fail with a validation error.
+!!! tip "Keep identity and behavior separate"
 
-!!! tip "How `Other` works"
+    The persona says who the agent is. Standing instructions about what it should do belong in `rules.txt` below.
 
-    `Other` is the "none of the above" switch. When you set `Other: true`, every other adjective must be `false` (or omitted) — combining `Other: true` with any other adjective set to `true` fails validation with:
+!!! info "Supported references"
 
-    ~~~text
-    Other adjective can only be set if no other adjectives are selected.
-    ~~~
-
-    Use `Other: true` together with the `custom` field when the six presets do not capture the tone you want and you would rather describe the personality entirely in free form. You do **not** need `Other: true` just to use `custom` — `custom` can always be added on top of preset adjectives to refine them further.
-
-### Role
-
-Open `agent_settings/role.yaml` and describe what the agent is:
-
-~~~yaml
-value: Restaurant Reservations Agent
-additional_info: Takes table reservations for Maison restaurant
-custom: ""
-~~~
+    The persona accepts `{{attr:...}}` and `{{vrbl:...}}` references, so it can vary per [variant](../reference/resources/variants.md) or per call. Behavioral references such as `{{fn:...}}` and `{{ho:...}}` belong in `rules.txt`.
 
 ### Rules