@enfocussw/switch-scripting-context 25.11.0-beta.10 → 25.11.0-beta.11

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.0-beta.11] - 2026-09-08
+
+### Added
+- `api-entry-points.md` — documented that Switch's entry-point scanner is regex-based (not a real
+  parser) and can silently drop `function` declarations from certain source shapes: string literals
+  ending in a backslash, regex literals (especially ones containing an unescaped `/` inside a
+  character class), and division not in a plain `word / word` shape. Applies to every entry point,
+  not just the ones checked at load time; `calculateScriptExpression` is the one exception, since
+  it's dispatched directly rather than through this scanner. Verified against real
+  `SwitchScriptTool --pack` output for each failure mode.
+- `api-tooling.md` — new "Verify entry points before packing" section with a Python/Node.js script
+  to check a built `main.js` for the expected entry points before relying on `--pack`, which doesn't
+  validate this itself.
+- `api-script-structure.md` — cross-linked the entry-point scanner constraints from the "Agent
+  editing policy" callout.
+- `api-app-guidelines.md` — new pre-publish checklist for scripts submitted to the Enfocus Appstore,
+  covering property naming/tooltip/editor/default requirements, entry point and `sendTo*()`
+  consistency with declared connections, logging quality, temp file/path handling, and app-only
+  packaging rules (no embedded Oracle JRE, universal signed macOS Mach-O binaries in extra files,
+  immutable extra files, translation completeness). Registered in the routing table, both `init.ts`
+  doc-file arrays, and the README's included-docs list.
+
+### Changed
+- `switch-scripting.md` — broadened the `api-entry-points.md` routing-table trigger to any edit to
+  `main.ts`/`main.js`, not just adding a new entry point.
+- `api-property-editors.md` — documented that the `nofiles`/`allfiles`/`allotherfiles` and
+  `nofolders`/`allfolders`/`allotherfolders` literal editors are specifically for connection
+  include/exclude filter mask properties, with the exact `Editor`/`Default`/`Subtype` chain verified
+  against Switch's own built-in connection filter declarations; added the matching rows to Common
+  practices. Noted that `next`/`current` have no confirmed script-facing use case. Noted that `none`
+  is the sanctioned way to allow an empty value under `Validation="Standard"`.
+- `api-script-declaration.md` — cross-linked the `Validation` row to the `none` literal editor for
+  allowing empty values under `Standard` validation.
+- `api-app-guidelines.md`, `api-script-declaration.md`, `api-property-editors.md`,
+  `api-entry-points.md`, `api-job-patterns.md`, `api-logging.md`, `api-script-structure.md` —
+  reclassified the Appstore submission rules added previously: most turned out to be universal
+  correctness rules (functional requirements or bugs if violated) rather than app-specific policy,
+  so their "App guideline" framing was removed and they're now stated as plain rules that apply to
+  every script. Only a handful remain "mandatory for apps, recommended for scripts" (property
+  naming/tooltip/default, non-module-editor requirement, log volume, platform-independent paths).
+  "No embedded Oracle JRE" moved out of the app-only section entirely, since it applies to any
+  script bundling extra files. `api-app-guidelines.md` is now organized into three explicit tiers
+  (Universal / Apps required-scripts recommended / Apps only) instead of one flat list.
+- `api-script-declaration.md`, `api-property-editors.md`, `api-entry-points.md`, `api-job-patterns.md`,
+  `api-job.md`, `api-logging.md`, `api-script-structure.md` — wove the individual Appstore submission
+  rules (above) directly into the relevant existing sections (property attributes, editor tables,
+  entry point signatures, `sendTo*()`/`ConnectionType` rules, logging conventions, packaging), each
+  cross-linked to and from the new checklist, so they're followed from the start rather than caught
+  only at a pre-publish review.
+- `api-script-declaration.md` — fixed the `Validation="Custom"` row, which named a nonexistent
+  `isPropertyValid` entry point; the actual entry point (per `api-entry-points.md`) is
+  `validateProperties`/`validateConnectionProperties`.
+- `api-job-patterns.md` — clarified that the automatic executor-refresh cleanup only applies to
+  temp files created via `flowElement.createPathWithName()` (the recommended default); temp files
+  created any other way must be cleaned up explicitly by the script. Also notes that the `tmp` npm
+  package is not recommended, and if used anyway, its `setGracefulCleanup()` is not always reliable
+  in the Switch execution environment and `discardDescriptor: true` should be set.
+- `api-flow-element.md`, `api-connection.md`, `api-script-declaration.md` — cross-linked and made
+  explicit that `getPropertyStringValue()`/`connection.getPropertyStringValue()` throws
+  `"Invalid tag: <tag>"` for a `Dependency` dependent property currently hidden by its master's
+  value, and that `hasProperty()`/`connection.hasProperty()` should be used to guard against this
+  (e.g. before fetching properties dependent on a drop-down/enum master). Also notes that the shown
+  set can vary per job if the master's value is dynamic, and that a hidden dependent's value cannot
+  be read at all — a script needing more than one dependency group's data at once must use a
+  different property structure, not `Dependency`-based hiding.
+
 ## [25.11.0-beta.10] - 2026-09-03
 
 ### Added

package/README.md

@@ -149,3 +149,4 @@ The `switch-docs/` folder contains:
 - `switch-api/api-property-editors.md` — property editor types and string return values
 - `switch-api/api-job-patterns.md` — file access semantics, routing rules, child jobs, executor limits
 - `switch-api/api-execution-environment.md` — process model, state persistence across jobs, error handling, npm/native module constraints
+- `switch-api/api-app-guidelines.md` — pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging

package/dist/init.js

@@ -95,6 +95,7 @@ function generateCursorMdc(docsDir) {
         'api-execution-environment.md',
         'api-logging.md',
         'api-logs-and-dataroot.md',
+        'api-app-guidelines.md',
     ];
     const fileList = apiFiles.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
     return `---
@@ -152,6 +153,7 @@ const API_FILES = [
     'api-execution-environment.md',
     'api-logging.md',
     'api-logs-and-dataroot.md',
+    'api-app-guidelines.md',
 ];
 function inlineApiFileList(docsDir) {
     return API_FILES.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');

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

@@ -0,0 +1,122 @@
+# App Publishing Guidelines
+
+A pre-publish checklist for a script intended for the Enfocus Appstore (`ScriptPackageType="App"`
+— see [api-script-structure.md § Script vs App](api-script-structure.md#script-vs-app)). Each item
+here is enforced in more detail at the linked section — this page exists to be read top-to-bottom
+right before submission, not as the primary source for any individual rule.
+
+Items fall into three tiers, marked on each one:
+
+- **Universal** — a correctness rule for every script, app or not. Violating it is a bug, not a
+  style choice.
+- **Apps required / scripts recommended** — mandatory for Appstore review; worth following in a
+  plain `Script` too, but not enforced there.
+- **Apps only** — doesn't apply to a plain `Script` package at all.
+
+---
+
+## Properties
+
+- [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30
+  characters or fewer and uses sentence-style capitalization ("Customer name", not "Customer
+  Name") — see [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+- [ ] **Apps required / scripts recommended.** Every property has a `Tooltip`, unless it's fully
+  self-explanatory with no extra constraints (e.g. "Number of copies" with no min/max) — see
+  [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+- [ ] **Universal.** Dynamic editors (`sltextwithvar`/`mltextwithvar`, `conditionwithvar`,
+  `scriptexp`) are enabled wherever the value could plausibly vary per job, and omitted where the
+  value is inherently static (e.g. a dataset name) — see
+  [api-property-editors.md § Common practices](api-property-editors.md#common-practices).
+- [ ] **Universal.** Keyword-style default values ("Default", "None", "Automatic", …) use the
+  matching literal editor (`default`, `none`, `automatic`, …), not a typed string default — see
+  [api-property-editors.md § Literal editors](api-property-editors.md#literal-editors).
+- [ ] **Universal.** Every property using `askplugin`/`askplugin2` ("Select from library"/"Select
+  many from library") has a matching `getLibraryForProperty`/`getLibraryForConnectionProperty`
+  entry point — see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+- [ ] **Apps required / scripts recommended.** Every property's editor chain includes at least one
+  editor that doesn't require an add-on Switch module — e.g. never offer `scriptexp` (Scripting
+  Module) as the only editor — see
+  [api-property-editors.md § Common practices](api-property-editors.md#common-practices).
+- [ ] **Universal.** Every property using the `external`/`external2`/… editor has either a
+  non-empty dependent `Application` property or a `findExternalEditorPath` entry point — see
+  [api-property-editors.md § Notes](api-property-editors.md#notes).
+- [ ] **Apps required / scripts recommended.** Every property has a default value unless one
+  genuinely isn't possible, in which case the `Tooltip` gives an example value instead — see
+  [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+- [ ] **Universal.** Every property/connection field declaring `Validation="Custom"` or `"Standard
+  and custom"` has a matching `validateProperties`/`validateConnectionProperties` entry point —
+  see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+
+## Entry points
+
+- [ ] **Universal.** `jobArrived` is present when `IncomingConnections="Yes"`; `timerFired` is
+  present when `IncomingConnections="No"` (and may additionally be present alongside `jobArrived`)
+  — see [api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+- [ ] **Universal.** No empty `jobArrived` or `timerFired` — an entry point that does nothing is
+  removed entirely, not left in place — see
+  [api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+
+## Sending jobs
+
+All **universal** — see
+[api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) and
+[api-script-declaration.md § ConnectionFields](api-script-declaration.md#connectionfields) for full
+detail.
+
+- [ ] If `OutgoingConnections` is not `No`, some `sendTo*()` method is called at least once for
+  any job actually routed (a purely timer/event-driven script that never touches a job is a
+  legitimate exception).
+- [ ] If `OutgoingConnections="Unlimited"`, `job.sendToSingle()` is never used.
+- [ ] `ConnectionType="Move"` never uses `job.sendToData()`/`job.sendToLog()`.
+- [ ] `ConnectionType="TrafficLight"` uses only `job.sendToData()`/`job.sendToLog()`; `sendToData`
+  is used when a Data Success/Warning/Error connection is enabled, `sendToLog` when the
+  corresponding Log connection is enabled.
+- [ ] An unused Success/Warning/Error connection is omitted from `ConnectionFields` entirely, not
+  left declared but unrouted.
+- [ ] A job with no output calls `job.sendToNull()`.
+- [ ] `job.fail()`/`flowElement.failProcess()` is used for genuine processing errors; an error
+  `TrafficLight` connection isn't used as a substitute for `fail()`.
+
+## Logging
+
+- [ ] **Universal.** An `Error` is logged when a custom
+  `validateProperties`/`validateConnectionProperties` check returns `valid: false` for a tag, and
+  when `getLibraryForProperty`/`getLibraryForConnectionProperty` would otherwise return an empty
+  list — see [api-logging.md § Message quality](api-logging.md#message-quality).
+- [ ] **Universal.** Log messages are free of grammatical errors and typos — see
+  [api-logging.md § Message quality](api-logging.md#message-quality).
+- [ ] **Universal.** Log messages use `%1`/`%2`/… placeholders with `messageParams`, not string
+  concatenation or interpolation of dynamic values — required for correct translation. See
+  [api-logging.md § Placeholders instead of concatenation](api-logging.md#placeholders-instead-of-concatenation),
+  which also covers the separate, narrower literal-`%` escaping gotcha.
+- [ ] **Apps required / scripts recommended.** Logging isn't excessive — no `Info`/`Debug` calls
+  that don't help a flow operator or support engineer understand what happened — see
+  [api-logging.md § Log volume](api-logging.md#log-volume).
+
+## Temp files and paths
+
+- [ ] **Universal.** All temporary files and folders are removed by the script before it finishes,
+  rather than relying on Switch's executor-refresh cleanup — see
+  [api-job-patterns.md § Temp file cleanup](api-job-patterns.md#temp-file-cleanup).
+- [ ] **Universal.** No Oracle JRE is embedded as an extra file, in a script or an app — see
+  [api-script-structure.md § Script folder files](api-script-structure.md#script-folder-files).
+- [ ] **Apps required / scripts recommended.** File system path strings are built with Node's
+  `path` module, not hardcoded separators or string concatenation — see
+  [api-job-patterns.md § Platform-independent paths](api-job-patterns.md#platform-independent-paths).
+
+---
+
+## App-only
+
+The following apply only to `ScriptPackageType="App"`, not to a plain `Script` package at all. See
+[api-script-structure.md § App Store submission guidelines](api-script-structure.md#app-store-submission-guidelines)
+for full detail.
+
+- [ ] The app is preferably available in more languages than just English.
+- [ ] Where translations are used, they're complete (every shipped language has every string), and
+  logging goes through the translation mechanism rather than hardcoded English.
+- [ ] Any macOS Mach-O binaries (executables or dynamic libraries) in extra files are built for
+  both `x86_64` and `arm64`.
+- [ ] Any macOS Mach-O binaries in extra files are signed.
+- [ ] No file that might be modified or regenerated at runtime is placed inside the app's own
+  package folder — that would fail the app's signature validation and cause Switch to remove it.

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

@@ -26,7 +26,7 @@ Connection properties are declared in the script's XML declaration (`ConnectionF
 ```ts
 connection.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
-Returns the connection property value as a string.
+Returns the connection property value as a string. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [api-script-declaration.md § Dependency](api-script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally.
 
 ```ts
 connection.getPropertyType(tag: string): PropertyType
@@ -41,7 +41,7 @@ Returns the English display name of the property (for use in log messages).
 ```ts
 connection.hasProperty(tag: string): boolean
 ```
-Returns `true` if the property exists and is visible for the current configuration.
+Returns `true` if the property exists and is visible for the current configuration. Use this to guard `getPropertyStringValue(tag)` calls on `Dependency` dependents — see the note above.
 
 ## File count
 

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

@@ -2,6 +2,54 @@
 
 Entry points are top-level `async` functions with specific names. They are **not exported**. Switch calls them automatically based on flow events.
 
+## Entry-point scanner constraints
+
+Switch discovers a script's entry points by regex, not by parsing. Before matching
+`function\s+(name)\s*\(` it strips comments and literals with a regex that doesn't understand JS
+escaping. Certain source shapes make that strip regex delete large spans of real code — and every
+`function` declaration inside the deleted span becomes invisible to Switch, whether or not that
+function is itself well-formed.
+
+This applies to **every** entry point on this page, not only the four checked below — a swallowed
+`validateProperties` or `getLibraryForProperty` fails silently (the callback just never runs, no
+error anywhere), which is worse than the loud failure the four below produce. The one exception is
+`calculateScriptExpression`: it's invoked directly at runtime rather than through this scanner, so
+it isn't at risk.
+
+If none of `jobArrived`, `timerFired`, `flowStopTriggered`, `httpRequestTriggeredAsync` survives,
+Switch fails with `Cannot open script '<name>': no entry points found` — `httpRequestTriggeredSync`
+alone does not satisfy this check. Both the packed `.sscript` (the entry-point list is baked in at
+pack time) and the unpacked script folder (`main.js` is rescanned by this same scanner every time
+Switch loads it, e.g. running or debugging from Designer) are affected. Packing does not validate
+or warn about any of this — a script that packs cleanly can still fail to load.
+
+**Rules for writing entry points in `main.ts`/`main.js`:**
+
+1. Never write a string literal whose content ends with a backslash: `"\\"`, `'\\'`, `` `\\` ``,
+   `"C:\\Temp\\"`. This is the highest-frequency trigger — the strip regex hunts for the next
+   matching quote character anywhere later in the file to close the literal (a backslash right
+   before the real closing quote makes it skip past that quote), and deletes everything in between.
+   Use `"\x5c"`, `"\u005C"`, `String.fromCharCode(92)`, or restructure (e.g.
+   `JSON.stringify(v).slice(1, -1)` for backslash/quote escaping) instead. A backslash elsewhere in
+   the literal is fine: `"\\n is newline"`, `"a\\b"`.
+2. Avoid regex literals — including ones that look properly closed, like `/[^/]+/` (a character
+   class containing an unescaped `/`). The strip regex doesn't understand character classes, so it
+   closes the "literal" early at the inner `/` and leaves a dangling `/` that swallows forward to
+   the next `/` anywhere later in the file. Use `new RegExp("...")` instead.
+3. Avoid division that isn't in the plain `word / word` shape. `a / b` is recognised and stripped
+   safely; `) / 2`, `] / 2`, and `/=` are not, and the leftover `/` swallows forward exactly like an
+   unclosed regex literal. Rewrite as `Math.floor(x / y)` with plain identifiers, or hoist to a
+   named variable first.
+4. Declare every entry point with the literal `function` keyword at top level:
+   `function jobArrived(...)` or `async function jobArrived(...)`. Arrow functions,
+   `exports.jobArrived = function (...)`, and class methods are invisible to the scanner.
+5. Entry-point names are matched case-sensitively. `JobArrived` is silently dropped during
+   extraction — if another valid entry point is also present the script packs and loads without
+   error, the misnamed function just never runs.
+
+See [api-tooling.md § Verify entry points before packing](api-tooling.md#verify-entry-points-before-packing)
+for a script to catch this before it reaches Switch.
+
 ## Flow lifecycle
 
 ```ts
@@ -21,6 +69,10 @@ async function timerFired(s: Switch, flowElement: FlowElement): Promise<void>
 ```
 Called on a recurring timer. First fires after `flowStartTriggered`. Set the interval via `flowElement.setTimerInterval(seconds)`. Cannot coexist with `flowStartTriggered` as the sole entry point.
 
+Required when `IncomingConnections="No"`; optional (alongside `jobArrived`) when
+`IncomingConnections="Yes"`. Never leave it present but empty — remove it entirely if it does
+nothing.
+
 ## Job processing
 
 ```ts
@@ -28,6 +80,12 @@ async function jobArrived(s: Switch, flowElement: FlowElement, job: Job): Promis
 ```
 Called when a job arrives. Must eventually call a `job.sendTo*()` or `job.fail()`. Can run concurrently if configured in the script XML declaration.
 
+`jobArrived` and `timerFired` presence must match the declared connections — present when
+`IncomingConnections="Yes"` (`timerFired` may additionally be present); when
+`IncomingConnections="No"`, `timerFired` must be present instead. See
+[api-script-declaration.md](api-script-declaration.md#built-in-elementfields). Never leave an empty
+`jobArrived` or `timerFired` in the script — remove the function entirely if it does nothing.
+
 ```ts
 async function abort(s: Switch, flowElement: FlowElement, job: Job, abortData: any): Promise<void>
 ```
@@ -59,24 +117,34 @@ Not available for debugging.
 ```ts
 async function getLibraryForProperty(s: Switch, flowElement: FlowElement, tag: string): Promise<string[]>
 ```
-Returns a dynamic list of values for a property's library dropdown.
+Returns a dynamic list of values for a property's library dropdown. Mandatory if any property uses
+the `askplugin`/`askplugin2` editor (see
+[api-property-editors.md](api-property-editors.md#modal-editors)). Log an error via `flowElement.log()`
+if the list would otherwise come back empty, so the user can see why the dropdown has nothing in it.
 
 ```ts
 async function getLibraryForConnectionProperty(s: Switch, flowElement: FlowElement, c: Connection, tag: string): Promise<string[]>
 ```
-Returns a dynamic list of values for a connection property's library dropdown.
+Returns a dynamic list of values for a connection property's library dropdown. Same guidance as
+`getLibraryForProperty` above, for connection fields using `askplugin`/`askplugin2`.
 
 ```ts
 async function validateProperties(s: Switch, flowElement: FlowElement, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
 ```
-Validates one or more property values. Return one result object per tag.
+Validates one or more property values. Return one result object per tag. Mandatory if any property
+declares `Validation="Custom"` or `"Standard and custom"` (see
+[api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields)). Log
+an error via `flowElement.log()` for any tag returned with `valid: false`, so the user sees why.
 
 ```ts
 async function validateConnectionProperties(s: Switch, flowElement: FlowElement, c: Connection, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
 ```
-Validates one or more connection property values.
+Validates one or more connection property values. Same guidance as `validateProperties` above, for
+connection fields declaring `Validation="Custom"`/`"Standard and custom"`.
 
 ```ts
 async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag: string): Promise<string>
 ```
-Resolves the path to an external editor for a property.
+Resolves the path to an external editor for a property. Required whenever the
+`external`/`external2`/… editor is used, unless the dependent `Application` property is non-empty —
+see [api-property-editors.md § Notes](api-property-editors.md#notes).

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

@@ -21,7 +21,7 @@ Properties are configured by the user in the Switch canvas and declared in the s
 ```ts
 flowElement.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
-Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown or a hidden dependent property. See [api-property-editors.md](api-property-editors.md) for editor types and their return value formats.
+Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [api-script-declaration.md § Dependency](api-script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally. See [api-property-editors.md](api-property-editors.md) for editor types and their return value formats.
 
 > **Dynamic values (Switch variables and script expressions) are only resolved when `getPropertyStringValue()` is called from `jobArrived`.** In any other entry point (e.g. `timerFired`) the raw unresolved string is returned.
 >
@@ -40,7 +40,7 @@ Returns the English display name of the property (for use in log messages).
 ```ts
 flowElement.hasProperty(tag: string): boolean
 ```
-Returns `true` if the property exists and is visible for the current configuration.
+Returns `true` if the property exists and is visible for the current configuration. Use this to guard `getPropertyStringValue(tag)` calls on `Dependency` dependents — see the note above.
 
 ## Connections
 
@@ -75,7 +75,7 @@ Logs a fatal error and puts the element into the "problem process" state. `messa
 ```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 [api-job-patterns.md](api-job-patterns.md) for temp file cleanup rules and routing constraints.
+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 [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [api-job-patterns.md](api-job-patterns.md#sending-jobs) for routing constraints.
 
 ```ts
 flowElement.getJobs(ids: string[]): Promise<Job[]>
@@ -94,7 +94,7 @@ Subscribes to a channel to receive jobs from it. Only one subscriber per channel
 ```ts
 flowElement.createPathWithName(name: string, createFolder: boolean): Promise<any>
 ```
-Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first.
+Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first. This is the recommended way to create temp files — see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup) for cleanup rules, including why this method should be preferred over ad hoc temp-file approaches like the `tmp` npm package.
 
 ```ts
 flowElement.getFileCount(nested?: boolean): Promise<number>

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

@@ -25,7 +25,24 @@ Switch does **not** automatically clean up files you create or pass to job-creat
 - Files/folders passed to `job.createChild(path)` — delete after routing.
 - Files/folders passed to `job.createDataset(name, filePath, model)` — delete after routing.
 
-> Files accumulate between executor refreshes if not cleaned up. The executor is refreshed after 5 min idle, 5,000 tasks, 150 MB memory, or 1,024 open file handles — at which point accumulated files are removed automatically, but do not rely on this.
+Use `flowElement.createPathWithName()` to create temp files by default — its output lives in the executor's temp area, which Switch removes automatically on executor refresh. Even so, delete explicitly after routing rather than relying on that refresh (see below).
+
+If a temp file is created some other way (e.g. `fs`/`path` writing outside the temp area, or a library that writes its own scratch files), the same rule applies: the script must delete it explicitly. Don't rely on Switch's executor-refresh cleanup for files outside the temp area — it only removes what it put there, so anything else creates a permanent leak.
+
+The [`tmp`](https://www.npmjs.com/package/tmp) npm package is common in scripts written by app creators, but it is **not recommended** here — prefer `flowElement.createPathWithName()` instead. If `tmp` is used anyway: its `setGracefulCleanup()` is not always reliable in the Switch script execution environment, so don't depend on it for cleanup — delete the file explicitly after routing regardless. Also pass `discardDescriptor: true` when creating a temp path (e.g. `tmp.fileSync({ discardDescriptor: true })`), or the open file descriptor can leak.
+
+> Files accumulate between executor refreshes if not cleaned up. The executor is refreshed after 5 min idle, 5,000 tasks, 150 MB memory, or 1,024 open file handles — at which point accumulated files **created via `createPathWithName()`** are removed automatically, but do not rely on this.
+
+---
+
+## Platform-independent paths
+
+Switch Server runs on both Windows and macOS. **App guideline (mandatory for apps, recommended for
+scripts):** a script package should work unmodified on either — paths returned by `job.get()`,
+`flowElement.createPathWithName()`, and similar methods use the host OS's native separator, so avoid
+hardcoding `/` or `\` when building or splitting a path, and don't assume one form when comparing or
+matching paths. Use Node's `path` module (`path.join`, `path.resolve`, `path.sep`, `path.basename`,
+etc.) instead of string concatenation.
 
 ---
 
@@ -49,6 +66,27 @@ await child.sendTo(conn2);
 await fs.promises.rm(tempPath);
 ```
 
+**Consistency with declared connections** (applies to every script, not just apps):
+- If `OutgoingConnections` is not `No`, the script must call some `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.
+- If `OutgoingConnections="Unlimited"` (more than one outgoing connection allowed), never use
+  `job.sendToSingle()` — it only makes sense when exactly one outgoing connection exists.
+- If no output is produced for a job, call `job.sendToNull()` rather than leaving it unrouted.
+- `ConnectionType="Move"` (see [api-script-declaration.md](api-script-declaration.md#connectionfields)):
+  never use `job.sendToData()`/`job.sendToLog()` — those are for `TrafficLight` connections only. Use
+  `job.sendTo()`/`job.sendToSingle()`.
+- `ConnectionType="TrafficLight"`: use only `job.sendToData()`/`job.sendToLog()` — never
+  `job.sendTo()`/`job.sendToSingle()`. Use `sendToData` when a Data Success/Warning/Error connection
+  is enabled in the declaration, and `sendToLog` when the corresponding Log connection is enabled.
+  Conversely, don't declare a Success/Warning/Error element the script never routes to — omit it from
+  `ConnectionFields` entirely (see the TrafficLight example in
+  [api-script-declaration.md](api-script-declaration.md#connectionfields)).
+- Prefer `job.fail()`/`flowElement.failProcess()` for genuine processing errors (see
+  [api-logging.md](api-logging.md)) over silently routing a failed job to a generic error connection —
+  reserve an error `TrafficLight` connection for cases the flow author should be able to reroute
+  downstream, not as a substitute for `fail()`.
+
 ---
 
 ## Dataset writes must precede child job creation

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

@@ -36,7 +36,7 @@ Returns the local filesystem path to the job. Use `AccessLevel.ReadOnly` to read
 
 ## Routing
 
-Every job must be routed exactly once.
+Every job must be routed exactly once. See [api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) for which `sendTo*()` method is appropriate for a given `ConnectionType`/`OutgoingConnections` declaration.
 
 ```ts
 job.sendToNull(): Promise<void>
@@ -92,7 +92,7 @@ Log a message including job context. To log a literal `%`, pass it as a param: `
 ```ts
 job.createChild(path: string): Promise<Job>
 ```
-Creates a new job inheriting the processing history, metadata, and private data of the parent. Takes effect immediately: the child's datasets are copied from the parent's *current* server-side state, so any pending `createDataset()` write not yet flushed by a `sendTo*()` call is not reflected in it. See [api-job-patterns.md](api-job-patterns.md#dataset-writes-must-precede-child-job-creation) — creating a child before writing a dataset is a common source of bugs. The caller is responsible for cleaning up the source file after routing.
+Creates a new job inheriting the processing history, metadata, and private data of the parent. Takes effect immediately: the child's datasets are copied from the parent's *current* server-side state, so any pending `createDataset()` write not yet flushed by a `sendTo*()` call is not reflected in it. See [api-job-patterns.md](api-job-patterns.md#dataset-writes-must-precede-child-job-creation) — creating a child before writing a dataset is a common source of bugs. The caller is responsible for cleaning up the source file after routing (see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup)).
 
 ## Private data
 
@@ -128,7 +128,7 @@ List all datasets attached to the job. **Immediate**: reads server state at once
 ```ts
 job.createDataset(name: string, filePath: string, model: DatasetModel): Promise<void>
 ```
-Attach a new dataset. **Deferred**: registers in-memory only; the file is not uploaded until the next `sendTo*()` call. Caller must clean up the source file.
+Attach a new dataset. **Deferred**: registers in-memory only; the file is not uploaded until the next `sendTo*()` call. Caller must clean up the source file after routing — see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup).
 
 ```ts
 job.getDataset(name: string, accessLevel: AccessLevel): Promise<string>

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

@@ -51,3 +51,36 @@ job.log(LogLevel.Info, '%1', [urlThatMightContainPercent]);
 `job.fail(message, messageParams?: (string | number | boolean)[])` takes an **array**.
 `flowElement.failProcess(message, messageParam?: string | number | boolean)` takes a **single
 value**, not an array. Passing an array to `failProcess` is a common mistake.
+
+## Placeholders instead of concatenation
+
+Build log messages with `%1`, `%2`, … placeholders and pass the dynamic values as
+`messageParams`/`messageParam`, rather than concatenating or interpolating them into the message
+string (beyond the literal-`%` escaping case above). A concatenated message can't be translated
+correctly — word order and pluralization vary by language, so a translator needs the message
+template and the substituted values kept separate. This matters even for a script that only ships in
+English today if it might ever be localized later.
+
+```ts
+// Avoid — can't be translated correctly, and hits the literal-% gotcha if fileName contains one
+job.log(LogLevel.Info, `Processed file ${fileName} in ${seconds}s`);
+
+// Prefer
+job.log(LogLevel.Info, 'Processed file %1 in %2s', [fileName, seconds]);
+```
+
+## Message quality
+
+- Log messages are user-facing text — proofread them. A message with grammatical errors or typos
+  looks unfinished and undermines trust.
+- Log an `Error` when a custom `validateProperties`/`validateConnectionProperties` check returns
+  `valid: false` for a tag, and when `getLibraryForProperty`/`getLibraryForConnectionProperty` would
+  otherwise return an empty list — see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+  Silently returning `false`/`[]` with no log line leaves the user without any explanation.
+
+## Log volume
+
+**App guideline (mandatory for apps, recommended for scripts):** don't over-log. Beyond the
+[Logging in loops](#logging-in-loops) guidance, avoid `Info`/`Debug` calls that don't help a flow
+operator or support engineer understand what happened — every extra message adds noise (and
+translation burden, for an app) without adding signal.

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

@@ -48,8 +48,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 [api-entry-points.md](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 [api-entry-points.md](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 |
@@ -75,6 +75,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 +97,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 +136,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. |
@@ -126,6 +158,8 @@ restrictions enforced by Switch — a script writer can combine editors differen
 | 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. |
+| 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
@@ -142,3 +176,7 @@ dedicated row above.
   `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](api-script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
+  the script implements `findExternalEditorPath` — see
+  [api-entry-points.md](api-entry-points.md#property-ui-callbacks).

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

@@ -57,8 +57,8 @@ 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`. 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). |
+| `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 [api-entry-points.md](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 [api-job-patterns.md § Sending jobs](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` | |
@@ -110,11 +110,11 @@ Key attributes:
 | `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. |
+| `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 [api-entry-points.md](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 [api-property-editors.md § Literal editors](api-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 +131,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
+[api-flow-element.md](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 +190,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
+[api-job-patterns.md § Sending jobs](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

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

@@ -2,7 +2,7 @@
 
 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.
+> **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, and [api-entry-points.md § Entry-point scanner constraints](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
 
@@ -17,7 +17,7 @@ A Switch script project lives in a **script folder** during development and is d
 | `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. |
+| `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). |
@@ -72,6 +72,31 @@ A Switch script project lives in a **script folder** during development and is d
 | Distribution | Freely | Enfocus Appstore only |
 | Position in pane | — | Configured via `PositionInElementPane` in XML |
 
+## App Store submission guidelines
+
+The following apply **only** to `ScriptPackageType="App"` (Appstore submission) — not to a plain
+`Script` package — beyond the general property/entry-point/logging conventions covered elsewhere in
+these docs:
+
+- **Prefer more than one language.** An app is preferably localized beyond English — see
+  [Translation files](#script-folder-files) (`<LanguageCode>.ts`) and
+  `SwitchScriptTool --generate-translations` in [api-tooling.md](api-tooling.md).
+- **Translations must be complete, and logging must go through the translation mechanism.** A
+  partially-translated app (some strings translated, others not) is not acceptable — every
+  user-facing message needs an entry in each shipped language file, and log calls must go through
+  that mechanism (see [api-switch.md](api-switch.md) for `Switch.translate`) rather than
+  hardcoding English text that bypasses it.
+- **macOS Mach-O binaries in extra files (`Resources/`) must be universal.** Any bundled macOS
+  application, framework bundle, executable, or dynamic library must include both `x86_64` and
+  `arm64` architectures.
+- **macOS Mach-O binaries in extra files must be signed.** An unsigned executable or dynamic
+  library bundled as an extra file will fail Appstore review.
+- **Extra files must not change at runtime.** Don't place files the script might modify or
+  regenerate at runtime inside the app's own package folder — Switch validates the app package's
+  signature, and content that changes after signing fails that validation, causing Switch to remove
+  the app. Write runtime-mutable data (temp files, caches, generated output) outside the app
+  folder — see [api-job-patterns.md § Temp file cleanup](api-job-patterns.md#temp-file-cleanup).
+
 ## Execution modes
 
 Set in the XML declaration via SwitchScripter. Applies to all instances of the script.

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

@@ -40,6 +40,83 @@ location for the current OS if the bare command isn't found.
 
 **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
+[api-entry-points.md § Entry-point scanner constraints](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`:

package/docs/switch-scripting.md

@@ -11,7 +11,7 @@ Detailed API docs are in `docs/switch-api/`:
 
 | File | Contents | Load when |
 |---|---|---|
-| `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a new script or adding an entry point |
+| `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
 | `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
 | `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
 | `switch-api/api-job.md` | `Job` — routing, file access, child jobs, private data, datasets | Processing/routing jobs, file access, private data, datasets |
@@ -29,6 +29,7 @@ Detailed API docs are in `docs/switch-api/`:
 | `switch-api/api-execution-environment.md` | Process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
 | `switch-api/api-logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
 | `switch-api/api-logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
+| `switch-api/api-app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
 
 ## Key rules
 - Always consult the API reference files above before writing or modifying script code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.0-beta.10",
+  "version": "25.11.0-beta.11",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",
@@ -40,7 +40,7 @@
   "license": "ISC",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/samw_pacol/enf-switch-scripting-context.git"
+    "url": "git+https://github.com/esko-bv/enf-switch-scripting-context.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -50,9 +50,9 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   },
-  "homepage": "https://github.com/samw_pacol/enf-switch-scripting-context#readme",
+  "homepage": "https://github.com/esko-bv/enf-switch-scripting-context#readme",
   "bugs": {
-    "url": "https://github.com/samw_pacol/enf-switch-scripting-context/issues"
+    "url": "https://github.com/esko-bv/enf-switch-scripting-context/issues"
   },
   "engines": {
     "node": ">=18"