@enfocussw/switch-scripting-context 25.11.1-beta.4 → 25.11.1-beta.6

package/docs/switch-api/execution-environment.md

@@ -13,6 +13,18 @@ How the Node.js process a script runs in behaves, beyond the entry point API its
 execution mode below, these are consequences of the host process model rather than things a script
 configures — understanding them avoids subtle bugs around state persistence and error handling.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Execution modes
+- Two independent concurrency tiers
+- Don't rely on in-memory state between entry point calls
+- Unhandled promise rejections end the run, not the process
+- Third-party npm modules: file-based scripts only
+- Native (binary) addons are not supported
+- No explicit CPU or memory cap beyond the documented thresholds
+<!-- docs-index:contents end -->
+
 ## Execution modes
 
 Set in the XML declaration via SwitchScripter, or by editing it directly (see
@@ -50,19 +62,40 @@ them:
   recycled (see
   [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
 
-## Module-level state persists across jobs on the same executor
+## Don't rely on in-memory state between entry point calls
+
+Write every entry point so it neither depends on state from an earlier call nor assumes it starts
+from a clean process.
+
+The executor evaluates the whole script again before every entry point call. Top-level
+`let`/`const`/`var` declarations and functions in the script file are recreated each time, so a
+counter or cache held in one does not carry over to the next job.
+
+Some in-memory state can still outlive a call, because executor processes are long-lived and
+shared:
+
+- Properties set on `global`/`globalThis`. One executor runs code for every script element pooled
+  onto it, so a global can be read or overwritten by a different script.
+- Internal state of CommonJS packages loaded with `require()`. Node caches a required module for
+  the life of the process, so a singleton inside the package (a client, a connection pool, a
+  configured default) can be reused by a later call. ES-module packages that are bundled into the
+  script (see [Native (binary) addons](#native-binary-addons-are-not-supported)) are evaluated
+  again on each call like the script itself.
+- Timers, sockets, and other handles a call leaves open keep running after the entry point returns.
+
+Whether any of this reaches a given job depends on which executor the job lands on and whether that
+executor was recycled in between. A script cannot control or predict either. This is a side effect
+of the process model, not a supported feature, and it can change between Switch versions:
 
-Because executor processes are long-lived and reused, any state held outside an entry point function
-— module-level `let`/`const`/`var`, an in-memory cache, a counter — can survive from one job
-invocation to the next if the same executor happens to service both. It is **not** reset before each
-`jobArrived`/`timerFired`/etc. call, and which executor services a given job is not something a
-script controls or can predict. This is useful for caching (e.g. a parsed config file, a pooled
-connection) but also a common source of bugs: don't assume module-level state starts fresh for every
-job, and don't assume it's shared with an *arbitrary* other job either — reset explicitly at the
-start of an entry point if a fresh value is required per job.
+- Don't use globals or package-level singletons to cache data or pass it between jobs. Store data
+  that must outlive a call with `s.setGlobalData()` (see [switch.md](switch.md)) or on the job
+  itself.
+- Don't set globals. If a package keeps internal state, configure it explicitly at the start of
+  each entry point rather than assuming either a fresh or a previously configured instance.
+- Close connections, clear timers, and release file handles before the entry point returns.
 
-`getInitialize()`/`getFinalize()` (if the script uses them) run once per script per process
-lifetime, not once per job — the same caveat applies to anything they set up.
+The executor also recognises `getInitialize()`/`getFinalize()` functions in a script. They are not
+part of the public scripting API; don't define them.
 
 ## Unhandled promise rejections end the run, not the process
 
@@ -85,7 +118,7 @@ third-party modules from its own `node_modules` folder (see
 
 Scripts with ESM dependencies are bundled before execution, when `SwitchVersion` in `manifest.xml`
 is `24.0` or higher (see
-[script-structure.md § Other effects of `SwitchVersion`](../switch-project/script-structure.md#other-effects-of-switchversion)); this bundling path does not support
+[node-versions.md § Other effects of `SwitchVersion`](../switch-project/node-versions.md#other-effects-of-switchversion)); this bundling path does not support
 native/binary Node addons (`.node` files). Stick to pure-JavaScript/TypeScript dependencies.
 
 ## No explicit CPU or memory cap beyond the documented thresholds

package/docs/switch-api/flow-element.md

@@ -11,6 +11,19 @@ triggers:
 
 The `FlowElement` instance `flowElement` is passed to every entry point that operates on a flow element. It provides access to properties, connections, job creation, and logging.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Properties
+- Connections
+- Timer
+- Logging
+- Job creation (jobArrived / timerFired / httpRequestTriggeredAsync)
+- Channels
+- Utilities
+<!-- docs-index:contents end -->
+
 ## Identity
 
 ```ts
@@ -81,12 +94,12 @@ flowElement.failProcess(message: string, messageParam?: string | number | boolea
 ```
 Logs a fatal error and puts the element into the "problem process" state. `messageParam` substitutes `%1`; before Switch 22.1, always pass it, as a string (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). Throws `"Job routing is not allowed in this entry point."` if called from an entry point where routing isn't permitted.
 
-## Job creation (jobArrived / timerFired)
+## Job creation (jobArrived / timerFired / httpRequestTriggeredAsync)
 
 ```ts
 flowElement.createJob(path: string): Promise<Job>
 ```
-Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [job-patterns.md](job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [job-patterns.md](job-patterns.md#sending-jobs) for routing constraints.
+Creates a new job from an existing file/folder path. Valid in `jobArrived`, `timerFired`, and `httpRequestTriggeredAsync` (confirmed working there; the only webhook entry point that receives `flowElement`). The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [job-patterns.md](job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [job-patterns.md](job-patterns.md#sending-jobs) for routing constraints.
 
 ```ts
 // Switch 21.0+

package/docs/switch-api/job-patterns.md

@@ -13,6 +13,19 @@ Common behavioral rules for file access, routing, temp file cleanup, and child j
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- File access semantics
+- Temp file cleanup
+- Platform-independent paths
+- Sending jobs
+- Dataset writes must precede child job creation
+- processLater
+- Executor cleanup thresholds
+- Driving a third-party CLI application
+<!-- docs-index:contents end -->
+
 ## File access semantics
 
 `job.get(accessLevel)` and `job.getDataset(name, accessLevel)` behave differently depending on the access level:

package/docs/switch-api/job.md

@@ -11,6 +11,21 @@ triggers:
 
 A `Job` represents a file or folder moving through the flow. It is passed to `jobArrived` and can be created via `flowElement.createJob()` or `job.createChild()`. Every job must be routed with a `sendTo*()` call or `fail()` before the entry point ends (or at a later time via `timerFired`).
 > Jobs obtained via `flowElement.getJobs()` throw on `getPrivateData()`, `listDatasets()`, and `getDataset()` in the same entry point invocation — private data/metadata cannot be *read* back. `setPrivateData()`/`removePrivateData()` are not restricted this way.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Priority
+- File access
+- Routing
+- Failure & logging
+- Child jobs
+- Private data
+- Datasets (metadata)
+- Variables & structured data
+<!-- docs-index:contents end -->
+
 ## Identity
 
 ```ts
@@ -108,7 +123,7 @@ Creates a new job inheriting the processing history, metadata, and private data
 
 ## Private data
 
-Private data is arbitrary key/value storage attached to a job and passed along with it. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
+Private data is arbitrary key/value storage attached to a job and passed along with it. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). For each tag's string value (`"EnfocusSwitch.<name>"`) and the release that added it, see [enums.md § EnfocusSwitchPrivateDataTag](enums.md#enfocusswitchprivatedatatag).
 
 ```ts
 job.getPrivateData(tag: string | EnfocusSwitchPrivateDataTag): Promise<any>

package/docs/switch-api/logging.md

@@ -15,6 +15,21 @@ Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElem
 listed in [enums.md](enums.md). Each log call has a small performance overhead, so where
 and how often to log is a deliberate choice, not a default.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Log levels
+- Don't add a verbosity property
+- Logging in loops
+- `console.log` does not work
+- Don't double-log before a failure
+- Message formatting and the `%` gotcha
+- Signature gotcha: array vs. single value
+- Placeholders instead of concatenation
+- Message quality
+- Log volume
+<!-- docs-index:contents end -->
+
 ## Log levels
 
 | Level | Use for |

package/docs/switch-api/switch.md

@@ -11,6 +11,16 @@ triggers:
 
 The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Global data
+- Webhooks
+- Abort
+- Server utilities
+  - Translation extraction rules
+<!-- docs-index:contents end -->
+
 ## Global data
 
 Global data is key/value storage shared across entry point invocations, scoped by `Scope`.

package/docs/switch-appstore/app-guidelines.md

@@ -25,6 +25,25 @@ Items fall into three tiers, marked on each one:
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Properties
+- Entry points
+- Sending jobs
+- Logging
+- Temp files and paths
+- App-only
+  - Identity and versioning
+  - Top-level declaration properties
+  - Password protection
+  - Localization
+  - Icon
+  - Extra files
+  - Source and review hygiene
+  - What review does and doesn't cover
+<!-- docs-index:contents end -->
+
 ## Properties
 
 - [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30

package/docs/switch-project/node-versions.md

@@ -0,0 +1,87 @@
+---
+id: node-versions
+category: switch-project
+order: 26
+summary: "How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion`"
+triggers:
+  - "Working out which Node.js version a script or app will run on, or what `SwitchVersion` in manifest.xml does"
+---
+
+# Node.js version per Switch version
+
+
+The Switch Server running the script picks its Node.js version by looking up `SwitchVersion` from
+`manifest.xml` in a fixed table that ships with each Switch release:
+
+| Switch version | `SwitchVersion` | Node.js used |
+|---|---|---|
+| Switch 2020 Spring | `20.0` | 12 |
+| Switch 2020 Fall | `20.1` | 12 |
+| Switch 2021 Spring | `21.0` | 14 |
+| Switch 2021 Fall | `21.1` | 16 |
+| Switch 2022 Spring | `22.0` | 16 |
+| Switch 2022 Fall | `22.1` | 16 |
+| Switch 2023 Fall | `23.1` | 18 |
+| Switch 2024 Spring | `24.0` | 18 |
+| Switch 2024 Fall | `24.1` | 20 |
+| Switch 25.11 | `25.11` | 20 |
+| Switch 26.11 | `26.11` | 24 |
+
+Switch 26.11 bundles Node.js 12.22.12, 14.21.3, 16.20.2, 18.20.8, 20.20.0, and 24.13.0.
+
+`SwitchVersion` controls the Node.js version only. Which scripting API methods exist depends on the
+Switch version the script runs on, see [api-versions.md](../switch-api/api-versions.md).
+
+## What writes `SwitchVersion`
+
+`SwitchVersion` is the version of whichever tool last wrote the manifest. It is not a setting the
+author picks:
+
+- `SwitchScriptTool --create` writes the tool's own version into the new script folder.
+- `SwitchScriptTool --pack` writes the tool's own version into the packed `.sscript`, whatever the
+  script folder's manifest says. The script folder's manifest itself is left unchanged. With
+  SwitchScriptTool 26.11, a folder whose manifest says `21.0` packs to a `.sscript` whose manifest
+  says `26.11`, which moves the script from Node.js 14 to Node.js 24. This was verified with a
+  pre-release SwitchScriptTool build.
+- SwitchScripter writes its own version on every save. Opening a script with a different
+  `SwitchVersion` shows a warning that saving updates the script to the current Node.js version.
+
+**Gotcha:** a script folder tested directly in Switch and the `.sscript` packed from it can run on
+different Node.js versions. A folder created with an older SwitchScriptTool keeps that tool's
+version, but packing it with a newer SwitchScriptTool stamps the newer one. Test the packed
+`.sscript`, not only the folder, before shipping it.
+
+To target an older Node.js version, pack the script with the SwitchScriptTool of a Switch release
+whose row in the table gives that version. For example, a script packed with SwitchScriptTool 25.11
+gets `SwitchVersion` `25.11` and runs on Node.js 20, in Switch 26.11 too. Apps work the same way
+with SwitchScripter, except that there is no SwitchScripter for Switch 25.11. An app that
+needs Node.js 20 is built with the Switch 2024 Fall SwitchScripter (`SwitchVersion` `24.1`), see
+[script-structure.md § SwitchScripter and Switch version compatibility](script-structure.md#switchscripter-and-switch-version-compatibility).
+Editing `SwitchVersion` by hand doesn't last, because `--pack` and SwitchScripter overwrite it.
+
+## Values missing from the table
+
+Behavior of the Switch 26.11 Server:
+
+- No `SwitchVersion` element: treated as `20.1`, so Node.js 12.
+- Lower than the first entry: Node.js 12.
+- Higher than the last entry, for example a package built by a newer tool than the Switch it runs
+  on: the newest Node.js that Switch bundles. The Server logs a debug message that the script
+  "might not be compatible with the current Switch version" and runs it anyway.
+- **Known issue:** a value that isn't an exact entry but falls numerically between the first and
+  last entries matches no Node.js version, for example `25.1` instead of `25.11`, `24.10` instead of
+  `24.1`, or `23.0`. The Server then fails to build the path to a Node.js binary, so no executor
+  process starts for the script. This was confirmed by running the Switch 26.11 lookup code with
+  these values, not by running such a script in Switch, so the exact symptom in Switch hasn't been
+  checked. A value such as `26.3` works today only because it's higher than the last entry, and it
+  will break once a later release adds an entry above it. Never hand-edit `SwitchVersion`. If you
+  must, copy a value exactly as the table above spells it.
+
+## Other effects of `SwitchVersion`
+
+- npm dependencies that are ES modules are bundled with esbuild before execution only when
+  `SwitchVersion` is `24.0` or higher.
+- A script expression has no manifest. It always runs on the newest Node.js the running Switch
+  bundles.
+
+> **Mac (Apple Silicon):** For scripts whose `SwitchVersion` is `21.1` (Switch 2021 Fall) or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts with an earlier `SwitchVersion` run under Rosetta, because the bundled Node.js 12 and 14 are Intel-only builds. If a script bundles platform-specific binaries, ship both Intel and ARM variants.

package/docs/switch-project/project-planning.md

@@ -2,15 +2,20 @@
 id: project-planning
 category: switch-project
 order: 1
-summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+summary: "Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
 triggers:
-  - "Starting a new script or app, before scaffolding any files"
+  - "Starting a new script or app, before scaffolding any files, or working in a script folder that is already scaffolded where Script vs App has not been settled"
 ---
 
 # Project Planning
 
-A pre-scaffolding checklist for a new script or app. Work through this with the user before
-creating any files. The goal is to make a few decisions deliberately up front, because retrofitting
+A planning checklist for a new script or app. Work through this with the user before
+creating any files.
+
+A script folder that already exists (scaffolded by the user, SwitchScripter, or `SwitchScriptTool
+--create`) does not skip the checklist. The manifest's `ScriptPackageType` is always `Script` in a
+scaffolded folder, so it does not answer item 1. Ask Script or App anyway, and run the other
+checks against the code that exists. The goal is to make a few decisions deliberately up front, because retrofitting
 them after code exists is expensive: password protection and localization for an app, path handling
 for a second target OS, synchronizing shared-resource access for concurrency, or restructuring entry
 points around a job-processing approach chosen too casually.
@@ -19,6 +24,21 @@ Two items below are direct questions for the user. The rest are not questions to
 are checks the agent runs against what's actually being built, raised only when they become
 relevant.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Ask the user directly
+  - 1. Script or App?
+  - 2. What should job processing look like in their flow?
+- Evaluate and flag, don't ask upfront
+  - One script folder or several
+  - Target OS
+  - Switch version baseline (apps only)
+  - Concurrency
+  - Native or binary npm dependencies
+  - Appstore competition risk (apps only)
+<!-- docs-index:contents end -->
+
 ## Ask the user directly
 
 ### 1. Script or App?
@@ -86,7 +106,7 @@ This sets two separate limits:
 
 - Which SwitchScripter build is needed to produce a compatible `.enfpack`, and so which Node.js
   version the app runs on (see
-  [script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)).
+  [node-versions.md](node-versions.md)).
   Write code for that Node.js version.
 - Which scripting API methods the code may call. Methods follow the Switch version the app runs on,
   so check every call against [api-versions.md](../switch-api/api-versions.md) for the oldest

package/docs/switch-project/property-editors.md

@@ -27,6 +27,18 @@ the order they're offered. `Type` follows from which editor(s) are chosen — se
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Inline editors
+- Modal editors
+- Literal editors
+- Extra XML attributes for certain editors
+- Common practices
+  - A property whose shape varies by a type selector
+- Notes
+<!-- docs-index:contents end -->
+
 ## Inline editors
 
 The inline editor slot is always the single token `inline` in `Editor` — what differs is `Type`.
@@ -36,13 +48,15 @@ The inline editor slot is always the single token `inline` in `Editor` — what
 | `Editor="inline" Type="string"` | Single-line text as entered |
 | `Editor="inline" Type="password"` | Text as entered (displayed masked) |
 | `Editor="inline" Type="number"` | Integer as a string |
-| `Editor="inline" Type="rational"` | Decimal as a string |
 | `Editor="inline" Type="time"` | `"hh:mm"` (zero-padded, e.g. `"09:05"`) |
 | `Editor="inline" Type="date"` | Date as entered |
 | `Editor="inline" Type="datetime"` | Date and time as entered |
 | `Editor="inline" Type="bool"` | `"No"` or `"Yes"` |
 | `Editor="inline" Type="enum:Item1;Item2;..."` | The selected item string (one of the declared values) |
 
+> The `rational` (decimal) inline editor is not allowed in Node.js scripts. Don't declare
+> `Type="rational"`.
+
 ---
 
 ## Modal editors
@@ -58,7 +72,7 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `filetype` | Filename pattern(s) for the selected file type |
 | `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
 | `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks) |
-| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
+| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one. Unconfirmed, so treat the name as unverified. |
 | `description` | Multi-line text as a single string (may include newlines) |
 | `scriptexp` | Result of script expression evaluated in job context, as a string |
 | `sltextwithvar` | Single-line text with variables substituted, as a string |
@@ -158,7 +172,7 @@ offer it as the property's only editor — pair it with a module-free option (e.
 
 | Property kind | Recommended `Editor` chain | Why |
 |---|---|---|
-| Secret (password, token, API key) | `inline` only, with `Type="password"` | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. `password` is a `Type`, not an editor token — there is no `password` entry in the [modal editor](#modal-editors) list, so `Editor="password"` is wrong. |
+| Secret (password, token, API key) | `inline` only, with `Type="password"` and **`Subtype=""`** (not `"inline"`) | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. `password` is a `Type`, not an editor token — there is no `password` entry in the [modal editor](#modal-editors) list, so `Editor="password"` is wrong. `Subtype="inline"` (the usual value for a single inline editor, per [script-declaration.md](script-declaration.md#custom-property-elements-elementfields)) is rejected at script load with "editor that is not supported in Node.js scripting"; Switch Designer itself saves `Type="password"` with `Subtype=""`. |
 | Scalar job-specific value (job ID, copy count, company name, date, etc.) | `inline` (`Type` matching the value) + `sltextwithvar` + `scriptexp` | Hard-coded default, plus dynamic substitution and full expression evaluation. |
 | Array/list job-specific value | `stringlist` + `mltextwithvar` + `scriptexp` | One item per line. **Caveat:** the intent is that every path returns a `string[]`, but the [modal editor table](#modal-editors) lists `mltextwithvar` as returning a single string, and which one holds for this chain is unverified. Handle both — split on newlines when a bare string comes back. |
 | Structured blob text (XML/JSON/HTML, email body) | `description` + `mltextwithvar` + `scriptexp` | Free multi-line text suits a single blob of content better than a line-per-item list. |

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

@@ -13,6 +13,21 @@ The file `<ScriptID>.xml` defines the script's metadata, custom properties, conn
 and execution configuration. It is normally written by **SwitchScripter**, but the format is fully
 documented below — you can edit it directly.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Agent editing policy
+- XML structure overview
+- Built-in ElementFields
+- Custom property elements (ElementFields)
+- ConnectionFields
+- ExtraProperties
+- Type reference
+- Escaped `ValueDescription` payloads
+- Reserved tag names
+- Annotated example
+<!-- docs-index:contents end -->
+
 ## Agent editing policy
 
 - Editing this file directly is safe as long as you follow the rules on this page exactly — the
@@ -68,7 +83,7 @@ value is non-string (see the table); an empty string field can omit `Type`.
 | `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). |
+| `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). Setting `IncomingConnections="Yes" RequireAtLeastOne="No"` makes the incoming connection optional per instance: some instances can have zero incoming connections (e.g. a flow-starting webhook trigger) and others one wired in (e.g. a mid-flow processing step), with the script branching on both cases at runtime, typically gated by a property such as a mode enum. Confirmed working in Switch Designer. |
 | `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs). |
 | `ConnectionType` | `Move` \| `Filter` \| `TrafficLight` | Governs which `ConnectionFields` children are legal — see [ConnectionFields](#connectionfields). |
 | `FunctionsNodeJSScript` | `;`-separated names | Entry point function names found in the script. Omit the element entirely if there is no Node.js program. |
@@ -120,7 +135,7 @@ Key attributes:
 | `UserDefined` | Always `"true"` for custom properties. |
 | `Type` | Value type discriminator — see [Type reference](#type-reference). |
 | `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [property-editors.md](property-editors.md). |
-| `Subtype` | Which editor in the `Editor` chain is currently active for the stored value. For a single-editor property this equals that editor's token (e.g. `"inline"`); for a bare modal editor with no inline component, leave it `""`. This attribute is read by Switch's validator at runtime, not just bookkeeping — keep it consistent with `Editor`. |
+| `Subtype` | Which editor in the `Editor` chain is currently active for the stored value. For a single-editor property this equals that editor's token (e.g. `"inline"`); for a bare modal editor with no inline component, leave it `""`. Exception: `Type="password"` takes `Subtype=""` even though `Editor="inline"` alone — see [property-editors.md](property-editors.md#common-practices). This attribute is read by Switch's validator at runtime, not just bookkeeping — keep it consistent with `Editor`. |
 | `LocalizedTagName` | Display name shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** 30 characters max, sentence-style capitalization (`"Customer name"`, not `"Customer Name"`). |
 | `Tooltip` | Tooltip shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** give every property a tooltip. The only exception is a property that's fully self-explanatory from its name alone with no extra constraints (e.g. "Number of copies" with no min/max) — if there's anything a user would need to know (units, valid range, format, an example value), put it in the tooltip. |
 | `DetailedInfo` | Long-form description for generated docs. Always include the attribute (empty string `""` is fine) — omitting it makes the property non-editable in Switch Designer. |
@@ -258,7 +273,6 @@ If no OAuth property exists on the script, omit `ExtraProperties` entirely or le
 |---|---|
 | `string` | Text |
 | `number` | Integer |
-| `rational` | Decimal |
 | `password` | Masked text |
 | `bool` | `Yes`/`No` |
 | `date`, `datetime`, `time` | `time` is hours-and-minutes |
@@ -272,11 +286,13 @@ This is the *authoring* vocabulary written into the XML `Type` attribute. It doe
 onto the runtime `PropertyType` returned by `getPropertyType()` (see
 [property-editors.md](property-editors.md) and [enums.md](../switch-api/enums.md)) — e.g. XML
 `bool` becomes runtime `boolean`, XML `path` splits into runtime `filepath`/`folderpath`, and several
-XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `time`) have no direct
+XML types (`stringlist`, `accountlist`, `enum:...`, `datetime`, `time`) have no direct
 `PropertyType` counterpart while several runtime values (`filetype`, `folderpattern`, `regex`,
 `oauthtoken`, `literal`) have no direct XML `Type` counterpart. Don't assume the two vocabularies are
 interchangeable.
 
+`rational` (decimal) is not a valid `Type` for Node.js scripts.
+
 `Type` is not independently authored on properties with a modal editor chain — it follows from
 which editor(s) you choose, per [property-editors.md](property-editors.md). When combining
 an inline editor with modal editors (e.g. `Editor="inline;sltextwithvar;scriptexp"`), the inline

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

@@ -2,9 +2,9 @@
 id: script-structure
 category: switch-project
 order: 10
-summary: "What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App"
+summary: "What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter"
 triggers:
-  - "Setting up a new script project, converting a Script to an App, or working out which Node.js version a script or app will run on"
+  - "Setting up a new script project or converting a Script to an App"
 ---
 
 # Script Project Structure
@@ -13,6 +13,20 @@ A Switch script project lives in a **script folder** during development and is d
 
 > **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [script-declaration.md](script-declaration.md) for the declaration's rules, and [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Script folder files
+- Several script folders side by side
+- manifest.xml format
+- Node.js version per Switch version
+- Script vs App
+- Packing an app
+  - SwitchScripter and Switch version compatibility
+- App Store submission guidelines
+- Execution modes
+<!-- docs-index:contents end -->
+
 ## Script folder files
 
 | File | Required | Notes |
@@ -80,78 +94,8 @@ my-collection/        the folder the user works in; AI agent config and docs liv
 
 ## Node.js version per Switch version
 
-The Switch Server running the script picks its Node.js version by looking up `SwitchVersion` from
-`manifest.xml` in a fixed table that ships with each Switch release:
-
-| Switch version | `SwitchVersion` | Node.js used |
-|---|---|---|
-| Switch 2020 Spring | `20.0` | 12 |
-| Switch 2020 Fall | `20.1` | 12 |
-| Switch 2021 Spring | `21.0` | 14 |
-| Switch 2021 Fall | `21.1` | 16 |
-| Switch 2022 Spring | `22.0` | 16 |
-| Switch 2022 Fall | `22.1` | 16 |
-| Switch 2023 Fall | `23.1` | 18 |
-| Switch 2024 Spring | `24.0` | 18 |
-| Switch 2024 Fall | `24.1` | 20 |
-| Switch 25.07 | `25.07` | 20 |
-| Switch 25.11 | `25.11` | 20 |
-| Switch 26.03 | `26.03` | 24 |
-| Switch 26.07 | `26.07` | 24 |
-
-Switch 26.07 bundles Node.js 12.22.12, 14.21.3, 16.20.2, 18.20.8, 20.20.0, and 24.13.0.
-
-`SwitchVersion` controls the Node.js version only. Which scripting API methods exist depends on the
-Switch version the script runs on, see [api-versions.md](../switch-api/api-versions.md).
-
-### What writes `SwitchVersion`
-
-`SwitchVersion` is the version of whichever tool last wrote the manifest. It is not a setting the
-author picks:
-
-- `SwitchScriptTool --create` writes the tool's own version into the new script folder.
-- `SwitchScriptTool --pack` writes the tool's own version into the packed `.sscript`, whatever the
-  script folder's manifest says. The script folder's manifest itself is left unchanged. Verified
-  with SwitchScriptTool 26.07: a folder whose manifest said `21.0` packed to a `.sscript` whose
-  manifest says `26.07`, which moves the script from Node.js 16 to Node.js 24.
-- SwitchScripter writes its own version on every save. Opening a script with a different
-  `SwitchVersion` shows a warning that saving updates the script to the current Node.js version.
-
-**Gotcha:** a script folder tested directly in Switch and the `.sscript` packed from it can run on
-different Node.js versions. A folder created with an older SwitchScriptTool keeps that tool's
-version, but packing it with a newer SwitchScriptTool stamps the newer one. Test the packed
-`.sscript`, not only the folder, before shipping it.
-
-To target an older Node.js version, build the package with the SwitchScriptTool or SwitchScripter
-of that Switch release. Editing `SwitchVersion` by hand doesn't last, because `--pack` and
-SwitchScripter overwrite it.
-
-### Values missing from the table
-
-Behavior of the Switch 26.07 Server:
-
-- No `SwitchVersion` element: treated as `20.1`, so Node.js 12.
-- Lower than the first entry: Node.js 12.
-- Higher than the last entry, for example a package built by a newer tool than the Switch it runs
-  on: the newest Node.js that Switch bundles. The Server logs a debug message that the script
-  "might not be compatible with the current Switch version" and runs it anyway.
-- **Known issue:** a value that isn't an exact entry but falls numerically between the first and
-  last entries matches no Node.js version, for example `25.7` instead of `25.07`, `24.10` instead of
-  `24.1`, or `23.0`. The Server then fails to build the path to a Node.js binary, so no executor
-  process starts for the script. This was confirmed by running the Switch 26.07 lookup code with
-  these values, not by running such a script in Switch, so the exact symptom in Switch hasn't been
-  checked. A value such as `26.3` works today only because it's higher than the last entry, and it
-  will break once a later release adds an entry above it. Never hand-edit `SwitchVersion`. If you
-  must, copy a value exactly as the table above spells it.
-
-### Other effects of `SwitchVersion`
-
-- npm dependencies that are ES modules are bundled with esbuild before execution only when
-  `SwitchVersion` is `24.0` or higher.
-- A script expression has no manifest. It always runs on the newest Node.js the running Switch
-  bundles.
-
-> **Mac (Apple Silicon):** For scripts whose `SwitchVersion` is `21.1` (Switch 2021 Fall) or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts with an earlier `SwitchVersion` run under Rosetta, because the bundled Node.js 12 and 14 are Intel-only builds. If a script bundles platform-specific binaries, ship both Intel and ARM variants.
+`SwitchVersion` in `manifest.xml` selects the Node.js version the script runs on, and SwitchScriptTool
+and SwitchScripter overwrite it. See [node-versions.md](node-versions.md).
 
 ## Script vs App
 
@@ -186,14 +130,14 @@ joined up explicitly:
 An app loads in the Switch version it was built with **or newer**, never older. So the SwitchScripter
 used must be at or below the oldest Switch version you intend to support, and portable
 SwitchScripters exist for older releases specifically to build backwards-compatible apps. There is
-no SwitchScripter for Switch 25.07 or 25.11 — use the Switch 2024 Fall SwitchScripter for those.
+no SwitchScripter for Switch 25.11 — use the Switch 2024 Fall SwitchScripter for it.
 Apps as a concept require Switch 13.1 or later.
 
 The SwitchScripter version also fixes the app's Node.js version, see
-[Node.js version per Switch version](#nodejs-version-per-switch-version). An app built with the
+[node-versions.md](node-versions.md). An app built with the
 Switch 2024 Fall SwitchScripter has `SwitchVersion` `24.1`, so it runs on Node.js 20 in every Switch
-version that loads it, including 26.x. Switch 26.07 ships SwitchScripter 26.07. An app built with
-it runs on Node.js 24, and it loads only in Switch 26.07 or newer.
+version that loads it, including 26.x. Switch 26.11 ships SwitchScripter 26.11. An app built with
+it runs on Node.js 24, and it loads only in Switch 26.11 or newer.
 
 An unsigned app loads only in Switch on the machine that created it. That's what allows local
 testing before submission; it loads elsewhere only once Enfocus has signed it.