Remove snake_case-only restriction on connection & broker IDs; update deploy gateway model

skills/mule-development/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@salesforce/mulesoft-vibes-skills` are documented in thi
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.4] - 2026-08-10
+
+### Fixed
+
+- **`build-agent-broker-project`** and **`translate-agent-broker-old-to-new-project`** — Removed the incorrect claim that connection ids (`context.connections.<id>`) and broker ids (keys under `brokers:`) are restricted by the V2 schema to `^[a-z0-9_]+$` (lowercase/digits/non-trailing-underscore only) and that camelCase or kebab-case "fails lint." The schema does not enforce a snake_case-only format on these keys — any valid YAML identifier validates. The skills now frame snake_case as a readability convention and preserve the one genuine invariant: an `.agent` target (`a2a://`, `mcp://`, `llm://`, `brokers://`) must match its corresponding `agent-network.yaml` key exactly. Affects `canonical-example.md` item 0, `gotchas.md` naming conventions, and the converter's connection/broker translation notes, template comments, and example annotations.
+
+### Changed
+
+- **`build-agent-broker-project`** — Updated the Step 9 deploy/gateway guidance to the current Anypoint CLI Agent Fabric plugin (v1.2.10) gateway model: single-gateway mode (`-g/--gateway`, default `agent-network-gw`) is the recommended path, with separate ingress/egress (`-i/--ingress-gw` + `-e/--egress-gw`) as the alternate mode. Replaces the stale separate-gateway-only defaults (`agent-network-ingress-gw` / `agent-network-egress-gw`).
+
 ## [1.8.3] - 2026-07-13
 
 ### Fixed

skills/mule-development/build-agent-broker-project/references/canonical-example.md

@@ -459,7 +459,7 @@ echo unresolvedResponse:
 
 These are the things the published docs don't make obvious — read the docs for everything else.
 
-0. **Connection and broker IDs use `[a-z0-9_]` only.** Both `context.connections.<id>` keys AND `brokers.<id>` keys are restricted by the YAML schema to lowercase letters, digits, and non-trailing underscores. `help_center_agent_connection` and `it_help_investigation` validate; camelCase (`helpCenterAgentConnection`) or kebab-case (`it-help-investigation`) as YAML keys will fail lint. Registry asset ids (agents/mcps/llms) are more permissive and typically use camelCase (`helpCenterAgent`). The `.agent` file *filename* is unrestricted (kebab-case is fine — `it-help-investigation.agent`).
+0. **Connection and broker IDs are not restricted to `[a-z0-9_]`.** `context.connections.<id>` keys and `brokers.<id>` keys accept any valid YAML identifier — camelCase, snake_case, and kebab-case all validate. This example uses snake_case (`help_center_agent_connection`, `it_help_investigation`) purely for readability. Registry asset ids (agents/mcps/llms) typically use camelCase (`helpCenterAgent`). The only hard rule: `.agent` targets (`a2a://`, `mcp://`, `llm://`, `brokers://`) must match the corresponding YAML key **exactly**. The `.agent` file *filename* is independent (kebab-case is fine — `it-help-investigation.agent`).
 1. **`info.version: v1`** is valid — non-semver strings are accepted.
 2. **`exchange.json` `"groupId": "${organizationId}"`** is the templated convention. `dependencies: []` is fine when all assets are inline.
 3. **A2A v1.0 broker card** in this example omits `url` and `protocolVersion` — the broker IS the endpoint and serves itself. Per the spec these fields are required on a v1.0 card; broker cards are the practical exception. **Registry agent cards** (external agents) DO include `url`. For agents still on legacy A2A v0.3, place the card under `metadata.interfaces.a2a_v03.card` (kept for backward compatibility) — that branch keeps the old shape including `protocolVersion: 0.3.0` and `url`.

skills/mule-development/build-agent-broker-project/references/gotchas.md

@@ -403,8 +403,8 @@ Per asset, atomically:
 
 **Naming conventions** (from canonical + YAML reference):
 - **Registry asset id** (agents/mcps/llms): camelCase or kebab-case. Schema allows `^[a-zA-Z_][a-zA-Z0-9_.-]*$`. The IT example uses camelCase (`helpCenterAgent`, `escalationMcp`, `openAiMini`).
-- **Connection id**: **MUST be lowercase letters, digits, and non-trailing underscores only** (`^[a-z0-9_]+$`, no trailing `_`). `help_center_agent_connection` ✓; `helpCenterAgentConnection` ✗ (uppercase); `my_connection_` ✗ (trailing `_`). This is a hard schema rule — the linter rejects any other pattern.
-- **Broker id** (key under `brokers:`): **same rule as connections** — lowercase letters, digits, non-trailing underscores only. `it_help_investigation` ✓; `it-help-investigation` ✗ (hyphens); `itHelpInvestigation` ✗ (uppercase). The `.agent` *filename* may still use kebab-case (`it-help-investigation.agent`) — only the YAML key is restricted.
+- **Connection id**: any valid YAML identifier. There is **no snake_case-only schema restriction** — camelCase, snake_case, and kebab-case all validate. The canonical example uses snake_case (`help_center_agent_connection`) for readability, but that's a convention, not a rule. The one hard requirement: the id must match the `.agent` target exactly (see Trigger/target rules below).
+- **Broker id** (key under `brokers:`): same — any valid YAML identifier; no snake_case-only restriction. `it_help_investigation`, `it-help-investigation`, and `itHelpInvestigation` all validate. The `.agent` *filename* is independent (kebab-case is fine — `it-help-investigation.agent`). The only hard rule: the trigger `target: "brokers://<broker-id>/a2a"` must match the YAML key exactly.
 - **Trigger `target:`**: `brokers://<broker-id>/a2a` where `<broker-id>` matches the YAML key exactly. If the broker id has underscores, the trigger target does too.
 - **Variables** (in `exchange.json.metadata.variables`): `<assetId>.url`, `<assetId>.apiKey`, etc.
 
@@ -565,12 +565,16 @@ After publish, surface published asset URLs.
 
 ### Step 9 — Deploy
 
-**One-time setup per private space:** `anypoint-cli-agent-fabric-plugin agent-network setup gateways --target-space <space>`. Defaults: ingress `agent-network-ingress-gw`, egress `agent-network-egress-gw`, space `agent-network-space`. Skip if gateways already exist.
+**One-time setup per private space:** `anypoint-cli-agent-fabric-plugin agent-network setup gateways --target-space <space>`. Space defaults to `agent-network-space`. Skip if gateways already exist.
+
+**Gateway modes (both `setup gateways` and `project deploy`):**
+- **Single-gateway mode (recommended):** `-g/--gateway <name>`. When no gateway flags are passed at all, deploy defaults to single-gateway mode using `agent-network-gw`.
+- **Separate-gateways mode:** `-i/--ingress-gw <name>` **with** `-e/--egress-gw <name>`. `-g` is mutually exclusive with `-i`/`-e`.
 
 **CLI deploy:** `anypoint-cli-agent-fabric-plugin agent-network project deploy [flags]`. Useful flags:
 - `--environment <name>` (or `ANYPOINT_ENV`)
-- `--target-space <name>` (defaults to `agent-network-space`)
-- `--ingress-gw <name>` / `--egress-gw <name>` (defaults shown above)
+- `-g/--gateway <name>` (single-gateway mode, recommended)
+- `-t/--target-space <name>` (single-gateway mode: optional; separate-gateways mode: defaults to `agent-network-space`)
 - `--property k:v` (repeatable — env-specific secrets/config; e.g., `--property openai.apiKey:STAGING_API_KEY`)
 - `--dont-wait-for-agent-network` (CI: return immediately)
 - `--disable-tracing` (CI/test: skip telemetry)

skills/mule-development/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/mulesoft-vibes-skills",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "MuleSoft DX skills to enhance Mule developement",
   "license": "SEE LICENSE IN LICENSE.txt",
   "files": [

skills/mule-development/translate-agent-broker-old-to-new-project/SKILL.md

@@ -131,8 +131,8 @@ Mapping rules:
 - `kind: agent` (V1) → `kind: a2a` (V2). `kind: mcp` and `kind: llm` stay.
 - For LLM connections, move auth into a top-level `authentication` block: `kind: apiKey`, `apiKey: ${<llmName>.apiKey}`. Don't keep V1's `spec.configuration` shape.
 - Replace hardcoded URLs with `${<refName>.url}` variables. The actual URL value goes into `exchange.json`.
-- **Connection ID format is enforced by the V2 schema**: `context.connections.<id>` keys must use only lowercase letters, digits, and non-trailing underscores (`^[a-z0-9_]+$`). Convert V1 PascalCase like `WorkdayAgentTestConnection` into `workday_agent_connection` (snake_case). Do NOT use camelCase or kebab-case for connection ids — the linter rejects them.
-- Registry `ref.name` values (agents/mcps/llms) are more permissive and typically become camelCase in V2 (e.g. `workdayAgent`). Only the connection *key* is snake_case-restricted.
+- **Connection IDs are not format-restricted by the V2 schema**: `context.connections.<id>` keys accept any valid YAML identifier (camelCase, snake_case, or kebab-case all validate). Convert V1 PascalCase like `WorkdayAgentTestConnection` into a readable id — this converter uses snake_case (`workday_agent_connection`) for consistency, but that's a convention, not a lint rule. The one hard requirement: the id must match the `.agent` target (`a2a://<id>`, `mcp://<id>`, `llm://<id>`) exactly.
+- Registry `ref.name` values (agents/mcps/llms) typically become camelCase in V2 (e.g. `workdayAgent`).
 
 #### Broker translation
 
@@ -167,7 +167,7 @@ brokers:
               outputModes: [application/json, text/plain]
 ```
 
-**Broker ID format is enforced by the V2 schema**: the key under `brokers:` must use only lowercase letters, digits, and non-trailing underscores (`^[a-z0-9_]+$`). Convert V1 PascalCase like `CustomerOnboardingBrokerTest` into `customer_onboarding` (snake_case). Kebab-case (`customer-onboarding`) fails lint. The `.agent` *filename* is separate and may use kebab-case if you prefer (e.g. `./brokers/customer-onboarding.agent`) — only the YAML broker key is restricted. Match the trigger `target: "brokers://<broker-id>/a2a"` to the YAML key exactly.
+**Broker IDs are not format-restricted by the V2 schema**: the key under `brokers:` accepts any valid YAML identifier (snake_case, kebab-case, and camelCase all validate). Convert V1 PascalCase like `CustomerOnboardingBrokerTest` into a readable id — this converter uses snake_case (`customer_onboarding`) for consistency, but that's a convention, not a lint rule. The `.agent` *filename* is independent (e.g. `./brokers/customer-onboarding.agent`). The one hard rule: match the trigger `target: "brokers://<broker-id>/a2a"` to the YAML broker key **exactly**.
 
 ### 3b. Build the V2 `exchange.json`
 

skills/mule-development/translate-agent-broker-old-to-new-project/references/v2-example.md

@@ -583,13 +583,13 @@ echo onboardingResponse:
 These are the specific decisions reflected in the V2 example, encoded so the conversion is reproducible:
 
 1. **Identifier renaming**: V1's PascalCase agent ids (`WorkdayAgentTest`) became camelCase (`workdayAgent`) in the registry. The `Test` suffix was dropped because the V2 example treats this as the canonical project. Registry ids are unrestricted (`^[a-zA-Z_][a-zA-Z0-9_.-]*$`).
-2. **Connection rename**: V1 `WorkdayAgentTestConnection` → V2 `workday_agent_connection`. Connection *keys* under `context.connections:` are restricted by the V2 schema to `^[a-z0-9_]+$` (lowercase, digits, non-trailing underscores). Their `ref.name` still points at the camelCase registry id (`workdayAgent`).
+2. **Connection rename**: V1 `WorkdayAgentTestConnection` → V2 `workday_agent_connection`. Connection *keys* under `context.connections:` accept any valid YAML identifier (no snake_case-only schema restriction); this converter uses snake_case by convention. Their `ref.name` still points at the camelCase registry id (`workdayAgent`). The one hard rule: the key must match the `.agent` target exactly.
 3. **`kind: agent` → `kind: a2a`**: V1's `agent` connection kind is V2's `a2a`.
 4. **Registry agent shape — `a2a_v03` branch**: V1 agents were A2A v0.3-based, so they convert into `metadata.interfaces.a2a_v03.card` (the GA back-compat path) preserving `protocolVersion: 0.3.0` and `url`. The Beta `metadata.protocol: a2a` + flat `metadata.card.a2a` shape is removed. Move an agent to `metadata.interfaces.a2a` only after the agent owner upgrades it to A2A v1.0.
 5. **Broker card uses `interfaces.a2a` (v1.0)**: the broker emits A2A v1.0 (the GA default). Backward compatibility is on the *consuming* side — clients on v0.3 still work because the runtime translates.
 6. **URLs parameterized**: every external URL becomes `${<refName>.url}` in YAML and lives in `exchange.json` `metadata.variables`.
 7. **Auth on connections**: the Gemini API key auth that V1 stuffed in `spec.configuration.apiKey` is now `context.connections.gemini_connection.authentication.{kind: apiKey, apiKey: ${gemini.apiKey}}`. Authentication is required on `kind: llm` connections in GA.
-8. **Broker id**: `CustomerOnboardingBrokerTest` → `customer_onboarding` (snake_case — the V2 schema restricts `brokers.<id>` keys to `^[a-z0-9_]+$`, so kebab-case fails lint). The `.agent` *filename* is unrestricted and stays `customer-onboarding.agent` for readability. The trigger `target: "brokers://customer_onboarding/a2a"` matches the YAML broker key.
+8. **Broker id**: `CustomerOnboardingBrokerTest` → `customer_onboarding` (snake_case by convention — `brokers.<id>` keys accept any valid YAML identifier, so kebab-case or camelCase would also validate). The `.agent` *filename* is independent and stays `customer-onboarding.agent` for readability. The one hard rule: the trigger `target: "brokers://customer_onboarding/a2a"` must match the YAML broker key exactly.
 9. **MCP tool actions**: each tool listed in V1 `brokers.tools[*].mcp.allowed` got its own action in the `.agent` file. Action ids are descriptive (`match_email_to_address`, `send_slack_status_update`) but the `tool_name` is preserved exactly. **No `inputs:` block** — V1 doesn't declare tool input schemas, and the V2 runtime auto-discovers arguments from the MCP server.
 10. **Reasoning action aliases**: inside `orchestrator.reasoning.actions`, short readable aliases (e.g. `workday`, `slack_update`) point at the longer action ids.
 11. **Prompt preservation**: the V1 `spec.instructions` were copied into the orchestrator's `system.instructions` with only minor cleanup (e.g. fixing "this a long running task" → "this is a long running task", and replacing the dotted MCP tool name with the new alias). Bullets and ordering were preserved.

skills/mule-development/translate-agent-broker-old-to-new-project/references/v2-template.agent

@@ -17,8 +17,9 @@ llm:
     model: "<model from V1 spec.llm.configuration.model>"
 
 # -- ACTION DEFINITIONS -------------------------------------------------------
-# Connection ids in `a2a://...` and `mcp://...` targets MUST match snake_case
-# connection keys declared in agent-network.yaml (schema: ^[a-z0-9_]+$).
+# Connection ids in `a2a://...` and `mcp://...` targets MUST match the
+# connection keys declared in agent-network.yaml exactly (any valid identifier;
+# this converter uses snake_case by convention, not because the schema requires it).
 actions:
   <agent_action_id>:
     target: "a2a://<agent_connection_name_snake_case>"
@@ -33,8 +34,9 @@ actions:
     # auto-discovers tool arguments from the MCP server.
 
 # -- TRIGGER ------------------------------------------------------------------
-# <broker_id_snake_case> MUST match the YAML broker key exactly (schema: ^[a-z0-9_]+$).
-# The .agent filename may still be kebab-case for readability.
+# <broker_id> MUST match the YAML broker key exactly (any valid identifier; this
+# converter uses snake_case by convention, not because the schema requires it).
+# The .agent filename is independent and may be kebab-case for readability.
 trigger <triggerNameCamelCase>:
   kind: "a2a"
   target: "brokers://<broker_id_snake_case>/a2a"