@enfocussw/switch-scripting-context 25.11.0-beta.16 → 25.11.0-beta.18

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.0-beta.18] - 2026-09-11
+
+### Fixed
+
+- The script declaration doc no longer tells agents to bump `Version` on every declaration change.
+  It now says to bump once per release and keep an unreleased number while editing, matching the
+  Appstore guidelines. It also notes that SwitchScripter only accepts minor versions for apps.
+
+## [25.11.0-beta.17] - 2026-09-11
+
+### Changed
+- `job.md`'s `sendToData()` entry and `connection.md`'s `getPropertyStringValue()` entry now warn
+  directly, at the point an agent is most likely to read them, that there is no way to check in
+  advance whether a connection accepts a given traffic light level. The warning previously lived
+  only in a separate section agents weren't always reaching first.
+
 ## [25.11.0-beta.16] - 2026-09-10
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
 
 Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.16/CHANGELOG.md) (also included in this package) for what's changed between versions.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.18/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -84,7 +84,7 @@ A few things this gets you without asking for them by name:
   properties (app path/licence) are off-limits and left to SwitchScripter's GUI instead.
 
 Re-run `init` after upgrading this package so the copied docs and generated config files catch up.
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.16/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.18/CHANGELOG.md) for what changed.
 
 ## Options
 

package/docs/switch-api/connection.md

@@ -37,6 +37,8 @@ connection.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
 Returns the connection property value as a string. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [script-declaration.md § Dependency](../switch-project/script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally.
 
+This is **not** how to check which traffic light level(s) a connection accepts before calling `job.sendToData()` — `"Success"`/`"Warning"`/`"Error"` are not property tags, so passing one throws the same invalid-tag error. There is no supported way to check in advance; see [Connection.Level enum](#connectionlevel-enum) below.
+
 ```ts
 connection.getPropertyType(tag: string): PropertyType
 ```

package/docs/switch-api/job.md

@@ -65,7 +65,7 @@ Send to a specific connection (any type). Get connections via `flowElement.getOu
 ```ts
 job.sendToData(level: Connection.Level, newName?: string): Promise<void>
 ```
-Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists.
+Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists. **There is no supported way to check in advance whether a connection at that level exists** — don't call `connection.getPropertyStringValue("Success")`/`"Warning"`/`"Error"` expecting to detect this; that throws an invalid-tag error, since traffic light levels aren't a readable connection property. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for the pattern (an explicit custom property plus `job.sendToNull()`).
 
 ```ts
 job.sendToLog(level: Connection.Level, model: DatasetModel, newName?: string): Promise<void>

package/docs/switch-project/script-declaration.md

@@ -22,8 +22,10 @@ documented below — you can edit it directly.
 - `Name` is the script's stable ID — never change it on an existing script (it's used as the flow
   element type and referenced by installed flows). `DisplayName`, tooltips, defaults, adding/removing
   custom properties, and connection topology are all safe to change directly.
-- After editing, `Version` should be bumped (integer, no leading zeros necessary beyond `1`) so
-  Switch treats it as an update.
+- `Version` identifies a released build, not an edit. Bump it only when the current value has
+  already been released (installed on a customer's or production Switch, or published on the
+  Appstore). If the current value was never released, keep editing under it; don't bump per
+  change. See the `Version` row below for format and what Switch does with it.
 - Custom property tag names must match `^[A-Za-z][A-Za-z0-9]*$`, must not start with `xml`
   (case-insensitive), and must not collide with a [reserved tag](#reserved-tag-names) below. Switch
   does **not** sanitize or rewrite bad tag names on load — it just fails to work correctly.
@@ -63,7 +65,7 @@ value is non-string (see the table); an empty string field can omit `Type`.
 |---|---|---|
 | `Name` | string | Stable script ID — **never change on an existing script**. Becomes the flow element `Type`. |
 | `DisplayName` | string | Shown in Switch. Empty falls back to `Name`. A `~` splits "Vendor~Element" — Switch shows the part after `~` as the short name and the whole string (space-joined) as the full name. |
-| `Version` | number | Format `[1-9][0-9]*(\.(0\|[1-9][0-9]*))*`, e.g. `1`, `2.1`. Bump on every declaration change. |
+| `Version` | number | Format `[1-9][0-9]*(\.(0\|[1-9][0-9]*))*`, e.g. `1`, `2.1`. SwitchScripter accepts a whole number only for a script and at most one minor level for an app (`2.1`); it resets anything else. Bump once per release, not per edit (see [Agent editing policy](#agent-editing-policy)). Each flow records the version of the element it uses; Switch compares that recorded value with `UpgradeMaximumVersion` to decide whether to show `FlowUpgradeWarning`. |
 | `Keywords` | string | Space/comma/semicolon-separated. Elements pane search. |
 | `Tooltip` | string | Elements pane tooltip. |
 | `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [entry-points.md](../switch-api/entry-points.md#job-processing). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.0-beta.16",
+  "version": "25.11.0-beta.18",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",