@enfocussw/switch-scripting-context 0.1.0

package/docs/switch-api/switch.md

@@ -0,0 +1,210 @@
+---
+id: switch
+category: switch-api
+order: 3
+summary: "`Switch` (`s`): global data, webhooks, abort, server utilities"
+triggers:
+  - "Using global data, webhooks, abort, or server settings"
+---
+
+# Switch Class
+
+The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Global data
+  - Locking
+- Webhooks
+- Abort
+- Server utilities
+  - Translation extraction rules
+<!-- docs-index:contents end -->
+
+## Global data
+
+Global data is key/value storage shared across entry point invocations, scoped by `Scope`.
+
+| Scope | Shared across |
+|---|---|
+| `Scope.FlowElement` | This script element instance only |
+| `Scope.FlowElements` | All instances of the same script in the same flow (Switch 22.0+) |
+| `Scope.Element` | All instances of the same script across all flows |
+| `Scope.Flow` | All elements in the same flow (Switch 22.0+) |
+| `Scope.Global` | Any element in any flow — use sparingly; prefix tags with your company name |
+
+Dates stored via `setGlobalData` are returned as strings by `getGlobalData` — parse them in your script. Before Switch 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
+
+```ts
+s.getGlobalData(scope: Scope, tag: string, lock?: boolean): Promise<any>
+s.getGlobalData(scope: Scope, tags: string[], lock?: boolean): Promise<{ tag: string, value: any }[]>
+```
+Read one or multiple values. Returns `''` (empty string) for a tag that doesn't exist, not `undefined`. Optional `lock` (default `false`) locks the requested tags for this entry point invocation. Other invocations' reads, writes and locks on those tags wait until it is released. One invocation can hold only one lock at a time. See [Locking](#locking) for what releases a lock and for the one-lock rule.
+
+More than 100 global data calls (`getGlobalData`/`setGlobalData` combined) in a single entry point invocation logs a warning — this is an advisory client-side counter, not an enforced server-side limit, but a sign the script should batch reads/writes. The warning text starts "The script exceeded the maximum of 100 global data operations from within the same entry point execution. This may affect Switch performance."
+
+```ts
+s.setGlobalData(scope: Scope, tag: string, value: any): Promise<void>
+s.setGlobalData(scope: Scope, globalData: { tag: string, value: any }[]): Promise<void>
+```
+Write one or multiple values. Releases this invocation's lock on every tag it writes.
+
+```ts
+s.removeGlobalData(scope: Scope, tag: string): Promise<void>
+s.removeGlobalData(scope: Scope, tags: string[]): Promise<void>
+```
+Delete one or multiple global data entries. Releases this invocation's lock on every tag it removes.
+
+> **Global data is never removed automatically.** Entries persist in Switch's database until explicitly deleted with `removeGlobalData`. Scripts that skip cleanup accumulate entries indefinitely and can fill the database. Always remove global data as soon as it is no longer needed.
+
+### Locking
+
+A lock belongs to one entry point invocation. `getGlobalData(scope, tags, true)` takes it. It ends
+when that invocation writes the tag with `setGlobalData`, removes it with `removeGlobalData`, or
+when the entry point ends, including when it throws or hits its abort timeout.
+
+While one invocation holds a lock on a tag, other invocations behave like this:
+
+- A plain `getGlobalData` of the tag waits until the lock is released, then returns the value
+  written at release. It does not throw and does not return the old value.
+- A locked `getGlobalData` of the tag waits, then takes the lock. It does not throw.
+- `setGlobalData` of the tag waits, then writes, overwriting what the holder wrote at release.
+
+The holding invocation itself can read its locked tags normally.
+
+The server checks again every 200 ms and has no timeout of its own. If the waiting invocation hits
+its abort timeout, Switch aborts it as usual: the wait ends, and any tags it already holds from an
+array lock are released.
+
+**Gotcha: one lock per invocation.** While an invocation holds or is waiting for a lock, every
+further `getGlobalData(..., true)` in that invocation throws `Token is already locked` within a few
+milliseconds. That includes a tag nobody holds and the tag it already holds. After it releases the
+lock, it can lock again. The rule applies across scopes too, and a `setGlobalData` that
+writes only some of the locked tags leaves the others locked, so the next lock still throws.
+
+`Token is already locked` therefore always comes from the invocation's own earlier lock; contention
+with another invocation waits instead of throwing. Retrying on this error can't succeed. Fix the
+code path that takes the second lock.
+
+**Locking several tags.** The array form is the only way to hold more than one tag at once:
+
+- `getGlobalData(scope, [a, b], true)` locks every listed tag.
+- `setGlobalData(scope, [{ tag: a, value: ... }, { tag: b, value: ... }])` releases every listed
+  tag.
+
+**Caveat: an array lock is not all-or-nothing.** If one of the tags is locked elsewhere, the call
+keeps the tags it already has while it waits for the rest, and other invocations wait on those too.
+The tags are taken in alphabetical order whatever order they are listed in, so two
+array locks over the same tags can't deadlock each other.
+
+**Caveat: deadlock risk.** A waiting array lock keeps what it has, and plain
+reads and writes wait for locks. If invocation X locks `[a, b]`, gets `a` and waits for `b`, while
+invocation Y holds `b` and then reads or writes `a`, each waits for the other until one of them
+hits its abort timeout. To avoid it, don't read or write any tag other than the ones you locked
+while you hold a lock.
+
+Rules for a read-modify-write of shared tags:
+
+1. Lock every tag you will change in one `getGlobalData` call.
+2. Change the values and write them straight away, in one `setGlobalData` call covering every
+   locked tag.
+3. Release on every exit path. If the update fails, write the original values back (or remove the
+   tags) in a `catch` or `finally`, rather than leaving other invocations waiting until the entry
+   point ends.
+4. Don't hold a lock across job sends, file I/O, or network calls. Every other invocation's plain
+   read of the tag waits for as long as you hold it.
+
+See [job-patterns.md § Shared state in global data](job-patterns.md#shared-state-in-global-data)
+for the job-registration pattern written this way.
+
+## Webhooks
+
+Both methods need Switch 21.1+.
+
+```ts
+s.httpRequestSubscribe(method: HttpRequest.Method, path: string, args: any[]): Promise<void>
+```
+Subscribe to incoming HTTP requests. Call inside `flowStartTriggered`. The absolute URL is `https://<host>:51088/scripting/${path}`. `path` must start with `/` (e.g. `/my-path`) or the call throws `"Wrong format of the subscription path."`. The `args` array is forwarded to the `httpRequestTriggeredSync` / `httpRequestTriggeredAsync` entry points.
+
+```ts
+s.httpRequestUnsubscribe(method: HttpRequest.Method, path: string): Promise<void>
+```
+Unsubscribe a previously registered webhook.
+
+## Abort
+
+```ts
+// Switch 22.1+
+s.setAbortData(abortData: any): void
+```
+Store a value that will be passed to the `abort` entry point when the configured abort timeout expires.
+
+## Server utilities
+
+```ts
+// Switch 24.0+
+s.getPreferenceSetting(settingKey: string): Promise<any>
+```
+Retrieve a Switch preference setting. `settingKey` format: `"settingGroup"` or `"settingGroup/settingName"`. Returns `''` if the setting/group doesn't exist. Any field whose name contains `password`, `pwd`, or `secret` is redacted in the result. The returned value is JSON-stringified, not a raw object.
+
+```ts
+// Switch 24.0+
+s.getServerVersion(): number
+```
+Returns the Switch server version as `majorVersion + updateNumber/100` (e.g. Switch 25.11 → `25.11`), not a literal version string — don't parse it as one. The method doesn't exist before Switch 24.0, so it can't detect older versions; see [api-versions.md § Checking at runtime](api-versions.md#checking-at-runtime).
+
+```ts
+// Switch 22.0+
+Switch.tr(str: string): string
+```
+Static method. Marks a string literal for translation (used by SwitchScriptTool). Returns the string unchanged at runtime.
+
+### Translation extraction rules
+
+`SwitchScriptTool --generate-translations` extracts strings by **static analysis of the source
+text**, not by running it. It only ever sees a `Switch.tr(...)` call whose argument is a string
+literal, spelled exactly like that. Anything it can't resolve statically is silently skipped — no
+error, no warning, just a missing entry in the `.ts` file. Always check the generated `.ts` for the
+strings you expected.
+
+What extraction handles:
+
+```ts
+Switch.tr('single');            // single, double and backtick quotes all work
+Switch.tr(`multi
+line`);                         // multi-line literals work
+Switch.tr('one ' + 'two ');     // concatenation of literals works
+// The tr() call doesn't have to sit at the point of use:
+const s = Switch.tr('Predefined string');
+await job.log(LogLevel.Info, s);   // extracted, and translated at runtime
+```
+
+What it does **not** handle:
+
+```ts
+const t = Switch.tr;               // aliasing the function: never extracted
+await job.log(LogLevel.Info, t('nope'));
+
+const token = getToken();
+Switch.tr('prefix ' + token);      // concatenation with a non-literal
+Switch.tr(`prefix ${token}`);      // template interpolation
+Switch.tr('Job ID = ' + job.getId());
+```
+
+For dynamic values, mark the template and pass the values as `messageParams` — the template gets
+translated, the substituted values don't:
+
+```ts
+await job.log(LogLevel.Info, Switch.tr('Job ID = %1'), [job.getId()]);
+```
+
+Arguments can themselves be translated by wrapping them separately:
+
+```ts
+const mode = readOnly ? Switch.tr('Read-only') : Switch.tr('Regular');
+await job.log(LogLevel.Info, Switch.tr('Job ID = %1, Mode = %2'), [job.getId(), mode]);
+```
+
+See [logging.md § Placeholders instead of concatenation](logging.md#placeholders-instead-of-concatenation)
+for the same rule stated from the logging side.

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

@@ -0,0 +1,281 @@
+---
+id: app-guidelines
+category: switch-appstore
+order: 20
+summary: "Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries)"
+triggers:
+  - "Preparing a script for publication as an app, or reviewing one against Appstore submission criteria"
+---
+
+# App Publishing Guidelines
+
+A pre-publish checklist for a script intended for the Enfocus Appstore (`ScriptPackageType="App"`
+— see [script-structure.md § Script vs App](../switch-project/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. The one exception is
+[App-only](#app-only) at the bottom, which is documented in full here.
+
+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.
+
+---
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Properties
+- Entry points
+- Sending jobs
+- Logging
+- Temp files and paths
+- App-only
+  - Identity and versioning
+  - Top-level declaration properties
+  - Password protection
+  - Localization
+  - Icon
+  - Extra files
+  - Source and review hygiene
+  - What review does and doesn't cover
+<!-- docs-index:contents end -->
+
+## Properties
+
+- [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30
+  characters or fewer and uses sentence-style capitalization ("Customer name", not "Customer
+  Name") — see [script-declaration.md](../switch-project/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
+  [script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields) for
+  the attribute and [property-documentation.md](../switch-project/property-documentation.md) for what to write in it.
+- [ ] **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
+  [property-editors.md § Common practices](../switch-project/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
+  [property-editors.md § Literal editors](../switch-project/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 [entry-points.md § Property UI callbacks](../switch-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
+  [property-editors.md § Common practices](../switch-project/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
+  [property-editors.md § Notes](../switch-project/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
+  [script-declaration.md](../switch-project/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 [entry-points.md § Property UI callbacks](../switch-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 [entry-points.md § Job processing](../switch-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
+  [entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
+
+## Sending jobs
+
+All **universal** — see
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) and
+[script-declaration.md § ConnectionFields](../switch-project/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 [logging.md § Message quality](../switch-api/logging.md#message-quality).
+- [ ] **Universal.** Log messages are free of grammatical errors and typos — see
+  [logging.md § Message quality](../switch-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
+  [logging.md § Placeholders instead of concatenation](../switch-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
+  [logging.md § Log volume](../switch-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
+  [job-patterns.md § Temp file cleanup](../switch-api/job-patterns.md#temp-file-cleanup).
+- [ ] **Universal.** No Oracle JRE is embedded as an extra file, in a script or an app — see
+  [script-structure.md § Script folder files](../switch-project/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
+  [job-patterns.md § Platform-independent paths](../switch-api/job-patterns.md#platform-independent-paths).
+
+---
+
+## App-only
+
+The following apply only to `ScriptPackageType="App"`, not to a plain `Script` package at all.
+Unlike the sections above, these are documented in full here rather than deferring elsewhere.
+
+### Identity and versioning
+
+- [ ] **`Name` (Script ID) matches `[A-Za-z0-9_-]+`** — letters, digits, hyphens and underscores
+  only, no spaces. It must also be globally unique across the Appstore; Enfocus checks for clashes
+  at review and may require a change. Pick something unlikely to collide.
+- [ ] **`Name` never changes across versions.** It is what identifies the app in an existing
+  customer flow, so changing it breaks the upgrade path. `DisplayName` *can* change freely between
+  versions without breaking upgrades — so keep any third-party application version number out of
+  `Name`, and preferably out of `DisplayName` too, or every application release forces a rename.
+- [ ] **`Version` is only incremented once the previous version was actually published.** If a
+  submission is rejected, resubmit under the *same* version number rather than bumping. Minor
+  versions are allowed to one level (`1.1`, `1.10`, `1.34`); leading zeros are not (`1.01` is
+  invalid).
+- [ ] **Every app in an app bundle carries the same version**, including the master app entry.
+- [ ] **The pack ID always starts with `com.enfocus.`**, generated from the script ID, regardless
+  of the company name and domain set in SwitchScripter preferences. To keep it stable when
+  updating, open the existing `.enfpack` (not the `.sscript`) before re-packing — SwitchScripter
+  remembers the pack ID from the pack it opened.
+
+### Top-level declaration properties
+
+- [ ] **App-level `Tooltip` is filled in** — this is the tooltip on the icon in the Elements pane,
+  separate from the per-property tooltips above.
+- [ ] **`Keywords` is populated and matches the keywords on the app's Appstore detail page.** Words
+  already in `DisplayName` are implicitly searchable and don't need repeating. Matching is
+  case-insensitive.
+- [ ] **`ExecutionMode="Concurrent"` wherever the script allows it.** `Serialized` is the default
+  and the slower choice; concurrent is preferred for throughput. If you go concurrent, the script
+  must synchronise its own access to any shared resource — see
+  [execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes).
+- [ ] **`ExecutionGroup` is shared across every app that drives the same non-concurrent third-party
+  application**, so Switch can stop them using it simultaneously. If your app is in that situation,
+  ask Enfocus which group name to use rather than inventing one.
+- [ ] **`PerformanceTuning="Yes"` only with a concrete reason.** It exposes `IdleAfterJob` (and
+  `NumberOfSlots`) to the user; don't surface those knobs by default.
+- [ ] **At most three categories, and `SubcategoryInElementPane` is filled in.** New categories need
+  Enfocus Product Management approval, and an app listed in more than three needs additional
+  approval. Note that an unsigned app always loads under the **Custom** subcategory regardless of
+  what it declares — the declared subcategory only takes effect once Enfocus has signed the app, and
+  review may change it.
+- [ ] **`DetailedInfo` is written wherever it adds something a `Tooltip` can't carry** — not
+  mechanically on every property. It is optional: Switch Designer can export a *flow's* HTML
+  documentation from every element in it, so an empty `DetailedInfo` produces a blank entry there
+  if a flow builder ever generates one, which is a reason to fill it in where the property warrants
+  it, not a reason to pad out every trivial one. See
+  [property-documentation.md](../switch-project/property-documentation.md) for what to write in it, and when
+  it's fine to leave blank. The [app manual](app-manual.md#flow-elements-properties) is the surface
+  users are far more likely to read, and it needs real per-property content regardless of what
+  `DetailedInfo` holds.
+- [ ] **`Description`, `Compatibility`, `SupportInfo` and `AppDiscovery` are filled in.** These are
+  required to create the `.enfpack` at all, and `SupportInfo` must point at *your* support channel,
+  never Enfocus Support — see [app-store-listing.md](app-store-listing.md) for what to write
+  in each.
+- [ ] **The app manual document is prepared**, following Enfocus's `documentation-app_name.docx`
+  template, and uploaded during Appstore review — see [app-manual.md](app-manual.md).
+- [ ] **The declared incoming/outgoing connection topology matches what the code actually does** —
+  see [Entry points](#entry-points) and [Sending jobs](#sending-jobs) above.
+- [ ] **Dependent properties have real dependency conditions and values, never left empty**, and the
+  script does not read a dependent property's value when its master isn't set to the value that
+  makes it relevant.
+
+### Password protection
+
+- [ ] **The app is password protected with a non-trivial password** (8+ characters, mixed case,
+  digits, symbols). Enfocus checks the password strength at review.
+- [ ] **Don't lose the password.** For a Node.js app, Switch runs an obfuscated copy of the code
+  produced at save time and never needs the original source, so the protection is genuinely
+  one-way: Enfocus cannot recover a Node.js script's source if the author forgets the password.
+  (For legacy JavaScript/VBScript a bypass mechanism exists internally at Enfocus, so that
+  protection is weaker — another reason to be on Node.js.)
+- [ ] Note that a published Node.js app ships only the obfuscated code, re-protected with a random
+  password Enfocus generates during review — not the password you set.
+
+### Localization
+
+- [ ] **Prefer more than one language.** An app is preferably localized beyond English — see
+  [Translation files](../switch-project/script-structure.md#script-folder-files) (`<LanguageCode>.ts`) and
+  `SwitchScriptTool --generate-translations` in [tooling.md](../switch-project/tooling.md).
+- [ ] **The app's own translations are limited to the six Switch UI languages** (English, French,
+  German, Italian, Chinese, Japanese); other languages are not accepted for the app itself. The
+  separate Appstore *documentation* may be supplied in additional languages, since it isn't
+  generated through the SDK.
+- [ ] **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 rather than hardcoding English text that bypasses it. Note that
+  `Switch.tr()` extraction is static and silently skips anything that isn't a plain string literal
+  — see [switch.md § Translation extraction rules](../switch-api/switch.md#translation-extraction-rules).
+  Check the generated `.ts` files rather than assuming.
+
+### Icon
+
+- [ ] **32×32 PNG, RGB, transparent background**, attached as the app icon. This is what appears in
+  the Elements pane and in flows.
+- [ ] **A separate icon (at least 200×200, square) is uploaded to the Appstore submission form**
+  for the Appstore listing — it is not part of the pack. See
+  [app-store-submission.md § Icons](app-store-submission.md#icons) for both assets' exact
+  specs and how to derive/verify them from source art.
+
+### Extra files
+
+- [ ] **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. Relying on Rosetta 2 costs performance and isn't a long-term option.
+- [ ] **macOS Mach-O binaries in extra files must be signed and notarized.** An unsigned or
+  incorrectly signed executable or dynamic library will fail Appstore review. At minimum, sign with
+  hardened runtime enabled and a secure timestamp; verify with `codesign -dv <file>` and check the
+  output contains a `Timestamp` line and the `runtime` flag on the `CodeDirectory` line.
+- [ ] **Extra files must not change at runtime.** Don't place files the script might modify or
+  regenerate at runtime — license files included — 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
+  [job-patterns.md § Temp file cleanup](../switch-api/job-patterns.md#temp-file-cleanup).
+- [ ] Find bundled files at runtime with `flowElement.getPluginResourcesPath()` — see
+  [flow-element.md](../switch-api/flow-element.md).
+
+### Source and review hygiene
+
+- [ ] **Comments in the source are in English**, so Enfocus reviewers can read them.
+- [ ] **No malicious or unrelated payload** — nothing that harms the user's machine or installs
+  additional software.
+- [ ] **No Oracle JRE embedded**, in a script or an app, for licensing reasons — see
+  [script-structure.md § Script folder files](../switch-project/script-structure.md#script-folder-files).
+- [ ] **Automating a third-party application doesn't breach that application's licence.** Some
+  vendors' terms explicitly exclude automation; check before building.
+
+### What review does and doesn't cover
+
+Enfocus verifies that the app loads correctly and becomes available as a flow element, and checks
+the items above. It does **not** test that the app works — functional correctness, error handling,
+code structure and naming are the app creator's responsibility, though good practice in all of them
+is assumed. Items marked as rejection-triggers in the SDK's own checklist are the identity,
+password, icon, signing and architecture ones above.
+
+Budget roughly **10 business days** for a review. An unsigned app only loads in Switch on the
+machine that created it, which is what makes local testing possible before submission; once signed
+it loads anywhere. Apps require Switch 13.1 or later.

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

@@ -0,0 +1,84 @@
+---
+id: app-manual
+category: switch-appstore
+order: 23
+summary: "Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template)"
+triggers:
+  - "Preparing the app manual document for Appstore submission"
+---
+
+# Writing the App Manual
+
+Guidance for the separate Word/PDF document an app creator uploads during Appstore review,
+following Enfocus's `documentation-app_name.docx` template. Enfocus shows it as a downloadable
+document on the app's Appstore detail page — distinct from the
+[listing fields](app-store-listing.md) shown inline on the listing itself, and from
+[Tooltip/DetailedInfo](../switch-project/property-documentation.md), seen only after installing. Follow the
+template's section order below; don't invent your own structure.
+
+**Delivery:** there's no declaration attribute for this content, since it isn't part of the app
+itself. Write it to `./DOCUMENTATION.md` at the project root, using the section headers below. The
+user copies each section into Enfocus's `documentation-app_name.docx` template and uploads the
+result during Appstore review; tell them that's the next step once the file is written.
+
+Same writing-quality bar as [property-documentation.md § Writing quality](../switch-project/property-documentation.md#writing-quality):
+no restated field names, no generic marketing vocabulary, no meta-commentary about the
+implementation, no vague filler, no copy-pasted boilerplate, nothing that won't translate cleanly.
+
+## App name
+
+The declaration's `DisplayName`.
+
+## Description
+
+Reuse [the listing's `Description`](app-store-listing.md#description) — adapt lightly if the
+extra room here helps (e.g. a screenshot the listing field can't carry), but don't rewrite the
+same facts from scratch.
+
+## Compatibility
+
+**Not the same field as the declaration's `Compatibility` attribute** — see the naming trap in
+[app-store-listing.md § Compatibility](app-store-listing.md#compatibility). This section
+is the minimum **Switch** version the app requires, e.g. "Switch 24.10 and higher." There's no
+declaration attribute for it; it's implicit in which SwitchScripter version built the app (see
+[script-structure.md § SwitchScripter and Switch version compatibility](../switch-project/script-structure.md#switchscripter-and-switch-version-compatibility)).
+The same value also goes in the "Switch Version" field on the
+[Appstore App Version submission form](app-store-submission.md#fields-that-reuse-content-youve-already-written)
+— state it explicitly here rather than leaving it for the reader to infer.
+
+## Compatibility third-party applications
+
+Reuse [the listing's `Compatibility`](app-store-listing.md#compatibility) content — the
+third-party application versions this app supports, with links to the vendor's download/version
+page where one exists.
+
+## Application discovery details
+
+Reuse [the listing's `AppDiscovery`](app-store-listing.md#appdiscovery) content. Add a
+screenshot here if the discovery mechanism (or the manual-path property, when auto-detection
+fails) is easier to show than describe.
+
+## Connections
+
+Reuse [the listing's `Connections`](app-store-listing.md#connections) content, expanded with
+whatever detail or screenshots the shorter listing field couldn't carry.
+
+## Properties detailed info
+
+Reuse each property's and connection's [`DetailedInfo`](../switch-project/property-documentation.md#detailedinfo)
+content — but don't limit this section to whatever `DetailedInfo` happens to contain. `DetailedInfo`
+is optional and often left blank; this manual is the far more likely surface to actually be read,
+so write real per-property content here even for properties where `DetailedInfo` was skipped.
+
+For an app bundle (multiple flow elements in one pack), document each flow element separately —
+the template repeats this section per element ("Flow element 1", "Flow element 2", …).
+
+### Flow elements properties
+
+Per flow element, per property: what it controls, and any tip or constraint a user needs to get
+the element working — the same content `DetailedInfo` would hold, written in full regardless of
+whether `DetailedInfo` itself was filled in.
+
+### Outgoing connections properties
+
+Same treatment, for injected connection properties.

package/docs/switch-appstore/app-store-listing.md

@@ -0,0 +1,69 @@
+---
+id: app-store-listing
+category: switch-appstore
+order: 22
+summary: "Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`"
+triggers:
+  - "Writing or reviewing the app's Appstore listing text"
+---
+
+# Writing the Appstore Listing Fields
+
+Guidance for the *content* of the declaration's prose fields that appear on the app's Enfocus
+Appstore listing: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, and `Connections`
+— see [script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields) for the
+attribute mechanics.
+
+Audience here is a prospective buyer browsing the Appstore, deciding whether to install the app at
+all — they haven't seen the flow element yet. That's different from
+[property-documentation.md](../switch-project/property-documentation.md) (`Tooltip`/`DetailedInfo`, read only
+after installing) and from [app-manual.md](app-manual.md) (a separate uploaded document).
+This content is also reused directly in the app manual's Description, Compatibility third-party
+applications, Application discovery details, and Connections sections — write it once, here, well.
+
+**Delivery:** write this content directly into the matching top-level attributes in
+`<ScriptID>.xml` (`Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`) —
+there is no separate file. See
+[script-declaration.md § Agent editing policy](../switch-project/script-declaration.md#agent-editing-policy)
+for how to edit the declaration safely.
+
+Same writing-quality bar as [property-documentation.md § Writing quality](../switch-project/property-documentation.md#writing-quality):
+no restated field names, no generic marketing vocabulary, no meta-commentary about the
+implementation, no vague filler, no copy-pasted boilerplate, nothing that won't translate cleanly.
+
+## `Description`
+
+What the app does, who it's for, and the third-party application or service it automates. Lead
+with the concrete task the app performs, not a category label — "Converts incoming PDFs to the
+customer's house color profile using ColorLogic" tells a buyer more than "A color management
+app." A screenshot is worth adding here if it clarifies the app's purpose faster than prose would.
+
+## `Compatibility`
+
+**Naming trap:** despite the name, this is **third-party application** compatibility, not Switch
+version compatibility — Switch has no declaration field for the minimum Switch version an app
+requires (see [app-manual.md § Compatibility](app-manual.md#compatibility) for where that
+goes instead). State which versions of the automated third-party application are supported, e.g.
+"Requires Acrobat Pro DC 2023 or later." Link to the third-party vendor's own download or version
+page if one exists.
+
+## `SupportInfo`
+
+The app creator's own support channel (email or URL) — **never Enfocus Support**, this is
+mandatory per [app-guidelines.md § App-only](app-guidelines.md#top-level-declaration-properties).
+State the channel plainly; this field has no dedicated section in the app manual, so it's the only
+place this information reliably reaches a buyer before they install.
+
+## `AppDiscovery`
+
+How the app locates the third-party application on disk. State the actual mechanism, concretely
+enough that a user who hits a failure knows what to check: which known install paths are searched
+first, and — if auto-detection can fail — which property lets the user point at the install
+location manually.
+
+## `Connections`
+
+A prose overview of the flow element's incoming and outgoing connections: what triggers the
+element, what each outgoing connection carries, and when a job is routed to which one. This is the
+topology summary a flow builder reads before wiring the element into a flow, so describe behavior
+("routes to Error when validation fails"), not just connection names.