@salesforce/afv-skills 1.7.3 → 1.7.5

package/skills/developing-agentforce/references/architecture-patterns.md

@@ -2,37 +2,37 @@
 
 > Extracted from SKILL.md Section 8. This file is loaded on demand when architecture pattern guidance is needed.
 
-> All architecture patterns below work for both `AgentforceServiceAgent` and `AgentforceEmployeeAgent`. The only difference is that employee agents cannot use `@utils.escalate` or `connection messaging:` — replace escalation with a `@utils.transition` to a help topic or an action that creates a case/ticket.
+> All architecture patterns below work for both `AgentforceServiceAgent` and `AgentforceEmployeeAgent`. The only difference is that employee agents cannot use `@utils.escalate` or `connection messaging:` — replace escalation with a `@utils.transition` to a help subagent or an action that creates a case/ticket.
 
 ## When to Use Each Pattern
 
 | Pattern | Use When |
 |---------|----------|
-| Hub-and-Spoke | Agent has 2+ distinct topics with different intents (most common) |
+| Hub-and-Spoke | Agent has 2+ distinct subagents with different intents (most common) |
 | Verification Gate | Sensitive data, payments, or PII require identity verification first |
 | Post-Action Loop | Actions produce state that drives follow-up logic (e.g., risk scoring) |
-| Single Topic | Agent serves one focused purpose with no routing needed |
+| Single Subagent | Agent serves one focused purpose with no routing needed |
 
 ## Hub-and-Spoke (Most Common)
 
-A central `topic_selector` routes to specialized spoke topics. Each spoke has a "back to hub" transition. Use when users may have multiple distinct intents.
+A central `agent_router` routes to specialized spoke subagents. Each spoke has a "back to hub" transition. Use when users may have multiple distinct intents.
 
 ```
-start_agent topic_selector:
-	description: "Route user requests to the appropriate topic"
+start_agent agent_router:
+	description: "Route user requests to the appropriate subagent"
 	reasoning:
 		instructions: |
 			You are a router only. Do NOT answer questions directly.
 			Always use a transition action to route immediately.
 		actions:
-			to_orders: @utils.transition to @topic.order_support
+			to_orders: @utils.transition to @subagent.order_support
 				description: "Order questions"
-			to_returns: @utils.transition to @topic.return_support
+			to_returns: @utils.transition to @subagent.return_support
 				description: "Return or refund requests"
-			to_general: @utils.transition to @topic.general_support
+			to_general: @utils.transition to @subagent.general_support
 				description: "General questions"
 
-topic order_support:
+subagent order_support:
 	description: "Handle order inquiries"
 	reasoning:
 		instructions: ->
@@ -40,34 +40,34 @@ topic order_support:
 		actions:
 			lookup: @actions.get_order
 				description: "Look up order"
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 ```
 
-> **Routing lives in `start_agent`** -- put all transition actions directly in `start_agent topic_selector:`. Do NOT create a separate routing-only topic (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. Topics that need "go back" should transition to `@topic.topic_selector`.
+> **Routing lives in `start_agent`** -- put all transition actions directly in `start_agent agent_router:`. Do NOT create a separate routing-only subagent (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. Subagents that need "go back" should transition to `@subagent.agent_router`.
 
 ## Verification Gate
 
-Users must pass through identity verification before accessing protected topics. Use when handling sensitive data, payments, or PII.
+Users must pass through identity verification before accessing protected subagents. Use when handling sensitive data, payments, or PII.
 
 ```
-start_agent topic_selector:
+start_agent agent_router:
 	description: "Route through identity verification"
 	reasoning:
 		instructions: |
 			You are a router only. Do NOT answer questions directly.
 			Route all users to identity verification first.
 		actions:
-			verify: @utils.transition to @topic.identity_verification
+			verify: @utils.transition to @subagent.identity_verification
 				description: "Begin verification"
 
-topic identity_verification:
+subagent identity_verification:
 	description: "Verify customer identity"
 	reasoning:
 		instructions: ->
 			if @variables.failed_attempts >= 3:
 				| Too many failed attempts. Transferring to human agent.
-				transition to @topic.escalation
+				transition to @subagent.escalation
 
 			if @variables.is_verified == True:
 				| Identity verified! How can I help?
@@ -80,7 +80,7 @@ topic identity_verification:
 				description: "Verify customer email"
 				set @variables.is_verified = @outputs.verified
 
-			to_account: @utils.transition to @topic.account_mgmt
+			to_account: @utils.transition to @subagent.account_mgmt
 				description: "Account management"
 				available when @variables.is_verified == True
 
@@ -90,7 +90,7 @@ topic identity_verification:
 
 ## Post-Action Loop
 
-The topic re-resolves after an action completes. Place post-action checks at the TOP of `instructions: ->` so they trigger on the loop:
+The subagent re-resolves after an action completes. Place post-action checks at the TOP of `instructions: ->` so they trigger on the loop:
 
 ```
 reasoning:
@@ -99,7 +99,7 @@ reasoning:
 		if @variables.refund_status == "Approved":
 			run @actions.create_crm_case
 				with customer_id = @variables.customer_id
-			transition to @topic.confirmation
+			transition to @subagent.confirmation
 
 		# PRE-LLM: Load data
 		run @actions.load_risk_score
@@ -116,19 +116,19 @@ reasoning:
 
 ## Migrating to Hub-and-Spoke
 
-When refactoring a flat agent (all logic in one topic) into hub-and-spoke:
+When refactoring a flat agent (all logic in one subagent) into hub-and-spoke:
 
-1. **Identify distinct intents** — each becomes a spoke topic
-2. **Move instructions and actions** from the monolithic topic into spoke topics. Each spoke needs BOTH its Level 1 action definitions (under `topic > actions`) AND Level 2 action invocations (under `topic > reasoning > actions`).
-3. **Create `start_agent topic_selector:`** with transition actions pointing to each spoke
-4. **Add "back to hub" transitions** in each spoke: `@utils.transition to @topic.topic_selector`
-5. **Re-preview immediately** — verify topic routing works before making further changes
+1. **Identify distinct intents** — each becomes a spoke subagent
+2. **Move instructions and actions** from the monolithic subagent into spoke subagents. Each spoke needs BOTH its Level 1 action definitions (under `subagent > actions`) AND Level 2 action invocations (under `subagent > reasoning > actions`).
+3. **Create `start_agent agent_router:`** with transition actions pointing to each spoke
+4. **Add "back to hub" transitions** in each spoke: `@utils.transition to @subagent.agent_router`
+5. **Re-preview immediately** — verify subagent routing works before making further changes
 
 **Common migration mistakes:**
-- Creating a separate `main_menu` topic instead of using `start_agent topic_selector:` as the hub — adds an unnecessary LLM hop
-- Leaving action definitions in `start_agent` instead of moving them to spoke topics — all actions visible in all topics, confusing the planner
-- Forgetting to add "back to hub" transitions — users get stuck in a spoke topic
-- If trace shows `topic: "DefaultTopic"`, check that topic descriptions contain keywords matching test utterances
+- Creating a separate `main_menu` subagent instead of using `start_agent agent_router:` as the hub — adds an unnecessary LLM hop
+- Leaving action definitions in `start_agent` instead of moving them to spoke subagents — all actions visible in all subagents, confusing the planner
+- Forgetting to add "back to hub" transitions — users get stuck in a spoke subagent
+- If trace shows `topic: "DefaultTopic"`, check that subagent descriptions contain keywords matching test utterances
 
 ## Multi-Intent Handling
 
@@ -137,8 +137,8 @@ When a user sends multiple intents in one message, the start_agent router should
 ```
 instructions: |
 	You are a router only. Do NOT answer questions directly.
-	If the user asks about multiple topics in one message, route to the first
-	topic. After that task is complete, remind the user about the other request.
+	If the user asks about multiple subagents in one message, route to the first
+	subagent. After that task is complete, remind the user about the other request.
 ```
 
 ## Handling Incomplete Action Inputs

package/skills/developing-agentforce/references/deploy-reference.md

@@ -64,7 +64,7 @@ Publishing creates an **inactive** version. Without activation, preview fails wi
 |-------|-------|-----|
 | `Required fields missing: [BundleType]` | Extra fields in bundle-meta.xml | Use minimal: only `<bundleType>AGENT</bundleType>` |
 | `Internal Error, try again later` | Invalid default_agent_user or new agent platform bug | Query Einstein Agent Users; for new agents, create shell in Setup UI first |
-| `Duplicate value found: GenAiPluginDefinition` | `start_agent` and `topic` share name | Use different names |
+| `Duplicate value found: GenAiPluginDefinition` | `start_agent` and `subagent` share name | Use different names |
 | `Flow not found` | Metadata not deployed | Deploy flows before publishing |
 | `SetupEntityType is not supported for DML` | PermissionSet via Apex DML | Use Metadata API (`sf project deploy start`) |
 

package/skills/developing-agentforce/references/discover-reference.md

@@ -58,7 +58,7 @@ When a target is missing:
 Agentforce ADLC Discovery Report
 
 Agent: OrderManagement
-  Topic: order_inquiry
+  Subagent: order_inquiry
     Action: get_order_status
       Target: flow://Get_Order_Status         Found
     Action: track_shipment

package/skills/developing-agentforce/references/examples.md

@@ -38,10 +38,10 @@ language:
 	additional_locales: ""
 	all_additional_locales: False
 
-start_agent topic_selector:
+start_agent agent_router:
 	description: "Begin the onboarding flow"
 
-topic greeting:
+subagent greeting:
 	label: "Greeting"
 	description: "Greet users and provide help"
 	reasoning:
@@ -62,7 +62,7 @@ Companion `bundle-meta.xml` (MUST be this exact content -- no extra fields):
 
 ## Minimal Employee Agent
 
-Employee agents differ from service agents in their config, variables, and connection blocks. This example shows a 2-topic IT Knowledge agent deployed to internal employees.
+Employee agents differ from service agents in their config, variables, and connection blocks. This example shows a 2-subagent IT Knowledge agent deployed to internal employees.
 
 ```
 system:
@@ -95,8 +95,8 @@ language:
 	additional_locales: ""
 	all_additional_locales: False
 
-start_agent topic_selector:
-	description: "Route employees to the right IT support topic"
+start_agent agent_router:
+	description: "Route employees to the right IT support subagent"
 	reasoning:
 		instructions: |
 			You are a router only. Do NOT answer questions directly.
@@ -104,12 +104,12 @@ start_agent topic_selector:
 			- IT questions, troubleshooting, how-to -> use to_knowledge
 			- Password reset, account access -> use to_account
 		actions:
-			to_knowledge: @utils.transition to @topic.knowledge_search
+			to_knowledge: @utils.transition to @subagent.knowledge_search
 				description: "Search IT knowledge base"
-			to_account: @utils.transition to @topic.account_support
+			to_account: @utils.transition to @subagent.account_support
 				description: "Account and password help"
 
-topic knowledge_search:
+subagent knowledge_search:
 	label: "Knowledge Search"
 	description: "Search and retrieve IT knowledge articles"
 
@@ -139,10 +139,10 @@ topic knowledge_search:
 				with query = ...
 				set @variables.search_query = @outputs.articles
 
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 
-topic account_support:
+subagent account_support:
 	label: "Account Support"
 	description: "Help with password resets and account access"
 
@@ -171,8 +171,8 @@ topic account_support:
 			# NOTE: No @utils.escalate — employee agents cannot escalate to
 			# human agents via messaging. Use a transition or case-creation
 			# action instead.
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 ```
 
 **What's deliberately absent (vs. service agents):**
@@ -183,7 +183,7 @@ topic account_support:
 
 ---
 
-## Multi-Topic Agent with Actions
+## Multi-Subagent Agent with Actions
 
 ```
 system:
@@ -228,25 +228,25 @@ language:
 	additional_locales: ""
 	all_additional_locales: False
 
-start_agent topic_selector:
-	description: "Route customers to the right support topic"
+start_agent agent_router:
+	description: "Route customers to the right support subagent"
 	reasoning:
 		instructions: |
 			You are a router only. Do NOT answer questions or provide help directly.
-			Always use a transition action to route to the correct topic immediately.
+			Always use a transition action to route to the correct subagent immediately.
 			- Order status or tracking -> use to_orders
 			- Returns or refunds -> use to_returns
 			- General questions -> use to_general
 			Never attempt to help the customer yourself. Always route.
 		actions:
-			to_orders: @utils.transition to @topic.order_support
+			to_orders: @utils.transition to @subagent.order_support
 				description: "Check order status or tracking"
-			to_returns: @utils.transition to @topic.return_support
+			to_returns: @utils.transition to @subagent.return_support
 				description: "Process a return or refund"
-			to_general: @utils.transition to @topic.general_support
+			to_general: @utils.transition to @subagent.general_support
 				description: "General questions and support"
 
-topic order_support:
+subagent order_support:
 	label: "Order Support"
 	description: "Handle order status and tracking inquiries"
 
@@ -281,10 +281,10 @@ topic order_support:
 				set @variables.order_id = @outputs.order_id
 				set @variables.order_status = @outputs.status
 
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 
-topic return_support:
+subagent return_support:
 	label: "Return Support"
 	description: "Handle returns and refund requests"
 
@@ -315,14 +315,14 @@ topic return_support:
 				with reason = ...
 				set @variables.case_id = @outputs.return_id
 
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 
 	after_reasoning:
 		if @variables.case_id != "":
-			transition to @topic.confirmation
+			transition to @subagent.confirmation
 
-topic general_support:
+subagent general_support:
 	label: "General Support"
 	description: "Handle general support questions"
 	reasoning:
@@ -332,10 +332,10 @@ topic general_support:
 		actions:
 			escalate_now: @utils.escalate
 				description: "Transfer to human agent"
-			back: @utils.transition to @topic.topic_selector
-				description: "Route to a different topic"
+			back: @utils.transition to @subagent.agent_router
+				description: "Route to a different subagent"
 
-topic confirmation:
+subagent confirmation:
 	label: "Confirmation"
 	description: "Confirm the completed action"
 	reasoning:
@@ -343,7 +343,7 @@ topic confirmation:
 			| Your request has been processed. Reference: {!@variables.case_id}
 			| Is there anything else I can help with?
 		actions:
-			new_request: @utils.transition to @topic.topic_selector
+			new_request: @utils.transition to @subagent.agent_router
 				description: "Start a new request"
 			end_chat: @actions.end_conversation
 				description: "End the conversation"

package/skills/developing-agentforce/references/feature-validity.md

@@ -6,7 +6,7 @@
 
 | Feature | On `@utils.transition` | On action definitions with `target:` | Notes |
 |---------|------------------------|---------------------------------------|-------|
-| `label:` on topics | ❌ | ✅ | Valid on topic blocks |
+| `label:` on subagents | ❌ | ✅ | Valid on subagent blocks |
 | `label:` on actions | ❌ | ✅ | Valid on Level 1 action definitions |
 | `label:` on I/O fields | ❌ | ✅ | Valid on inputs/outputs |
 | `require_user_confirmation:` | ❌ | ✅ | Compiles; runtime no-op |
@@ -18,8 +18,8 @@
 **What works on `@utils.transition` actions:**
 ```yaml
 actions:
-   go_next: @utils.transition to @topic.next
-      description: "Navigate to next topic"   # ✅ ONLY description works
+   go_next: @utils.transition to @subagent.next
+      description: "Navigate to next subagent"   # ✅ ONLY description works
 ```
 
 **What works on action definitions with `target:`:**

package/skills/developing-agentforce/references/instruction-resolution.md

@@ -34,7 +34,7 @@ During Phase 1, the Agent Script runtime evaluates deterministic constructs in `
 2. **Variable injection**: `{!@variables.X}` tokens are replaced with current values.
 3. **`run` execution**: Deterministic `run @actions.X` calls execute and their outputs are captured.
 4. **`set` execution**: Variable assignments execute immediately.
-5. **`transition to`**: If reached, the topic switch happens immediately (LLM is never called).
+5. **`transition to`**: If reached, the subagent switch happens immediately (LLM is never called).
 
 ### Phase 1 Example
 
@@ -46,7 +46,7 @@ reasoning:
       # 1. Post-action check (from previous loop)
       if @variables.refund_approved == True:
          | Your refund has been processed. Reference: {!@variables.refund_id}
-         transition to @topic.confirmation
+         transition to @subagent.confirmation
 
       # 2. Pre-LLM data loading
       if @variables.data_loaded == False:
@@ -97,7 +97,7 @@ The Agent Script runtime assembles a 4-message prompt for the LLM:
 | # | Message Role | Content Source | Purpose |
 |---|---|---|---|
 | 1 | **System** | `system: instructions:` + agent metadata | Global persona, safety rules, capabilities |
-| 2 | **System** | `topic: reasoning: instructions:` (resolved from Phase 1) | Topic-specific operating instructions |
+| 2 | **System** | `subagent: reasoning: instructions:` (resolved from Phase 1) | Subagent-specific operating instructions |
 | 3 | **User/Assistant** | Conversation history (all turns) | Context for the current request |
 | 4 | **System** | Available actions + their descriptions | Tool palette the LLM can choose from |
 
@@ -147,7 +147,7 @@ reasoning:
       # POST-ACTION CHECK (at TOP -- fires on re-resolution)
       if @variables.order_cancelled == True:
          | Your order has been cancelled successfully.
-         transition to @topic.confirmation
+         transition to @subagent.confirmation
 
       # These instructions are for the FIRST entry (before action runs)
       | I can help you cancel your order.
@@ -167,7 +167,7 @@ reasoning:
    instructions: ->
       # 1. POST-ACTION CHECKS (deterministic transitions)
       if @variables.action_completed == True:
-         transition to @topic.next_step
+         transition to @subagent.next_step
 
       # 2. PRE-LLM DATA LOADING (deterministic actions)
       if @variables.data_needed == True:
@@ -258,7 +258,7 @@ reasoning:
          run @actions.assign_case
             with case_id = @variables.case_id
             with priority = @variables.priority
-         transition to @topic.case_confirmation
+         transition to @subagent.case_confirmation
 
       | I need to collect some information to create a support case.
       | What is the issue you're experiencing?
@@ -273,11 +273,11 @@ reasoning:
    instructions: ->
       if @variables.intent == "billing" and @variables.is_verified == True:
          | I can help with your billing question.
-         transition to @topic.billing_support
+         transition to @subagent.billing_support
 
       if @variables.intent == "billing" and @variables.is_verified == False:
          | For billing questions, I need to verify your identity first.
-         transition to @topic.identity_verification
+         transition to @subagent.identity_verification
 
       if @variables.intent == "general":
          | How can I help you today?
@@ -314,32 +314,32 @@ reasoning:
       | What is your order number?
 
       if @variables.order_status != "":
-         transition to @topic.show_status
+         transition to @subagent.show_status
 
 # CORRECT -- Check at TOP
 reasoning:
    instructions: ->
       if @variables.order_status != "":
-         transition to @topic.show_status
+         transition to @subagent.show_status
 
       | What is your order number?
 ```
 
-### Anti-Pattern 3: Persona in Topic Instructions
+### Anti-Pattern 3: Persona in Subagent Instructions
 
 ```
-# WRONG -- Persona text duplicated in every topic
+# WRONG -- Persona text duplicated in every subagent
 reasoning:
    instructions: |
       You are a friendly, professional customer service agent.
       Help the customer with their order.
 
-# CORRECT -- Persona in system instructions, topic has operational instructions only
+# CORRECT -- Persona in system instructions, subagent has operational instructions only
 system:
    instructions: |
       You are a friendly, professional customer service agent.
 
-topic order_support:
+subagent order_support:
    reasoning:
       instructions: ->
          | Help the customer check their order status.
@@ -454,14 +454,14 @@ set @variables.counter = @variables.counter + 1
 ### Deterministic Transition
 
 ```
-transition to @topic.next_topic
+transition to @subagent.next_subagent
 ```
 
 ### Conditional Transition
 
 ```
 if @variables.all_collected == True:
-   transition to @topic.confirmation
+   transition to @subagent.confirmation
 ```
 
 ---
@@ -507,20 +507,20 @@ For production agents, use the Session Trace Data Model (STDM) in Data Cloud to
 
 ---
 
-## 10. Resolution Across Topic Transitions
+## 10. Resolution Across Subagent Transitions
 
-When a topic transition occurs (via `@utils.transition to @topic.X` or `transition to @topic.X`), instruction resolution starts fresh in the new topic:
+When a subagent transition occurs (via `@utils.transition to @subagent.X` or `transition to @subagent.X`), instruction resolution starts fresh in the new subagent:
 
-1. The current topic's remaining instructions are NOT processed
-2. The new topic's `before_reasoning:` runs (if present)
-3. The new topic's `reasoning: instructions:` resolves from Phase 1
-4. The LLM receives the new topic's assembled prompt
+1. The current subagent's remaining instructions are NOT processed
+2. The new subagent's `before_reasoning:` runs (if present)
+3. The new subagent's `reasoning: instructions:` resolves from Phase 1
+4. The LLM receives the new subagent's assembled prompt
 
-**Important**: Variables persist across transitions. A variable set in Topic A is available in Topic B. This is how you pass data between topics:
+**Important**: Variables persist across transitions. A variable set in Subagent A is available in Subagent B. This is how you pass data between subagents:
 
 ```
-# Topic A: Collect data
-topic collect_info:
+# Subagent A: Collect data
+subagent collect_info:
    reasoning:
       instructions: ->
          | Please provide your order number.
@@ -531,13 +531,13 @@ topic collect_info:
 
    after_reasoning:
       if @variables.order_id != "":
-         transition to @topic.process_order
+         transition to @subagent.process_order
 
-# Topic B: Use the data
-topic process_order:
+# Subagent B: Use the data
+subagent process_order:
    reasoning:
       instructions: ->
-         # order_id is available from Topic A
+         # order_id is available from Subagent A
          | Processing order {!@variables.order_id}...
          run @actions.get_order_details
             with order_id = @variables.order_id

package/skills/developing-agentforce/references/known-issues.md

@@ -163,9 +163,9 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Status**: OPEN
 - **Date Discovered**: 2026-02-14
 - **Affects**: Agents with actions targeting secured resources
-- **Symptom**: If the running user (Einstein Agent User or session user) lacks permission to execute ANY action defined in the agent — even actions in other topics — the entire agent may fail with a permission error rather than gracefully skipping the unauthorized action.
-- **Root Cause**: The planner appears to validate permissions for all registered actions at startup, not lazily per-topic.
-- **Workaround**: For **Service Agents**: Ensure the Einstein Agent User has both the `AgentforceServiceAgentUser` system PS AND a custom `{AgentName}_Access` PS with `<classAccesses>` for ALL Apex classes across all topics. Do NOT rely on the auto-generated `NextGen_{AgentName}_Permissions` — it is often incomplete (ORM1 testing: 3/4 classes, missing `ShipmentTracker`). For **Employee Agents**: Ensure each employee user has the custom PS assigned. See [agent-user-setup.md](agent-user-setup.md) for the full provisioning workflow and permission set XML template. Alternatively, split agents by permission boundary.
+- **Symptom**: If the running user (Einstein Agent User or session user) lacks permission to execute ANY action defined in the agent — even actions in other subagents — the entire agent may fail with a permission error rather than gracefully skipping the unauthorized action.
+- **Root Cause**: The planner appears to validate permissions for all registered actions at startup, not lazily per-subagent.
+- **Workaround**: For **Service Agents**: Ensure the Einstein Agent User has both the `AgentforceServiceAgentUser` system PS AND a custom `{AgentName}_Access` PS with `<classAccesses>` for ALL Apex classes across all subagents. Do NOT rely on the auto-generated `NextGen_{AgentName}_Permissions` — it is often incomplete (ORM1 testing: 3/4 classes, missing `ShipmentTracker`). For **Employee Agents**: Ensure each employee user has the custom PS assigned. See [agent-user-setup.md](agent-user-setup.md) for the full provisioning workflow and permission set XML template. Alternatively, split agents by permission boundary.
 - **Open Questions**: Will the planner support lazy permission checking in a future release?
 
 ---
@@ -176,7 +176,7 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Affects**: `system.messages.welcome` with variable interpolation
 - **Symptom**: Variable references like `{!@variables.customer_name}` or `{!userName}` in the welcome message display as literal text instead of resolved values.
 - **Root Cause**: Welcome messages are rendered before the agent runtime initializes variables. Mutable variables have not been set yet, and linked variables may not be resolved at welcome-message time.
-- **Workaround**: Use static welcome messages. Personalize greetings in the first topic's instructions instead.
+- **Workaround**: Use static welcome messages. Personalize greetings in the first subagent's instructions instead.
 - **Open Questions**: Will welcome message variable resolution be supported in a future release?
 
 ---
@@ -187,7 +187,7 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Affects**: `system.messages.welcome` with multi-line content
 - **Symptom**: Line breaks (`\n`) in welcome messages are stripped, causing multi-line messages to render as a single line.
 - **Root Cause**: The welcome message renderer does not preserve newline characters from the Agent Script source.
-- **Workaround**: Keep welcome messages as a single line. Use the first topic's instructions with pipe syntax (`|`) for multi-line greetings.
+- **Workaround**: Keep welcome messages as a single line. Use the first subagent's instructions with pipe syntax (`|`) for multi-line greetings.
 - **Open Questions**: Is this by design or a bug?
 
 ---
@@ -196,9 +196,9 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Status**: OPEN
 - **Date Discovered**: 2026-02-14
 - **Affects**: Multi-agent configurations using `related_agent` references
-- **Symptom**: SOMA (Same Org Multi-Agent) configurations that reference related agents via node declarations fail with "Node does not have corresponding topic" error at runtime.
-- **Root Cause**: The planner resolves agent references at compile time but may not correctly map cross-agent topic references when agents are deployed independently.
-- **Workaround**: Use `@topic.X` delegation within the same agent instead of cross-agent references. For true multi-agent scenarios, use the `@utils.escalate` or connection-based handoff patterns.
+- **Symptom**: SOMA (Same Org Multi-Agent) configurations that reference related agents via node declarations fail with "Node does not have corresponding subagent" error at runtime.
+- **Root Cause**: The planner resolves agent references at compile time but may not correctly map cross-agent subagent references when agents are deployed independently.
+- **Workaround**: Use `@subagent.X` delegation within the same agent instead of cross-agent references. For true multi-agent scenarios, use the `@utils.escalate` or connection-based handoff patterns.
 - **Open Questions**: Will SOMA node resolution be fixed in a future planner update?
 
 ---
@@ -218,8 +218,8 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 - **Status**: WORKAROUND
 - **Date Discovered**: 2026-02-16
 - **Date Updated**: 2026-02-17 (TDD v2.1.0 — clarified outputs specifically required)
-- **Affects**: `sf agent publish authoring-bundle` with topic-level action definitions
-- **Symptom**: `sf agent publish` returns "Internal Error, try again later" when topic-level action definitions have `target:` but no `outputs:` block. Also triggered when using `inputs:` without `outputs:`. LSP + CLI validation both PASS — error is server-side compilation only.
+- **Affects**: `sf agent publish authoring-bundle` with subagent-level action definitions
+- **Symptom**: `sf agent publish` returns "Internal Error, try again later" when subagent-level action definitions have `target:` but no `outputs:` block. Also triggered when using `inputs:` without `outputs:`. LSP + CLI validation both PASS — error is server-side compilation only.
 - **Root Cause**: The server-side compiler needs output type contracts to resolve `flow://` and `apex://` action targets. Without an `outputs:` block, the compiler cannot generate return bindings. The `inputs:` block alone is NOT sufficient — `outputs:` is specifically required.
 - **Workaround**: Always include an `outputs:` block in action definitions. The `inputs:` block can be omitted if the target has no required inputs (the LLM will still slot-fill via `with param=...`), but `outputs:` must always be present.
 - **TDD Validation**: `Val_No_Outputs` (v2.1.0) confirms inputs-only action definition → "Internal Error". `Val_Partial_Output` confirms declaring a subset of outputs IS valid. `Val_Apex_Bare_Output` confirms bare `@InvocableMethod` without wrapper classes also triggers this error.

package/skills/developing-agentforce/references/minimal-examples.md

@@ -1,12 +1,12 @@
 # Minimal Working Examples
 
-Complete, deployable agent examples with single topics, actions, and conditional logic.
+Complete, deployable agent examples with single subagents, actions, and conditional logic.
 
 ---
 
 ## Hello-World Agent Script
 
-A complete, deployable agent with one topic, one action, and conditional logic:
+A complete, deployable agent with one subagent, one action, and conditional logic:
 
 ```agentscript
 system:
@@ -28,12 +28,12 @@ start_agent entry:
     description: "Entry point for all conversations"
     reasoning:
         instructions: |
-            Greet the customer and route to the main topic.
+            Greet the customer and route to the main subagent.
         actions:
-            go_main: @utils.transition to @topic.main
+            go_main: @utils.transition to @subagent.main
                 description: "Navigate to main conversation"
 
-topic main:
+subagent main:
     description: "Main conversation handler"
     reasoning:
         instructions: ->
@@ -64,4 +64,4 @@ topic main:
 - **`instructions: ->`**: Procedural mode enables `if`/`else` and `run` directives
 - **`instructions: |`**: Literal mode for static text passed to the LLM
 - **`set @variables.X = @outputs.Y`**: Captures action output into mutable state
-- **`@utils.transition`**: Permanent handoff (does not return to calling topic)
+- **`@utils.transition`**: Permanent handoff (does not return to calling subagent)