Document that version_constraint decides an action's output path shape (#34)

* Document that version_constraint decides an action's output path shape

Adding a version_constraint to an existing workflow without shortening its ${data['...']} references produces YAML that imports cleanly and then fails at release. Nothing in the skill documentation said so, and the two forms are mutually exclusive rather than aliases: unpinned, a reference carries the action's namespace as in ${data['DeviceQuery.Device.query.devices']}, while pinned at ~1 the same field is ${data['DeviceQuery.devices']}.

The schema and best-practices references now describe the pin and the path rewrite as a single two-part edit, and the authoring skill gains a counter-rationalization row for the half-applied case. Verified against a live tenant for Device Query, Get device details, and Event Query: with ~1 the short form resolves and the long form is rejected at release with `property "..." contains unknown variable`; without the pin, the long form resolves.

Two smaller corrections came out of the same check. Only class-based actions strictly require a version_constraint at import, since a non-class action such as Device Query imports and releases without one, so that claim is now scoped accordingly. And the workflows copies of both references had drifted from the authoring copies, still saying to always use ~1 and claiming every CrowdStrike action sits at major version 1, which is wrong for the 0.x actions such as Charlotte AI. Both are now in line.

* Leave authoring SKILL.md at its token budget

The counter-rationalization row added in the previous commit pushed authoring/SKILL.md from 5491 to 5570 tokens, over its 5500 budget, and CI's size check failed. The file had 35 characters of headroom, so the row cannot fit without evicting unrelated guidance, and merging it into the adjacent version_constraint row still lands 10 tokens over.

Reverting that hunk. The guidance lives in the schema and best-practices references, which is where the detail belongs anyway. Deciding what to evict from SKILL.md to make room is a separate change.

Author: mraible

CHANGELOG.md

@@ -19,6 +19,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 ### Fixed
 
 - Three authoring-doc corrections from a Fusion engineer's tech review. `version_constraint` is no longer framed as class-specific — nearly every action carries one whether or not it declares a `class`, so include it on every action node. The event-trigger and system-level variables (`Trigger.CID`, `Workflow.Execution.ID`, `Workflow.Definition.Name`, etc.) are now shown in the `${data['...']}` form and are documented as living in the `data` namespace like any other field rather than as an exception. And the action `name:` field is described as a relabelable display label — renaming it does not break references, which resolve by node key and action `id`.
+- **`version_constraint` decides the shape of an action's output paths, and that was undocumented.** Unpinned, a reference carries the action's namespace (`${data['DeviceQuery.Device.query.devices']}`); pinned at `~1` the same field is `${data['DeviceQuery.devices']}`. The two forms are mutually exclusive, so adding a `version_constraint` to an existing workflow without shortening its `${data['...']}` references produces YAML that imports cleanly and then fails at release with `property "..." contains unknown variable`. The schema and best-practices references now document this as a single two-part edit. Verified against a live tenant for Device Query, Get device details, and Event Query. The `workflows` copies of both references were also brought in line with the `authoring` copies, which had drifted: they still said to "always use `~1`" and claimed all CrowdStrike actions sit at major version 1, which is wrong for the 0.x actions such as Charlotte AI.
+- Clarified that only class-based actions strictly *require* a `version_constraint` at import. A non-class action such as Device Query imports and releases without one; it just keeps the older, longer output paths.
 
 ## [1.0.1] - 2026-08-07
 

skills/authoring/references/best-practices.md

@@ -100,6 +100,28 @@ Import validation fails with an error like:
 version constraint required for activity class 'CreateVariable'
 ```
 
+That failure is specific to class-based actions. A non-class action such as Device
+Query imports and releases fine without a `version_constraint` — but read the next
+section before you decide to leave it off.
+
+### It also decides the shape of the action's output paths
+Pinning a version changes how you reference that action's output, and the two
+forms are mutually exclusive:
+
+| `version_constraint` | Reference form |
+|---|---|
+| omitted | `${data['DeviceQuery.Device.query.devices']}` — carries the action's namespace |
+| `~1` | `${data['DeviceQuery.devices']}` — node label plus field |
+
+The middle segment is the action's `Namespace` from `action_search.py --details`.
+Pin `~1` and keep the long path, and release fails with
+`property "..." contains unknown variable "DeviceQuery.Device.query.devices"`.
+
+**So adding a `version_constraint` to an existing workflow is a two-part edit:**
+add the pin *and* shorten every `${data['...']}` reference to that action. Doing
+only the first produces YAML that imports and then fails at release. Confirmed
+against a live tenant for Device Query, Get device details, and Event Query.
+
 ---
 
 ## YAML authoring gotchas

skills/authoring/references/yaml-schema.md

@@ -437,13 +437,42 @@ output_fields:
 
 ## version_constraint
 
-Required for class-based actions (CreateVariable, UpdateVariable) and every other
-action as well. The value is the tilde range for the major component of the
+Required for class-based actions (CreateVariable, UpdateVariable), and wanted on
+every other action too. The value is the tilde range for the major component of the
 action's `semantic_version` (`~0` when it declares none), so read it from
 `action_search.py --details` rather than assuming `~1`:
 
 ```yaml
 version_constraint: ~1   # semantic_version 1.x.y; use ~0 for 0.x.y, ~2 for 2.x.y
 ```
 
-Omitting this on actions that require it causes import validation failures.
+Omitting this on a class-based action causes import validation failures. On a
+non-class action, import and release both succeed without it, but the action's
+output paths keep their older, longer form — see below.
+
+### It also decides the shape of the action's output paths
+
+Pinning a version is not only a compatibility guard. It changes how you reference
+that action's output, and the two forms are mutually exclusive:
+
+| `version_constraint` | Reference form |
+|---|---|
+| omitted | `${data['DeviceQuery.Device.query.devices']}` — carries the action's namespace |
+| `~1` | `${data['DeviceQuery.devices']}` — node label plus field |
+
+That middle segment is the action's `Namespace` as reported by
+`action_search.py --details` (`device.query` for Device Query,
+`device.get_details` for Get device details, `logscale.query_event` for Event
+Query). Pin `~1`, leave the long path in place, and **release fails**:
+
+```
+property "Script" contains unknown variable "DeviceQuery.Device.query.devices"
+```
+
+So when you add a `version_constraint` to an existing workflow, shorten every
+`${data['...']}` reference to that action in the same edit. Adding the pin alone
+produces YAML that imports and then fails at release.
+
+Confirmed against a live tenant for Device Query, Get device details, and Event
+Query: with `~1` the short form resolves and the long form is rejected at
+release; without it, the long form resolves.

skills/workflows/references/best-practices.md

@@ -77,21 +77,49 @@ per item. Include the input value (e.g., `device_id`) so callers can correlate r
 ### When to use it
 - **Always** on `CreateVariable` and `UpdateVariable` (class-based actions)
 - **Always** when the action response from `action_search.py --details` includes `class`
-- **Sometimes** on catalog actions that have been versioned (check API response)
+- **Every** other action needs one too — it just isn't gated on having a `class`
 
 ### The correct value
+The value is the tilde range for the major component of the action's declared
+`semantic_version`, and `~0` when the action declares none:
+
 ```yaml
-version_constraint: ~1
+version_constraint: ~1   # action's semantic_version is 1.x.y
 ```
-This means "compatible with major version 1" (semver tilde range). All current
-CrowdStrike actions use major version 1.
+
+So an action at `1.0.4` takes `~1`, one at `0.0.100` (Charlotte AI, most Store
+plugins) takes `~0`, and one at `2.3.0` takes `~2`. Do not assume `~1`
+everywhere — plenty of actions sit at major version 0. Read the
+`semantic_version` from `action_search.py --details` and take its major component.
 
 ### What happens without it
 Import validation fails with an error like:
 ```
 version constraint required for activity class 'CreateVariable'
 ```
 
+That failure is specific to class-based actions. A non-class action such as Device
+Query imports and releases fine without a `version_constraint` — but read the next
+section before you decide to leave it off.
+
+### It also decides the shape of the action's output paths
+Pinning a version changes how you reference that action's output, and the two
+forms are mutually exclusive:
+
+| `version_constraint` | Reference form |
+|---|---|
+| omitted | `${data['DeviceQuery.Device.query.devices']}` — carries the action's namespace |
+| `~1` | `${data['DeviceQuery.devices']}` — node label plus field |
+
+The middle segment is the action's `Namespace` from `action_search.py --details`.
+Pin `~1` and keep the long path, and release fails with
+`property "..." contains unknown variable "DeviceQuery.Device.query.devices"`.
+
+**So adding a `version_constraint` to an existing workflow is a two-part edit:**
+add the pin *and* shorten every `${data['...']}` reference to that action. Doing
+only the first produces YAML that imports and then fails at release. Confirmed
+against a live tenant for Device Query, Get device details, and Event Query.
+
 ---
 
 ## YAML authoring gotchas

skills/workflows/references/yaml-schema.md

@@ -441,11 +441,42 @@ output_fields:
 
 ## version_constraint
 
-Required for class-based actions (CreateVariable, UpdateVariable) and some catalog actions.
-Always use `~1` (semver compatible with major version 1).
+Required for class-based actions (CreateVariable, UpdateVariable), and wanted on
+every other action too. The value is the tilde range for the major component of the
+action's `semantic_version` (`~0` when it declares none), so read it from
+`action_search.py --details` rather than assuming `~1`:
 
 ```yaml
-version_constraint: ~1
+version_constraint: ~1   # semantic_version 1.x.y; use ~0 for 0.x.y, ~2 for 2.x.y
 ```
 
-Omitting this on actions that require it causes import validation failures.
+Omitting this on a class-based action causes import validation failures. On a
+non-class action, import and release both succeed without it, but the action's
+output paths keep their older, longer form — see below.
+
+### It also decides the shape of the action's output paths
+
+Pinning a version is not only a compatibility guard. It changes how you reference
+that action's output, and the two forms are mutually exclusive:
+
+| `version_constraint` | Reference form |
+|---|---|
+| omitted | `${data['DeviceQuery.Device.query.devices']}` — carries the action's namespace |
+| `~1` | `${data['DeviceQuery.devices']}` — node label plus field |
+
+That middle segment is the action's `Namespace` as reported by
+`action_search.py --details` (`device.query` for Device Query,
+`device.get_details` for Get device details, `logscale.query_event` for Event
+Query). Pin `~1`, leave the long path in place, and **release fails**:
+
+```
+property "Script" contains unknown variable "DeviceQuery.Device.query.devices"
+```
+
+So when you add a `version_constraint` to an existing workflow, shorten every
+`${data['...']}` reference to that action in the same edit. Adding the pin alone
+produces YAML that imports and then fails at release.
+
+Confirmed against a live tenant for Device Query, Get device details, and Event
+Query: with `~1` the short form resolves and the long form is rejected at
+release; without it, the long form resolves.