@enfocussw/switch-scripting-context 25.11.0-beta.9 → 25.11.1-beta.1

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

@@ -0,0 +1,75 @@
+---
+id: property-documentation
+category: switch-project
+order: 21
+summary: "Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections"
+triggers:
+  - "Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo`"
+---
+
+# Writing Property and Connection Documentation
+
+Guidance for the *content* of `Tooltip` and `DetailedInfo` on properties and connections — see
+[script-declaration.md](script-declaration.md#custom-property-elements-elementfields) for
+the attribute mechanics (when each is required, what breaks if omitted). This page covers what to
+actually write in them.
+
+Both attributes are read only inside Switch Designer, by someone who has already added the flow
+element to a flow. Compare with [app-store-listing.md](../switch-appstore/app-store-listing.md), read by
+someone deciding whether to install the app at all, and [app-manual.md](../switch-appstore/app-manual.md), a
+separate uploaded document.
+
+**Delivery:** write this content directly into the `Tooltip`/`DetailedInfo` attributes in
+`<ScriptID>.xml` — there is no separate file. See
+[script-declaration.md § Agent editing policy](script-declaration.md#agent-editing-policy)
+for how to edit the declaration safely.
+
+## Tooltip
+
+The one-line hint shown in the Properties pane. This is the field that matters most here — it's
+always visible to whoever is configuring the property, connection, or the app's own icon, with no
+extra click required.
+
+- Add information the property name doesn't already give: units, valid range, format, or an
+  example value. A tooltip that just restates the label ("Output folder: the output folder to
+  use") wastes the one line a user reliably reads.
+- If no sensible default is possible, put an example value in the tooltip — see the `Default`
+  guideline in [script-declaration.md](script-declaration.md#custom-property-elements-elementfields).
+- Sentence-style capitalization, no trailing period, one line. Match the style already used in
+  declarations: `Tooltip="Select the output folder"`.
+- Skip it only when the property is genuinely self-explanatory from its name alone, with no
+  constraints worth stating (e.g. "Number of copies" with no min/max).
+
+## DetailedInfo
+
+Feeds the HTML documentation Switch Designer can export for a whole *flow* — not something
+specific to this app, it's compiled from every element the flow builder happens to have placed in
+that flow. Real, but low priority in practice: it's an opt-in export most flow builders never
+generate, and plenty of shipped apps leave it blank. Don't treat an empty `DetailedInfo` as a
+defect to pad out.
+
+Fill it in when the tooltip's one line genuinely isn't enough — an interaction with another
+property, an edge case worth flagging, or why a setting matters, not a restatement of the tooltip
+in longer sentences. A trivial property with `DetailedInfo=""` is expected and fine.
+
+If you do write `DetailedInfo`, don't rely on it being the only place that content exists — the
+property's fuller description belongs in [app-manual.md](../switch-appstore/app-manual.md#properties-detailed-info)
+regardless, since that document is far more likely to actually be read.
+
+## Writing quality
+
+Applies to both fields, and is the same bar [app-store-listing.md](../switch-appstore/app-store-listing.md)
+and [app-manual.md](../switch-appstore/app-manual.md) hold their content to:
+
+- **Don't restate the field name.** A tooltip on "Output folder" that says "The output folder"
+  adds nothing a user didn't already know.
+- **No generic AI/marketing vocabulary** — powerful, seamless, robust, intuitive, and similar
+  words that could describe any property in any app. Say the specific thing this one does.
+- **No meta-commentary about the implementation.** Write what the user sees or does, not how the
+  script is coded internally ("this property is passed to the internal handler").
+- **No vague filler.** "Set this to an appropriate value" tells a user nothing; a concrete unit,
+  range, or example does.
+- **No copy-pasted boilerplate across properties.** Identical tooltip text reused on unrelated
+  properties signals nobody thought about the individual property.
+- **Keep it translatable.** Idioms and culture-specific references don't translate cleanly into
+  the six Switch languages — see [switch.md § Translation extraction rules](../switch-api/switch.md#translation-extraction-rules).

package/docs/{switch-api/api-property-editors.md → switch-project/property-editors.md}

@@ -1,20 +1,29 @@
+---
+id: property-editors
+category: switch-project
+order: 15
+summary: "Property editor types, string return values, literal editors, dropdowns"
+triggers:
+  - "Defining property editors in XML or reading property values in code"
+---
+
 # Property Editors
 
 Property editors determine how a user enters a value in Switch Designer, and what string is
 returned by `getPropertyStringValue()` at runtime. They're set in the XML declaration via the
 `Editor` and `Type` attributes on a custom property — see
-[api-script-declaration.md](api-script-declaration.md) for the surrounding attribute grammar.
+[script-declaration.md](script-declaration.md) for the surrounding attribute grammar.
 
 All property values are returned as `string` or `string[]`. `getPropertyType()` returns one of a
 fixed set of `PropertyType` values (`literal`, `string`, `number`, `date`, `boolean`, `filepath`,
-`folderpath`, `regex`, `oauthtoken`, etc. — see [api-enums.md](api-enums.md)) describing what kind of
+`folderpath`, `regex`, `oauthtoken`, etc. — see [enums.md](../switch-api/enums.md)) describing what kind of
 value is actually present; `literal` is only one of these, not a binary "literal vs. user-entered"
 flag. Use it before interpreting the returned string, e.g. to check for a literal editor's constant
 before comparing it.
 
 `Editor` is a `;`-joined list: the inline editor's token (if any) first, then modal editor tokens in
 the order they're offered. `Type` follows from which editor(s) are chosen — see the tables below and
-[the Type reference](api-script-declaration.md#type-reference).
+[the Type reference](script-declaration.md#type-reference).
 
 ---
 
@@ -48,8 +57,8 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `regexp` | Regular expression string as entered |
 | `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`) |
-| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) |
+| `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. |
 | `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 |
@@ -58,7 +67,7 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `filepatterns` | `string[]` — one pattern string per entry |
 | `folderpatterns` | `string[]` — one pattern string per entry |
 | `stringlist` (`Type="stringlist"`) | `string[]` — one string per line |
-| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](api-script-declaration.md#extraproperties) |
+| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](script-declaration.md#extraproperties) |
 | `external`, `external2`, … | File path to a property set edited by an external companion app |
 
 > Duplicate tokens in `Editor` are meaningless — each modal editor can only be offered once, except
@@ -75,6 +84,14 @@ constant as one of the choices; all literal tokens have `Type="string"`.
 Always call `getPropertyType()` first to check whether the value is a literal before comparing the
 string.
 
+Use the matching literal editor for a keyword-style value like "Default", "None", or "Automatic"
+instead of making it a typed string default — e.g. `default` instead of a `Default`
+attribute set to the literal text `"Default"`. Typing the keyword as an ordinary string default lets
+a user accidentally change it to arbitrary text and loses the `PropertyType.Literal` signal the
+script relies on. `none` is specifically the sanctioned way to let a property hold an empty value
+under `Validation="Standard"` — combine it into the `Editor` chain instead of relaxing to
+`Validation="None"` just to permit emptiness.
+
 | `Editor` token | `getPropertyStringValue()` returns |
 |---|---|
 | `default` | `"Default"` |
@@ -89,6 +106,19 @@ string.
 | `next` | `"Next"` |
 | `current` | `"Current"` |
 
+`nofiles`/`allfiles`/`allotherfiles` and `nofolders`/`allfolders`/`allotherfolders` are not
+general-purpose — every real use of them is a connection **include/exclude filter mask** (an
+`IncludeMask`/`ExcludeMask`, or `IncludeFolderMask`/`ExcludeFolderMask`, on a `ConnectionType="Filter"`
+connection). Switch Designer labels them "No/All/All other jobs" and "No/All folders" in that
+context, not the XML token names above. See [Common practices](#common-practices) below for the
+exact chain.
+
+`next` and `current` exist in the editor grammar but have no confirmed script-facing use case — no
+built-in Switch flow element declares a property using them, and Enfocus's own property-editor
+documentation omits both (along with `allotherfolders`, apparently by oversight, since it's used the
+same way as `allotherfiles`). Don't reach for `next`/`current` without confirming a concrete need
+first.
+
 ---
 
 ## Extra XML attributes for certain editors
@@ -115,6 +145,17 @@ flow is exported.
 The following are recommended conventions for pairing property kinds with editor chains, not
 restrictions enforced by Switch — a script writer can combine editors differently if asked to.
 
+Enable the dynamic editors (`sltextwithvar`/`mltextwithvar` and `conditionwithvar`, `scriptexp`)
+wherever the value could plausibly vary per job — the rows below already reflect this. Conversely,
+don't add them to a property whose value is inherently static (e.g. a dataset name, or anything a
+`Dependency` master needs to read at flow-configuration time) — offering a variable/script option
+there just invites a value the script can't sensibly use.
+
+**App guideline (mandatory for apps, recommended for scripts):** make sure at least one editor in
+the chain works without an add-on Switch module: `scriptexp` requires the Scripting Module, so never
+offer it as the property's only editor — pair it with a module-free option (e.g. `inline` or
+`sltextwithvar`) so the property still works for a user without that module.
+
 | Property kind | Recommended `Editor` chain | Why |
 |---|---|---|
 | Secret (password, token, API key) | `password` only | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. |
@@ -125,7 +166,9 @@ restrictions enforced by Switch — a script writer can combine editors differen
 | Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
 | Enum (`Type="enum:..."`) | `inline` only, always | No editor guarantees a var/expression result matches one of the declared items. |
 | File/folder path that must exist for the app to work | `choosefile`/`choosefolder` only | Switch validates the picked path exists at flow start. |
-| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [api-flow-element.md](api-flow-element.md#properties) if the path is needed later in the flow. |
+| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [flow-element.md](../switch-api/flow-element.md#properties) if the path is needed later in the flow. |
+| Connection include-mask filter (which jobs pass through) | `allfiles;allotherfiles;types;filepatterns;regexp;scriptexp`, `Default="All Files"`, `Subtype="allfiles"` | Matches Switch's own built-in connection filter properties exactly — `Default`/`Subtype` must hold the chosen literal's exact rendered string. Folder version: `allfolders;allotherfolders;folderpatterns;regexp;scriptexp` with `Default="All Folders"`, `Subtype="allfolders"`. |
+| Connection exclude-mask filter (which jobs are blocked) | `nofiles;types;filepatterns;regexp;scriptexp`, `Default="No Files"`, `Subtype="nofiles"` | Same reasoning as the include mask, starting from `nofiles` instead since there's no "exclude all/all other" case. Folder version: `nofolders;folderpatterns;regexp;scriptexp` with `Default="No Folders"`, `Subtype="nofolders"`. |
 
 `regexp`, `filetype`/`types`, `askplugin`/`askplugin2`, `oauth`, and `external` can technically be
 combined with `sltextwithvar`/`scriptexp` too, but this is uncommon in practice and not covered by a
@@ -137,8 +180,12 @@ dedicated row above.
 
 - **OAuth 2.0**: endpoint, client ID/secret, scope, and redirect ports are configured per-property
   in a matching `<ExtraProperties>` child element (see
-  [api-script-declaration.md § ExtraProperties](api-script-declaration.md#extraproperties)), not in
+  [script-declaration.md § ExtraProperties](script-declaration.md#extraproperties)), not in
   `Editor`/`Type`. The script receives a ready-to-use access token string via
   `getPropertyStringValue()`.
 - **External editor**: requires a separate companion application. The script receives a file path to
   the property set file. Entry point `findExternalEditorPath` resolves the editor executable path.
+  One of these two must be true — either a dependent property named `Application` (see
+  [Dependency](script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
+  the script implements `findExternalEditorPath` — see
+  [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks).

package/docs/{switch-api/api-script-declaration.md → switch-project/script-declaration.md}

@@ -1,3 +1,12 @@
+---
+id: script-declaration
+category: switch-project
+order: 14
+summary: "XML declaration reference: properties, connections, execution config; agents may edit this file directly"
+triggers:
+  - "Understanding, adding, or editing script properties/connections/execution config"
+---
+
 # Script Declaration (XML)
 
 The file `<ScriptID>.xml` defines the script's metadata, custom properties, connection properties,
@@ -13,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.
@@ -54,11 +65,11 @@ 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`. |
-| `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). |
+| `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). |
+| `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. |
 | `ExecutionMode` | `Concurrent` \| `Serialized` | |
@@ -108,13 +119,13 @@ 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 [api-property-editors.md](api-property-editors.md). |
+| `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`. |
-| `LocalizedTagName` | Display name shown in the Properties pane. |
-| `Tooltip` | Tooltip shown in the Properties pane. |
+| `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. |
-| `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. |
+| `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [property-editors.md § Literal editors](property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
+| `Default` | Default value string. Omit only if the value is emitted as CDATA instead. **App guideline (mandatory for apps, recommended for scripts):** always provide a default unless there's genuinely no sensible one; if a default truly isn't possible, give an example value in the `Tooltip` 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`. |
@@ -131,6 +142,24 @@ Key attributes:
               Validation="Standard" Default=""></OutputFolder>
 ```
 
+**Runtime pitfall:** when a dependent property is hidden (its master's current value doesn't satisfy
+`DependencyCondition`/`Dependencyvalue`), Switch treats the tag as if it doesn't exist. Calling
+`flowElement.getPropertyStringValue(tag)` on it throws `"Invalid tag: <tag>"` — see
+[flow-element.md](../switch-api/flow-element.md#properties). Only fetch a dependent property once you know
+its condition holds, either by checking the already-read master value yourself, or by calling
+`flowElement.hasProperty(tag)` first (it returns `false` for a hidden dependent). This matters most
+for an enum/drop-down master with several dependents keyed off different values — fetch only the
+ones actually shown for the current selection, not all of them.
+
+A script must never assume the set of fetchable dependents is fixed once at flow configuration
+time: if the master's own value is dynamic (a Switch variable or script expression, resolved per
+job in `jobArrived`), which dependents are shown can differ from job to job in the same flow
+execution. Re-check the condition (or call `hasProperty()`) on every invocation rather than caching
+an earlier "shown" determination. There is no way to read a currently-hidden dependent's value for
+a given job — if a script genuinely needs data from more than one dependency group at once (e.g.
+values entered while the master previously pointed elsewhere), this pattern cannot provide it, and
+a different property structure (not `Dependency`-based hiding) is needed instead.
+
 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.
 
@@ -172,6 +201,11 @@ most important thing to get right when hand-editing this section:
 
 Custom (author-defined) connection properties may be added regardless of `ConnectionType`.
 
+The declared connections and the script's `sendTo*()` calls must agree with each other — see
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) for the exact rules per
+`ConnectionType`. In particular, omit a `Success`/`Warning`/`Error` element entirely (as shown
+above) if the script never routes to it, rather than leaving an unused connection declared.
+
 **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
@@ -184,7 +218,7 @@ 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
+[property-editors.md](property-editors.md)). One child element per OAuth property, named
 identically to the property's tag, in `ElementFields` or `ConnectionFields`:
 
 ```xml
@@ -236,7 +270,7 @@ If no OAuth property exists on the script, omit `ExtraProperties` entirely or le
 
 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
+[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
 `PropertyType` counterpart while several runtime values (`filetype`, `folderpattern`, `regex`,
@@ -244,7 +278,7 @@ XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `tim
 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
+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
 editor's type wins: an inline Number editor plus those modal editors still yields `Type="number"`.
 

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

@@ -0,0 +1,188 @@
+---
+id: script-structure
+category: switch-project
+order: 10
+summary: "What files a script folder contains, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App"
+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"
+---
+
+# 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 [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.
+
+## 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 [script-declaration.md](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. Never bundle an Oracle Java Runtime Environment here — licensing terms don't permit redistributing it, in a script or an app. |
+| `<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
+
+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.
+
+## 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 |
+
+## Packing an app
+
+An app is produced by SwitchScripter, not by SwitchScriptTool, and the two workflows have to be
+joined up explicitly:
+
+- **A script folder can only be typed `Script`.** To ship one as an app, pack it with
+  `SwitchScriptTool --pack` first, then open the resulting package in SwitchScripter and change the
+  type to `App` before creating the `.enfpack`. If "Create pack" is greyed out, the type is still
+  `Script`.
+- **Extra files can't be managed while SwitchScripter is working with a script folder.** Convert to
+  a script package first. The conversion is reversible, so the `.pdesc` holding the extra-files
+  configuration can be round-tripped back into the script folder and kept in version control.
+- **Creating a pack does not save the script.** Save first, or the pack is built from the last
+  saved state.
+- **The pack ID is derived from the script ID and always starts with `com.enfocus.`**, whatever the
+  company name and domain in SwitchScripter preferences. To keep it stable across an update, open
+  the previous `.enfpack` rather than the `.sscript` — SwitchScripter carries the pack ID over from
+  the pack it opened, even if the script ID or domain has since changed.
+
+### SwitchScripter and Switch version compatibility
+
+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.
+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
+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.
+
+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.
+
+## App Store submission guidelines
+
+App-specific submission rules (localization, universal/signed macOS binaries, immutable extra
+files) live in [app-guidelines.md § App-only](../switch-appstore/app-guidelines.md#app-only), alongside the
+rest of the pre-publish checklist.
+
+## Execution modes
+
+`Concurrent`/`Serialized`, `ExecutionGroup` and `NumberOfSlots` are set in the XML declaration (see
+[script-declaration.md](script-declaration.md#built-in-elementfields) for the attributes)
+and documented in
+[execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes),
+which also explains why none of them maps to a count of Node.js processes.

package/docs/{switch-api/api-tooling.md → switch-project/tooling.md}

@@ -1,3 +1,12 @@
+---
+id: tooling
+category: switch-project
+order: 11
+summary: "SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment"
+triggers:
+  - "Running SwitchScriptTool: transpiling, packing, unpacking, or deploying"
+---
+
 # Script Folders, Packages & SwitchScriptTool
 
 ## Script folder vs script package
@@ -36,10 +45,87 @@ location for the current OS if the bare command isn't found.
 
 **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.
+**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. Pack also replaces `SwitchVersion` in the packed `manifest.xml` with SwitchScriptTool's own version (`--create` writes it too), and that value picks the Node.js version the package runs on. See [script-structure.md § What writes `SwitchVersion`](script-structure.md#what-writes-switchversion).
 
 **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.
 
+## Verify entry points before packing
+
+Switch's entry-point scanner is regex-based, not a real parser, and can silently drop entry-point
+functions from certain string/regex/division shapes — see
+[entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints).
+`--pack` does not validate or warn about this: a script that packs cleanly can still fail to load,
+or load with a property callback that silently never runs. Compiling and passing tests doesn't
+catch it either, since the source is syntactically valid JS/TS — only extraction against the built
+`main.js` does.
+
+After any edit to `main.ts`/`main.js`, run the extracted entry points against the **built**
+`main.js` and confirm the expected names come back. Python:
+
+```python
+#!/usr/bin/env python3
+import re, sys
+
+STRIP_PATTERN = re.compile(
+    r'(?:/\*.*?\*/)'
+    r'|(?:(["\'`])\1)'
+    r'|(?://.*?$)'
+    r'|(?:([/"\'`]).*?[^\\]\2)'
+    r'|(?:/(?:\\.|[^/\n])*/)'
+    r'|(?:\(\s*\w+\s*/\s*\w+\s*\))'
+    r'|(?:\w+\s*/\s*\w+)',
+    re.DOTALL | re.MULTILINE,
+)
+FUNC_PATTERN = re.compile(r'function[\s\n\r]+(\$?\w+)[\s\n\r]*\(', re.MULTILINE)
+NODE_ENTRY_POINTS = {
+    'timerFired', 'jobArrived', 'getLibraryForProperty', 'getLibraryForConnectionProperty',
+    'findExternalEditorPath', 'validateProperties', 'validateConnectionProperties',
+    'httpRequestTriggeredSync', 'httpRequestTriggeredAsync', 'flowStopTriggered',
+    'flowStartTriggered', 'abort',
+}
+REQUIRED_ANY = {'jobArrived', 'timerFired', 'flowStopTriggered', 'httpRequestTriggeredAsync'}
+
+code = open(sys.argv[1], encoding='utf-8').read()
+stripped = STRIP_PATTERN.sub('', code)
+found = [m.group(1) for m in FUNC_PATTERN.finditer(stripped) if m.group(1) in NODE_ENTRY_POINTS]
+print('Entry points found:', found or '(none)')
+if not (REQUIRED_ANY & set(found)):
+    sys.exit('FAIL: none of ' + str(sorted(REQUIRED_ANY)) + ' survived extraction.')
+```
+
+Or Node.js:
+
+```js
+#!/usr/bin/env node
+const fs = require('fs');
+
+const STRIP_PATTERN = /(?:\/\*[\s\S]*?\*\/)|(?:(["'`])\1)|(?:\/\/.*?$)|(?:([/"'`])[\s\S]*?[^\\]\2)|(?:\/(?:\\.|[^/\n])*\/)|(?:\(\s*\w+\s*\/\s*\w+\s*\))|(?:\w+\s*\/\s*\w+)/gm;
+const FUNC_PATTERN = /function[\s\n\r]+(\$?\w+)[\s\n\r]*\(/gm;
+const NODE_ENTRY_POINTS = new Set([
+  'timerFired', 'jobArrived', 'getLibraryForProperty', 'getLibraryForConnectionProperty',
+  'findExternalEditorPath', 'validateProperties', 'validateConnectionProperties',
+  'httpRequestTriggeredSync', 'httpRequestTriggeredAsync', 'flowStopTriggered',
+  'flowStartTriggered', 'abort',
+]);
+const REQUIRED_ANY = ['jobArrived', 'timerFired', 'flowStopTriggered', 'httpRequestTriggeredAsync'];
+
+const stripped = fs.readFileSync(process.argv[2], 'utf8').replace(STRIP_PATTERN, '');
+const found = [];
+let m;
+while ((m = FUNC_PATTERN.exec(stripped)) !== null) {
+  if (NODE_ENTRY_POINTS.has(m[1])) found.push(m[1]);
+}
+console.log('Entry points found:', found.length ? found : '(none)');
+if (!found.some((f) => REQUIRED_ANY.includes(f))) {
+  console.error('FAIL: none of', REQUIRED_ANY, 'survived extraction.');
+  process.exit(1);
+}
+```
+
+If the required entry point is missing, dump `stripped`/the stripped output and diff it against
+`main.js` — the first swallowed region starts at the string, regex, or division literal identified
+in the rules above.
+
 ## 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`: