@enfocussw/switch-scripting-context 25.11.0-beta.8

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

@@ -0,0 +1,351 @@
+# Script Declaration (XML)
+
+The file `<ScriptID>.xml` defines the script's metadata, custom properties, connection properties,
+and execution configuration. It is normally written by **SwitchScripter**, but the format is fully
+documented below — you can edit it directly.
+
+## Agent editing policy
+
+- Editing this file directly is safe as long as you follow the rules on this page exactly — the
+  format has no schema, so Switch will silently misbehave (not error) on a malformed attribute.
+- Preserve every attribute you don't intend to change. Don't reformat, reorder attributes, or drop
+  fields you don't understand.
+- `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.
+- 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.
+- `manifest.xml` (declares the package's program file(s) and type) rarely needs edits; treat it as
+  low-risk to read but confirm with the user before changing `ScriptPackageType`,
+  `ScriptDeclarationFile`, or `ScriptProgramFiles`.
+- Never add or edit `ApplicationPath` or `ApplicationLicense` — these are app-only properties that
+  point Switch at a third-party application's install location and license. They must be set by the
+  user from the Switch Scripter GUI after the script package has been packed; Switch silently drops
+  them if written into the declaration file directly.
+
+---
+
+## XML structure overview
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Object>
+    <ElementFields>     <!-- required: built-in fields + custom property elements -->
+    <ConnectionFields>  <!-- optional: custom outgoing-connection property elements -->
+    <ExtraProperties>   <!-- optional: OAuth 2.0 editor config only -->
+</Object>
+```
+
+`ElementFields` is required — Switch rejects the whole declaration without it. `ConnectionFields`
+and `ExtraProperties` may be omitted or left empty.
+
+---
+
+## Built-in ElementFields
+
+These configure the flow element (name, topology, execution, pane placement, docs). All carry
+`Editor="hide"` and are never shown to the user directly. Add `Type="..."` to a field only when the
+value is non-string (see the table); an empty string field can omit `Type`.
+
+| Element | Values | Notes |
+|---|---|---|
+| `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. |
+| `Keywords` | string | Space/comma/semicolon-separated. Elements pane search. |
+| `Tooltip` | string | Elements pane tooltip. |
+| `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. |
+| `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). |
+| `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. |
+| `ExecutionMode` | `Concurrent` \| `Serialized` | |
+| `NumberOfSlots` | `Default` \| integer | Only meaningful when `Concurrent`. |
+| `ExecutionGroup` | string | Only meaningful when `Serialized`. Empty falls back to `Name`. |
+| `PerformanceTuning` | `Yes` \| `No` | When `Yes`, `IdleAfterJob` (and `NumberOfSlots` if concurrent) become visible/editable in Switch. |
+| `IdleAfterJob` | number (seconds) | |
+| `PositionInElementPane` | `Basics` \| `Tools` \| `Communication` \| `Apps` \| `Configurators` \| `Metadata` \| `Database` | Which section of the Elements pane the script appears under. |
+| `SubcategoryInElementPane` | escaped XML, see [§ escaped payloads](#escaped-valuedescription-payloads) | Apps/Configurators only. |
+| `DispositionInElementPane` | numeric string or empty | Sort position within the category. Empty = alphabetical. |
+| `Description` | string | Long description. |
+| `Compatibility` | string | Configurator only: third-party app compatibility notes. |
+| `SupportInfo` | string | Configurator only: support email/URL. |
+| `AppDiscovery` | string | Configurator only: how the app is located on disk. |
+| `FlowUpgradeWarning` | string | Warning shown during flow upgrade. |
+| `UpgradeMaximumVersion` | number | Previous version up to which the upgrade warning is shown. Optional. |
+| `Connections` | string | Prose description of outgoing connections, for generated docs. |
+| `SwitchModule` | `Configurator` \| `Metadata` \| `Scripting` \| `Database` \| `SwitchClient` \| `SwitchClientSDK` | Licensing module. |
+| `ObsoleteProperties` | `;`/`,`/whitespace-separated tag names | Suppresses "unknown property" warnings when a flow already has properties you removed. Add old tag names here when removing a custom property. |
+| `ObsoleteConnectionProperties` | same | Same, for removed connection properties. |
+
+Do **not** add `ApplicationPath` or `ApplicationLicense` as element names — Switch silently drops
+them. These app-only properties must be configured by the user from the Switch Scripter GUI after
+the package is packed, not written into the declaration file.
+
+---
+
+## Custom property elements (ElementFields)
+
+Each user-defined property is a child element of `<ElementFields>` with `UserDefined="true"`. The
+element name is the property's **tag** (used as the `tag` argument in `getPropertyStringValue()`)
+and must follow the [tag name rules](#reserved-tag-names).
+
+The element must **never be self-closing**. Its text content holds the property's *current value*
+— e.g. `<Count ...>8</Count>`, not `<Count ... Default="8" />`. A self-closing custom property is
+non-editable in Switch Designer.
+
+```xml
+<MyProperty UserDefined="true" Type="string" Editor="choosefolder" LocalizedTagName="My Property"
+            Tooltip="Select the output folder" DetailedInfo="" Validation="Standard" Default=""
+            Subtype="">Default value goes here</MyProperty>
+```
+
+Key attributes:
+
+| Attribute | Description |
+|---|---|
+| `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 [api-property-editors.md](api-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`. |
+| `LocalizedTagName` | Display name shown in the Properties pane. |
+| `Tooltip` | Tooltip shown in the Properties pane. |
+| `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. |
+| `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs an `isPropertyValid` entry point) \| `Standard and custom` (both, custom only runs if standard passes). |
+| `Default` | Default value string. Omit only if the value is emitted as CDATA instead. |
+| `Dependency` | Tag of the master property this one depends on. Written flat (not nested) — the dependent element is a sibling of its master, not a child. |
+| `DependencyCondition` | One of: `Not-empty`, `Equals`, `Not-equals`, `Contains`, `Does not contain`, `Matches`, `Does not match`, `Starts with`, `Does not start with`. |
+| `Dependencyvalue` | Value(s) to compare against — `;`-separated for multiple. Note the lowercase `v`. |
+
+**Dependency example** — show `OutputFolder` only when `Mode` equals `"Custom"`:
+
+```xml
+<Mode UserDefined="true" Type="enum:Default;Custom" Editor="inline" Subtype="inline"
+      LocalizedTagName="Mode" Tooltip="" DetailedInfo="" Validation="Standard"
+      Default="Default">Default</Mode>
+<OutputFolder UserDefined="true" Type="string" Editor="choosefolder" Subtype=""
+              Dependency="Mode" DependencyCondition="Equals" Dependencyvalue="Custom"
+              LocalizedTagName="Output folder" Tooltip="" DetailedInfo=""
+              Validation="Standard" Default=""></OutputFolder>
+```
+
+Attribute order in the file doesn't matter functionally — SwitchScripter's own output happens to be
+alphabetical (QDom sorts attributes on write), but any order parses correctly.
+
+---
+
+## ConnectionFields
+
+Custom outgoing-connection properties follow the same attribute pattern as element properties, with
+one addition: `AvailableFor="Data"` or `AvailableFor="Log"` restricts which connection kind shows the
+property; omit the attribute for both.
+
+```xml
+<ConnectionFields>
+    <TargetFolder AvailableFor="Data" UserDefined="true" Type="string" Editor="choosefolder"
+                  Subtype="" LocalizedTagName="Target folder" Tooltip="" DetailedInfo=""
+                  Validation="Standard" Default=""></TargetFolder>
+</ConnectionFields>
+```
+
+Connection property values are read at runtime via `connection.getPropertyStringValue(tag)`.
+
+**`ConnectionType` gates which built-in connection fields may appear here** — this is the single
+most important thing to get right when hand-editing this section:
+
+| `ConnectionType` | Legal built-in children |
+|---|---|
+| `Move` | none — `<ConnectionFields/>` must be empty of built-ins |
+| `Filter` | `IncludeFolderMask`, `ExcludeFolderMask` (both or neither) |
+| `TrafficLight` | `Success`, `Warning`, `Error`, each optionally with `AvailableFor="Data"` or `AvailableFor="Log"` (omit the attribute if available for both; omit the whole element if available for neither) |
+
+```xml
+<!-- ConnectionType = TrafficLight -->
+<ConnectionFields>
+    <Success AvailableFor="Data" LocalizedTagName="Success out" Type="bool" Editor="inline" Default="Yes">Yes</Success>
+    <Error   AvailableFor="Data" LocalizedTagName="Error out"   Type="bool" Editor="inline" Default="Yes">Yes</Error>
+    <!-- no Warning element: not available for Data or Log -->
+</ConnectionFields>
+```
+
+Custom (author-defined) connection properties may be added regardless of `ConnectionType`.
+
+**Caution — package-swap connection preservation:** Switch Designer decides whether existing flow
+connections survive a script package replace by comparing the serialised `ConnectionFields` and
+`IncomingConnections` text **byte-for-byte** between old and new declarations, and additionally
+checks whether `ConnectionType`/`OutgoingConnections` changed. Don't make cosmetic whitespace or
+attribute-order changes to those sections without expecting existing flows' outgoing connection
+properties to reset on next package update.
+
+---
+
+## ExtraProperties
+
+Only used for OAuth 2.0 (`Editor` containing `oauth`, see
+[api-property-editors.md](api-property-editors.md)). One child element per OAuth property, named
+identically to the property's tag, in `ElementFields` or `ConnectionFields`:
+
+```xml
+<ElementFields>
+    <OAuth1 UserDefined="true" Type="string" Editor="oauth" Subtype="" LocalizedTagName="OAuth1"
+            Tooltip="" DetailedInfo="" Validation="Standard" Default=""></OAuth1>
+</ElementFields>
+<ExtraProperties>
+    <OAuth1 OAuthAuthorizationEndpoint="http://auth-url"
+            OAuthClientID="AppID1"
+            OAuthClientSecret="Application Password 123"
+            OAuthClientSecretEditor="inline"
+            OAuthRedirPorts="666"
+            OAuthRedirPortsEditor="inline"
+            OAuthScope="some-random-scope"
+            OAuthScopeEditor="inline"
+            OAuthTokenEndpoint="http://token-url"/>
+</ExtraProperties>
+```
+
+Attributes: `OAuthAuthorizationEndpoint`, `OAuthClientID`, `OAuthClientSecret`, `OAuthRedirPorts`,
+`OAuthTokenEndpoint`, `OAuthScope`. A companion `<Attr>Editor` attribute is only needed when that
+attribute has more than one valid input mode; otherwise omit it. If the package is
+password-protected, `OAuthClientSecret` must be stored encrypted — leave OAuth secret edits to the
+user rather than writing a plaintext secret into a password-protected package.
+
+If no OAuth property exists on the script, omit `ExtraProperties` entirely or leave it empty
+(`<ExtraProperties/>`).
+
+---
+
+## Type reference
+
+`Type` is a single token, except for enums:
+
+| Token | Meaning |
+|---|---|
+| `string` | Text |
+| `number` | Integer |
+| `rational` | Decimal |
+| `password` | Masked text |
+| `bool` | `Yes`/`No` |
+| `date`, `datetime`, `time` | `time` is hours-and-minutes |
+| `path` | Filesystem path |
+| `enum:A;B;C` | Closed choice list, `;`-separated (a trailing `;` is tolerated) |
+| `filefilter`, `folderfilter` | File / folder filter values |
+| `stringlist` | List of strings |
+| `accountlist` | Account list |
+
+This is the *authoring* vocabulary written into the XML `Type` attribute. It does not map one-to-one
+onto the runtime `PropertyType` returned by `getPropertyType()` (see
+[api-property-editors.md](api-property-editors.md) and [api-enums.md](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
+`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.
+
+`Type` is not independently authored on properties with a modal editor chain — it follows from
+which editor(s) you choose, per [api-property-editors.md](api-property-editors.md). When combining
+an inline editor with modal editors (e.g. `Editor="inline;sltextwithvar;scriptexp"`), the inline
+editor's type wins: an inline Number editor plus those modal editors still yields `Type="number"`.
+
+---
+
+## Escaped `ValueDescription` payloads
+
+`SubcategoryInElementPane` (and a couple of internal-only fields) store a nested XML fragment,
+escaped into the text node:
+
+```xml
+<SubcategoryInElementPane Editor="hide">&lt;ValueDescription Type="stringlist">
+ &lt;Value>Communication&lt;/Value>
+&lt;/ValueDescription>
+</SubcategoryInElementPane>
+```
+
+Decodes to:
+
+```xml
+<ValueDescription Type="stringlist">
+  <Value>Communication</Value>
+</ValueDescription>
+```
+
+One `Value` child per subcategory string. Escaping only `<` (not also `&quot;`) is fine — both forms
+parse.
+
+---
+
+## Reserved tag names
+
+A custom property or connection property tag must not collide with any built-in field name. Do not
+use any of:
+
+- Any [built-in `ElementFields` name](#built-in-elementfields) above.
+- Any built-in `ConnectionFields` name: `IncludeFolderMask`, `ExcludeFolderMask`, `Success`,
+  `Warning`, `Error`.
+- `Type`, `Category`, `ElementDescription`, `LogDebugMessages`, `SPSDebugMode`, `SPSDebugPort`,
+  `SPSDebugEntryPoints`, `AbortTimeoutMinutes`, `ScriptPackagePath`, `Xpos`, `Ypos`, `ElementIcon`,
+  `LastModified`, `Path`, `customExecutionMode`, `AdvancedTuningEnabled`, `Hold`, `TrafficType`,
+  `CorneringFactor`, `ElementType`.
+- `ApplicationPath`, `ApplicationLicense` (legal as a tag, but Switch silently drops these two from
+  the flow element's property set, so don't use them). These are app-only properties, set by the
+  user from the Switch Scripter GUI after packing — never modify them directly.
+
+Also required: tag matches `^[A-Za-z][A-Za-z0-9]*$` and does not start with `xml` (case-insensitive).
+
+---
+
+## Annotated example
+
+Representative declaration with Move connections, custom properties, and a dependency chain:
+
+```xml
+<Object>
+    <ElementFields>
+        <Name Editor="hide" Type="string">depositJob</Name>
+        <DisplayName Editor="hide" Type="string"></DisplayName>
+        <Version Editor="hide" Type="number">1</Version>
+        <Keywords Editor="hide" Type="string"></Keywords>
+        <Tooltip Editor="hide" Type="string"></Tooltip>
+        <IncomingConnections RequireAtLeastOne="Yes" Editor="hide">Yes</IncomingConnections>
+        <OutgoingConnections RequireAtLeastOne="Yes" DetailedInfo="" Editor="hide">Unlimited</OutgoingConnections>
+        <ConnectionType Editor="hide">Move</ConnectionType>
+        <FunctionsNodeJSScript Editor="hide">jobArrived</FunctionsNodeJSScript>
+        <ExecutionMode Editor="hide">Concurrent</ExecutionMode>
+        <NumberOfSlots Editor="hide">Default</NumberOfSlots>
+        <ExecutionGroup Editor="hide"></ExecutionGroup>
+        <PerformanceTuning Editor="hide">No</PerformanceTuning>
+        <IdleAfterJob Editor="hide" Type="number">0</IdleAfterJob>
+        <PositionInElementPane Editor="hide">Tools</PositionInElementPane>
+        <DispositionInElementPane Editor="hide" Type="number"></DispositionInElementPane>
+        <Description Editor="hide" Type="string"></Description>
+        <Connections Editor="hide" Type="string"></Connections>
+        <SwitchModule Editor="hide" Type="string">Scripting</SwitchModule>
+        <ObsoleteProperties Editor="hide" Type="string"></ObsoleteProperties>
+        <ObsoleteConnectionProperties Editor="hide" Type="string"></ObsoleteConnectionProperties>
+
+        <!-- Custom property: folder chooser -->
+        <DepositFolder UserDefined="true" Type="string" Editor="choosefolder" Subtype=""
+                        LocalizedTagName="Deposit folder" Tooltip="" DetailedInfo=""
+                        Validation="Standard" Default=""></DepositFolder>
+
+        <!-- Custom property: dropdown enum -->
+        <AttachAs UserDefined="true" Type="enum:Job;Dataset" Editor="inline" Subtype="inline"
+                  LocalizedTagName="Attach as" Tooltip="" DetailedInfo="" Validation="Standard"
+                  Default="Job">Job</AttachAs>
+
+        <!-- Custom property: bool, depends on AttachAs = "Dataset" -->
+        <IncludeMetadata UserDefined="true" Type="bool" Editor="inline" Subtype="inline"
+                          Dependency="AttachAs" DependencyCondition="Equals" Dependencyvalue="Dataset"
+                          LocalizedTagName="Include metadata" Tooltip="" DetailedInfo=""
+                          Validation="Standard" Default="No">No</IncludeMetadata>
+
+        <!-- Custom property: literal "Default" editor combined with a modal editor -->
+        <FallbackFolder UserDefined="true" Type="string" Editor="default;choosefolder" Subtype=""
+                         LocalizedTagName="Fallback folder" Tooltip="" DetailedInfo=""
+                         Validation="Standard" Default="Default">Default</FallbackFolder>
+    </ElementFields>
+    <ConnectionFields/>
+    <ExtraProperties/>
+</Object>
+```

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

@@ -0,0 +1,85 @@
+# Script Project Structure
+
+A Switch script project lives in a **script folder** during development and is distributed as a `.sscript` package (ZIP).
+
+> **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [api-script-declaration.md](api-script-declaration.md) for the declaration's rules. Leave `manifest.xml` to the user unless explicitly asked.
+
+## Script folder files
+
+| File | Required | Notes |
+|---|---|---|
+| `manifest.xml` | Yes | Switch internal use only. Do not edit manually. |
+| `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [api-script-declaration.md](api-script-declaration.md). |
+| `main.ts` | Yes (TypeScript) | Source file. Edit this. |
+| `main.js` | Yes | Compiled output executed by Switch. Generated by transpiling `main.ts`. |
+| `main.js.map` | No | Source map, generated alongside `main.js`. |
+| `package.json` | Yes (TypeScript) | NPM config for type declarations. |
+| `tsconfig.json` | Yes (TypeScript) | TypeScript transpilation options. |
+| `<IconFileName>.png` | No | 32×32 px, RGB, not interlaced. Extension must be `.png`. |
+| `node_modules/` | No | Local npm packages. |
+| `Resources/` | No | Extra resource files bundled when packing with SwitchScriptTool. |
+| `<LanguageCode>.ts` | No | Translation files (Switch App SDK). |
+| `.vscode/launch.json` | No | Debug config (created by SwitchScriptTool). |
+| `.vscode/switch.code-snippets` | No | Entry point snippets (TypeScript only). |
+
+> After editing `main.ts`, transpile with SwitchScriptTool to regenerate `main.js` before testing in Switch.
+
+## manifest.xml format
+
+```xml
+<Manifest>
+    <ScripterInstanceName>myScript</ScripterInstanceName>
+    <SwitchVersion>24.0</SwitchVersion>
+    <ScriptPackageFormatVersion>1.0</ScriptPackageFormatVersion>
+    <ScriptPasswordProtected>No</ScriptPasswordProtected>
+    <ScriptPackageType>Script</ScriptPackageType>
+    <ScriptDeclarationFile>myScript.xml</ScriptDeclarationFile>
+    <ScriptProgramFiles>
+        <ScriptProgramFile ScriptLanguage="NodeJSScript">main.ts</ScriptProgramFile>
+    </ScriptProgramFiles>
+    <ScriptIconFile>myScript_32.png</ScriptIconFile>
+    <LocalizationItems/>
+</Manifest>
+```
+
+`ScriptPackageType` is either `Script` (regular) or `App` (scripted plug-in).
+
+## Node.js version per Switch version
+
+`SwitchVersion` in `manifest.xml` determines which Node.js version executes the script — Switch uses the **latest** Node.js version bundled with the Switch release that created the script.
+
+| 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 |
+
+> **Mac (Apple Silicon):** For scripts created in Switch 2021 Fall or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts created in earlier versions run under Rosetta using the Intel Node.js build. If a script bundles platform-specific binaries, ship both Intel and ARM variants.
+
+## Script vs App
+
+| | Script | App |
+|---|---|---|
+| `ScriptPackageType` | `Script` | `App` |
+| Appears in Elements pane | No (used via Script element) | Yes, as its own element |
+| Distribution | Freely | Enfocus Appstore only |
+| Position in pane | — | Configured via `PositionInElementPane` in XML |
+
+## Execution modes
+
+Set in the XML declaration via SwitchScripter. Applies to all instances of the script.
+
+**Concurrent** — entry points for the same or different instances may run in parallel. Scripts must synchronize access to any shared resources.
+
+**Serialized** — entry points within the same **execution group** are never concurrent. Instances in different execution groups may still run in parallel.
+
+**Execution group** — only relevant for Serialized mode. Should be a reverse-domain string (e.g. `com.mycompany.myScript`) to avoid collisions. Defaults to the Script ID if left empty.
+
+See [api-execution-environment.md](api-execution-environment.md#two-independent-concurrency-tiers) — neither `NumberOfSlots` nor execution group maps to a count of Node.js OS processes; they gate job dispatch on the Switch Server, separate from the pooled executor processes that actually run script code.

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

@@ -0,0 +1,75 @@
+# Switch Class
+
+The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.
+
+## Global data
+
+Global data is key/value storage shared across entry point invocations, scoped by `Scope`.
+
+| Scope | Shared across |
+|---|---|
+| `Scope.FlowElement` | This script element instance only |
+| `Scope.FlowElements` | All instances of the same script in the same flow |
+| `Scope.Element` | All instances of the same script across all flows |
+| `Scope.Flow` | All elements in the same flow |
+| `Scope.Global` | Any element in any flow — use sparingly; prefix tags with your company name |
+
+Dates stored via `setGlobalData` are returned as strings by `getGlobalData` — parse them in your script.
+
+```ts
+s.getGlobalData(scope: Scope, tag: string, lock?: boolean): Promise<any>
+s.getGlobalData(scope: Scope, tags: string[], lock?: boolean): Promise<{ tag: string, value: any }[]>
+```
+Read one or multiple values. Returns `''` (empty string) for a tag that doesn't exist, not `undefined`. Optional `lock` (default `false`) prevents concurrent writes until `setGlobalData` is called or the entry point ends.
+
+More than 100 global data calls (`getGlobalData`/`setGlobalData` combined) in a single entry point invocation logs a warning — this is an advisory client-side counter, not an enforced server-side limit, but a sign the script should batch reads/writes.
+
+```ts
+s.setGlobalData(scope: Scope, tag: string, value: any): Promise<void>
+s.setGlobalData(scope: Scope, globalData: { tag: string, value: any }[]): Promise<void>
+```
+Write one or multiple values. Releases any lock held for the same scope/tag.
+
+```ts
+s.removeGlobalData(scope: Scope, tag: string): Promise<void>
+s.removeGlobalData(scope: Scope, tags: string[]): Promise<void>
+```
+Delete one or multiple global data entries.
+
+> **Global data is never removed automatically.** Entries persist in Switch's database until explicitly deleted with `removeGlobalData`. Scripts that skip cleanup accumulate entries indefinitely and can fill the database. Always remove global data as soon as it is no longer needed.
+
+## Webhooks
+
+```ts
+s.httpRequestSubscribe(method: HttpRequest.Method, path: string, args: any[]): Promise<void>
+```
+Subscribe to incoming HTTP requests. Call inside `flowStartTriggered`. The absolute URL is `https://<host>:51088/scripting/${path}`. `path` must start with `/` (e.g. `/my-path`) or the call throws `"Wrong format of the subscription path."`. The `args` array is forwarded to the `httpRequestTriggeredSync` / `httpRequestTriggeredAsync` entry points.
+
+```ts
+s.httpRequestUnsubscribe(method: HttpRequest.Method, path: string): Promise<void>
+```
+Unsubscribe a previously registered webhook.
+
+## Abort
+
+```ts
+s.setAbortData(abortData: any): void
+```
+Store a value that will be passed to the `abort` entry point when the configured abort timeout expires.
+
+## Server utilities
+
+```ts
+s.getPreferenceSetting(settingKey: string): Promise<any>
+```
+Retrieve a Switch preference setting. `settingKey` format: `"settingGroup"` or `"settingGroup/settingName"`. Returns `''` if the setting/group doesn't exist. Any field whose name contains `password`, `pwd`, or `secret` is redacted in the result. The returned value is JSON-stringified, not a raw object.
+
+```ts
+s.getServerVersion(): number
+```
+Returns the Switch server version as `majorVersion + updateNumber/100` (e.g. Switch 25.11 → `25.11`), not a literal version string — don't parse it as one.
+
+```ts
+Switch.tr(str: string): string
+```
+Static method. Marks a string literal for translation (used by SwitchScriptTool). Returns the string unchanged at runtime.

package/docs/switch-api/api-tooling.md

@@ -0,0 +1,61 @@
+# Script Folders, Packages & SwitchScriptTool
+
+## Script folder vs script package
+
+| | Script folder | Script package (`.sscript`) |
+|---|---|---|
+| Use for | Development, version control | Production, deployment |
+| Included in flow export | **No** | Yes |
+| TypeScript transpile | Manual — `SwitchScriptTool --transpile` | Automatic in SwitchScripter |
+| Password protection | Not supported | Optional |
+| Can be used as App | No — must pack first | Yes |
+
+Script folders are not included in flow exports or backups. Never use a script folder in production — pack it to a `.sscript` package first.
+
+## SwitchScriptTool
+
+Command-line tool included with Switch. May not be on `PATH` — fall back to the known install
+location for the current OS if the bare command isn't found.
+
+**Windows:** `C:\Program Files\Enfocus\Enfocus Switch\SwitchScriptTool\SwitchScriptTool.exe` (add to PATH to avoid typing the full path)
+
+**macOS:** symlinked to `/usr/local/bin/SwitchScriptTool` by the installer. If the symlink is missing, the real binary is bundled inside the SwitchScripter app: `/Applications/Enfocus/Enfocus Switch/SwitchScripter.app/Contents/MacOS/SwitchScriptTool/SwitchScriptTool`.
+
+## Commands
+
+| Mode | Command | Purpose |
+|---|---|---|
+| Create | `SwitchScriptTool --create <ScriptID> <Path> [--JavaScript]` | Scaffold a new script folder with all required files |
+| Transpile | `SwitchScriptTool --transpile <Path>` | Compile `main.ts` → `main.js`. **Must use this, not `tsc` directly** |
+| Pack | `SwitchScriptTool --pack <Folder> <Output> [--password <pwd>] [--verbose]` | Create `.sscript` package for deployment |
+| Unpack | `SwitchScriptTool --unpack <file.sscript> <Folder> [--password <pwd>]` | Extract package to folder |
+| List | `SwitchScriptTool --list <file.sscript>` | List package contents (no password needed) |
+| Generate translations | `SwitchScriptTool --generate-translations <ScriptFolder> <ResultFolder>` | Generate translation files for the script package |
+
+**Create** scaffolds: `manifest.xml`, `<ScriptID>.xml`, `<ScriptID>.sscript`, `main.ts` (or `main.js` with `--JavaScript`), `.vscode/launch.json`, `Resources/`, plus `package.json`, `tsconfig.json`, `.vscode/switch.code-snippets`, and type declarations for TypeScript. Creates `<Path>/<ScriptID>/` — it does not write into `<Path>` directly. `ScriptID` may only contain letters, digits, hyphens, and underscores.
+
+**Transpile** is required after every edit to `main.ts` before testing a **script folder** directly in Switch. Switch executes `main.js` only — `main.ts` is never run directly. Using SwitchScriptTool (not `tsc`) ensures the same transpile options as SwitchScripter, which is required for consistent behavior. This step is **not** needed before packing — see Pack below.
+
+**Pack** transpiles `main.ts` fresh into the package on every run; it never reads or modifies any `main.js` already sitting in the source folder (a stale hand-edited `main.js` there is ignored and left untouched — see the excluded-files note below). It always excludes `package.json` and `.vscode/` from the packed output, printed as an "Info: will not be packed" list even without `--verbose`; `--verbose` additionally prints the full list of what *will* be packed. `node_modules` is packed as-is, so run `npm prune --production` first (see Deployment) — otherwise `devDependencies` (including `@types/*` packages, which the scaffolded `package.json` puts there) get bundled into the package for no runtime benefit. One harmless quirk: the placeholder `<ScriptID>.sscript` file scaffolded by `--create` is not excluded and ends up packed inside the real `.sscript` too.
+
+**Unpack** prints package metadata (`Type`, `Protection`, `Status`) before extracting. For a TypeScript-sourced package it extracts only `main.ts` — the compiled `main.js`/`main.js.map` are not written back out, so a pack → unpack round trip returns a clean, editable script folder rather than a compiled snapshot.
+
+## Deployment
+
+Before packing, remove dev dependencies to reduce package size — this matters because `--pack` bundles `node_modules` as-is, and the scaffolded `package.json` puts type-only packages (`@types/node`, `@types/switch-scripting`, `undici-types`) under `devDependencies`:
+
+```
+npm prune --production
+```
+
+Then pack:
+
+```
+SwitchScriptTool --pack <ScriptFolder> <OutputFolder>
+```
+
+Reasons not to use a script folder in production:
+- Not included in flow exports or backups
+- Slower execution than a package
+- Any syntax error saved to `main.js` immediately breaks the running script
+- No password protection available

package/docs/switch-api/api-vscode.md

@@ -0,0 +1,62 @@
+# VS Code Setup
+
+## Type declarations
+
+Enables autocomplete and type checking for `Switch`, `Job`, `FlowElement` and all Switch API globals.
+
+**Via npm (preferred):** Add to `devDependencies` in `package.json` and run `npm install`:
+
+```json
+"@types/switch-scripting": "https://github.com/enfocus-switch/types-switch-scripting/archive/refs/tags/v24.1.1-final.tar.gz"
+```
+
+**Manual fallback:** Download `index.d.ts` from the types repo and place it at `node_modules/@types/switch-scripting/index.d.ts` inside the script folder.
+
+> `SwitchScriptTool --create` sets this up automatically for new TypeScript script folders.
+
+## TypeScript 6 / VS Code 1.114+
+
+From VS Code 1.114, TypeScript 6 is used. Ambient/global types are no longer auto-included — without explicit configuration, `@types/node` and `@types/switch-scripting` globals (`Switch`, `Job`, etc.) will not be recognised.
+
+Add a `types` array to `compilerOptions` in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "switch-scripting"]
+  }
+}
+```
+
+## ESLint rules
+
+Two rules that catch Switch-specific async bugs before runtime:
+
+- **`require-await`** — flags `async` functions that never actually `await`, catching accidentally dropped API call promises
+- **`@typescript-eslint/no-floating-promises`** — errors on any unawaited promise; in Switch scripts these cause silent race conditions that are very difficult to diagnose
+
+Example `.eslintrc`:
+
+```json
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": { "project": "./tsconfig.json" },
+  "plugins": ["@typescript-eslint", "prettier"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "rules": {
+    "require-await": 2,
+    "@typescript-eslint/no-floating-promises": 2,
+    "prettier/prettier": 2
+  }
+}
+```
+
+## Snippets
+
+`SwitchScriptTool --create` generates `.vscode/switch.code-snippets` with entry point scaffolding (prefix `switch…`). See the hub doc for details.