Add prominent warnings about kebab-case action IDs causing NaN in scaffolder templates

docs/features/software-templates/index.md

@@ -10,6 +10,18 @@ Components inside Backstage. By default, it has the ability to load skeletons of
 code, template in some variables, and then publish the template to some
 locations like GitHub or GitLab.
 
+:::warning Important
+
+When creating custom scaffolder actions, **use camelCase for action IDs** instead of kebab-case. Action IDs with dashes (like `fetch:component-id`) will cause template expressions like `${{ steps.fetch-component-id.output.componentId }}` to return `NaN` because the dashes are evaluated as subtraction operators in JavaScript expressions.
+
+Use `fetchComponentId` instead of `fetch:component-id` for action IDs, or access outputs using bracket notation: `${{ steps['fetch:component-id'].output.componentId }}`.
+
+:::note
+
+See the [Writing Custom Actions guide](./writing-custom-actions.md#naming-conventions) and [Template Migration guide](./migrating-from-v1beta2-to-v1beta3.md#watch-out-for-dash-case) for more details.
+
+:::
+
 ## Prerequisites
 
 :::note Note

docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md

@@ -202,6 +202,45 @@ output:
 
 ## Watch out for `dash-case`
 
+:::warning Critical Issue: kebab-case Action IDs Cause NaN
+
+The nunjucks compiler can run into issues if the `id` fields in your template steps use dash characters, since these IDs translate directly to JavaScript object properties when accessed as output. **This is a common source of bugs where template expressions return `NaN` instead of expected values.**
+
+**The Problem:**
+When you use kebab-case action IDs like `fetch:component-id`, template expressions like:
+```yaml
+${{ steps.fetch-component-id.output.componentId }}
+```
+Are evaluated as JavaScript: `steps.fetch - component - id.output.componentId`, which performs subtraction operations and results in `NaN`.
+
+**Solutions:**
+
+1. **Recommended:** Use `camelCase` for your action IDs:
+
+```yaml
+steps:
+  - id: fetchComponentId    # ✅ Use camelCase
+    ...
+
+  - id: publishPullRequest  # ✅ Use camelCase
+    input:
+      repoUrl: ${{ steps.fetchComponentId.output.repoUrl }}  # ✅ Works correctly
+```
+
+2. **Alternative:** Keep dash-case and use bracket notation for property access:
+
+```yaml
+steps:
+  - id: fetch-component-id   # ⚠️  Dash-case requires bracket notation
+    ...
+
+  - id: publish-pull-request
+    input:
+      repoUrl: ${{ steps['fetch-component-id'].output.repoUrl }}  # ✅ Works with brackets
+```
+
+:::
+
 The nunjucks compiler can run into issues if the `id` fields in your template steps use dash characters, since these IDs translate directly to JavaScript object properties when accessed as output. One possible migration path is to use `camelCase` for your action IDs.
 
 ```yaml

docs/features/software-templates/writing-custom-actions.md

@@ -105,6 +105,16 @@ We follow `provider:entity:verb` or as close to this as possible for our built-i
 
 Also feel free to use your company name to namespace them if you prefer too, for example `acme:file:create` like above.
 
+:::warning Critical: Use camelCase for Action IDs
+
+**Always use `camelCase` for action IDs** instead of `kebab-case` or `snake_case`. Action IDs with dashes (like `fetch:component-id`) will cause your template expressions to return `NaN` instead of expected values.
+
+**Problem:** If you use kebab-case like `fetch:component-id`, expressions like `${{ steps.fetch-component-id.output.componentId }}` will be evaluated as `steps.fetch - component - id.output.componentId` (subtraction operations), resulting in `NaN`.
+
+**Solution:** Use `fetchComponentId` instead of `fetch:component-id`, or access outputs with bracket notation: `${{ steps['fetch:component-id'].output.componentId }}`.
+
+:::
+
 Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if possible, which leads to better reading
 and writing of template entity definitions.
 

docs/features/software-templates/writing-templates.md

@@ -633,6 +633,14 @@ template. These follow the same standard format:
       name: ${{ parameters.name }}
 ```
 
+:::warning Action ID Naming
+
+When using custom actions, **use camelCase for action IDs** to avoid issues with template expressions. Action IDs with dashes will cause expressions like `${{ steps.my-action.output.value }}` to return `NaN` instead of the expected value.
+
+Use `myAction` instead of `my-action`, or access outputs with bracket notation: `${{ steps['my-action'].output.value }}`.
+
+:::
+
 By default we ship some [built in actions](./builtin-actions.md) that you can
 take a look at, or you can
 [create your own custom actions](./writing-custom-actions.md).