@enfocussw/switch-scripting-context 25.11.0-beta.12 → 25.11.0-beta.13

package/CHANGELOG.md

@@ -5,6 +5,69 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.0-beta.13] - 2026-09-09
+
+### Fixed
+- README's two CHANGELOG links pointed at an unversioned jsdelivr URL, which always serves the
+  *latest published* file. On GitHub that showed the published file rather than the repo's live one,
+  hiding unreleased entries. Both are now relative links, so GitHub resolves them to the live file.
+- Generated tool config (Cursor, Codex/OpenCode, Windsurf, Zed, Cline) — the "Core rules" block told
+  agents never to edit `<ScriptID>.xml` and to send the user to SwitchScripter instead. That has
+  contradicted `api-script-declaration.md` and the `switch-scripting.md` key rules since the agent
+  editing policy was added, and it sat in an always-on rules file that outranks any doc the agent
+  loads later. Now matches the docs: direct editing is fine under the declaration's rules.
+
+### Added
+- `api-switch.md` — a "Translation extraction rules" section under `Switch.tr()`. Extraction is
+  static source analysis, so aliasing `Switch.tr`, concatenating with a variable, or interpolating
+  a template literal silently produces no translation entry at all. Documents what does work
+  (all quote styles, multi-line, literal-only concatenation, marking a string away from its use
+  site) and the `%1` + `messageParams` pattern for dynamic values.
+- `api-job-patterns.md` — "Driving a third-party CLI application", the Node.js replacement for the
+  legacy `findApplicationPath`/`ApplicationPath` mechanism: a custom path property on the
+  `automatic;choosefile;sltextwithvar;scriptexp` chain, resolved once in `flowStartTriggered` into
+  `Scope.FlowElement` global data, with `failProcess()` when discovery fails and cleanup in
+  `flowStopTriggered`.
+- `api-script-structure.md` — "Packing an app" and SwitchScripter/Switch version compatibility:
+  script folders can only be typed `Script` (pack, then retype to `App` in SwitchScripter), extra
+  files are unavailable in script-folder mode, the pack ID is always `com.enfocus.*` and is carried
+  over by opening the previous `.enfpack`, an app loads only in its build version or newer (no
+  Scripter for 25.07/25.11 — use 2024 Fall), and an unsigned app loads only on the machine that
+  built it.
+- `api-app-guidelines.md` — the App-only section is now split into Identity and versioning,
+  Top-level declaration properties, Password protection, Localization, Icon, Extra files, Source
+  and review hygiene, and what review does and doesn't cover. New rules from the App SDK: script ID
+  charset and uniqueness, resubmit-without-bumping after a rejection, minor-version format, the
+  three-category limit and Product Management approval, unsigned apps always loading under
+  "Custom", `DetailedInfo` feeding the generated HTML docs, `ExecutionGroup` coordination for a
+  shared third-party application, `Compatibility`/`SupportInfo`/`AppDiscovery` being required to
+  build the pack at all, Node.js password protection being unrecoverable, the six-language limit on
+  app translations, the 200×200 Appstore icon, and macOS notarization checks via `codesign -dv`.
+- Generated tool config and `switch-scripting.md` key rules — added the entry-point scanner
+  constraints (literal `function` keyword; no trailing-backslash string literals, regex literals, or
+  non-`word / word` division) to the always-on rules. Previously these lived only in
+  `api-entry-points.md`, so an agent making a small edit without opening that file had no signal
+  that the failure mode exists, and it fails silently.
+
+### Changed
+- Generated tool config for Cursor, Codex/OpenCode, Windsurf, Zed and Cline now lists each API doc
+  with its "Load when" routing text instead of a bare filename, so those agents can open the one
+  file they need without reading `switch-scripting.md` first. Costs ~600 tokens in the always-on
+  block, saves a ~1,300-token hub read per session.
+- The routing table in `docs/switch-scripting.md` is now the single source for that list. `init.ts`
+  parses it (`parseRoutingTable()`); the two hardcoded 19-entry arrays are gone, as is the drift
+  they invited.
+- `api-script-structure.md` — moved "App Store submission guidelines" into
+  `api-app-guidelines.md` § App-only and "Execution modes" into `api-execution-environment.md`,
+  leaving pointers at both old headings. Reviewing an app or reasoning about concurrency previously
+  needed two files for one topic. Existing anchor links still resolve.
+- `docs/switch-scripting.md` and `README.md` — sharpened the routing descriptions for
+  `api-job.md` (signatures) vs `api-job-patterns.md` (rules and gotchas), and for
+  `api-script-structure.md` vs `api-tooling.md`. Their triggers overlapped enough that an agent had
+  to load both files for any job-handling task.
+- `init` no longer copies `docs/superpowers`, `docs/temp`, or `.DS_Store` into a consuming project.
+  The published tarball already excludes them, but `init` run from a git clone did not.
+
 ## [25.11.0-beta.12] - 2026-09-08
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
 
 Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context/CHANGELOG.md) (also included in this package) for what's changed between versions.
+See [CHANGELOG.md](CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -84,7 +84,7 @@ A few things this gets you without asking for them by name:
   properties (app path/license) are off-limits and left to SwitchScripter's GUI instead.
 
 Re-run `init` after upgrading this package so the copied docs and generated config files catch up —
-see [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context/CHANGELOG.md) for what changed.
+see [CHANGELOG.md](CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -132,7 +132,7 @@ The `switch-docs/` folder contains:
 
 - `switch-scripting.md` — master index with execution environment rules and "load when" routing table
 - `switch-api/api-entry-points.md` — all entry point signatures and when each is called
-- `switch-api/api-job.md` — `Job` class: routing, file access, child jobs, private data, datasets
+- `switch-api/api-job.md` — `Job` class signatures: routing, file access, child jobs, private data, datasets
 - `switch-api/api-flow-element.md` — `FlowElement`: properties, connections, job creation, logging
 - `switch-api/api-switch.md` — `Switch` global: global data, webhooks, abort, server utilities
 - `switch-api/api-connection.md` — `Connection`: type, properties, file count
@@ -140,13 +140,13 @@ The `switch-docs/` folder contains:
 - `switch-api/api-enums.md` — all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
 - `switch-api/api-document-classes.md` — `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
 - `switch-api/api-script-declaration.md` — XML declaration reference
-- `switch-api/api-script-structure.md` — script folder/package structure and manifest format
+- `switch-api/api-script-structure.md` — script folder contents, manifest format, Node.js version per Switch release, Script vs App
 - `switch-api/api-tooling.md` — SwitchScriptTool commands, script folder vs package, build and deployment
 - `switch-api/api-debugging.md` — enabling debug mode, debuggable entry points, VS Code attach
 - `switch-api/api-logging.md` — log levels, when/what to log, `console.log` limitation, common gotchas
 - `switch-api/api-logs-and-dataroot.md` — locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
 - `switch-api/api-vscode.md` — type declarations, tsconfig for TypeScript 6, ESLint rules
 - `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
+- `switch-api/api-job-patterns.md` — `Job` rules and gotchas: file access semantics, temp cleanup, routing rules, child jobs, executor limits
+- `switch-api/api-execution-environment.md` — execution modes, 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, app-only submission rules

package/dist/init.d.ts

@@ -9,6 +9,21 @@ export interface ToolDefinition {
     altIds?: string[];
     files: ToolFile[];
 }
+export interface ApiDoc {
+    /** Filename within docs/switch-api/, e.g. "api-job.md". */
+    file: string;
+    /** The routing table's "Load when" text, verbatim. */
+    loadWhen: string;
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+export declare function parseRoutingTable(root?: string): ApiDoc[];
+/** Filenames only, in routing-table order. */
+export declare function apiFiles(root?: string): string[];
 export declare function generateAgentsMd(docsDir: string): string;
 export declare function generateGeminiMd(docsDir: string): string;
 export declare function generateWindsurfRules(docsDir: string): string;

package/dist/init.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutingTable = parseRoutingTable;
+exports.apiFiles = apiFiles;
 exports.generateAgentsMd = generateAgentsMd;
 exports.generateGeminiMd = generateGeminiMd;
 exports.generateWindsurfRules = generateWindsurfRules;
@@ -47,6 +49,46 @@ const readline = __importStar(require("readline"));
 // ─── Markers ─────────────────────────────────────────────────────────────────
 const MARKER_BEGIN = '<!-- switch-scripting-context begin -->';
 const MARKER_END = '<!-- switch-scripting-context end -->';
+// ─── Shared content (single source of truth for all generated tool files) ────
+/** Package root, whether running from src/ (ts-node) or dist/. */
+function packageRoot() {
+    return path.resolve(__dirname, '..');
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+function parseRoutingTable(root = packageRoot()) {
+    const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
+    const docs = [];
+    for (const line of hub.split('\n')) {
+        // | `switch-api/<file>.md` | <contents> | <load when> |
+        const m = /^\|\s*`switch-api\/(api-[a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
+        if (m)
+            docs.push({ file: m[1], loadWhen: m[3].trim() });
+    }
+    if (docs.length === 0) {
+        throw new Error('No API docs found in docs/switch-scripting.md — the routing table format changed. ' +
+            'Generated tool config would be empty; fix parseRoutingTable() before publishing.');
+    }
+    return docs;
+}
+/** Filenames only, in routing-table order. */
+function apiFiles(root) {
+    return parseRoutingTable(root).map(d => d.file);
+}
+const INLINE_CORE_RULES = `## Core rules
+
+- Entry point functions are top-level async functions — do NOT use \`export\`, arrow functions, or class methods; declare them with the literal \`function\` keyword.
+- Switch finds entry points with a regex, not a parser. Never write a string literal whose content ends with a backslash, a regex literal, or division outside the plain \`word / word\` shape — each silently deletes a span of real code and the entry points inside it, with no error. Read \`api-entry-points.md\` § Entry-point scanner constraints before editing \`main.ts\`/\`main.js\`.
+- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
+- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
+- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
+- The XML declaration (\`<ScriptID>.xml\`) can be edited directly — read \`api-script-declaration.md\` first and follow its rules exactly (nothing validates this format, so mistakes fail silently). Never change an existing script's \`Name\`; bump \`Version\` on every declaration edit. Leave \`manifest.xml\` to the user unless explicitly asked.
+- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
+- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
 // ─── Content generators ──────────────────────────────────────────────────────
 function generateClaudeMd(docsDir) {
     return `${MARKER_BEGIN}
@@ -76,28 +118,6 @@ You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 ${MARKER_END}`;
 }
 function generateCursorMdc(docsDir) {
-    const apiFiles = [
-        'api-entry-points.md',
-        'api-job.md',
-        'api-flow-element.md',
-        'api-connection.md',
-        'api-http.md',
-        'api-enums.md',
-        'api-document-classes.md',
-        'api-script-declaration.md',
-        'api-script-structure.md',
-        'api-tooling.md',
-        'api-debugging.md',
-        'api-vscode.md',
-        'api-property-editors.md',
-        'api-job-patterns.md',
-        'api-switch.md',
-        '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 `---
 description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
 globs: ["**/*.ts", "**/*.js"]
@@ -107,56 +127,21 @@ alwaysApply: false
 ${MARKER_BEGIN}
 You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 
-## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.
+${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
-${fileList}
+${inlineApiFileList(docsDir)}
 ${MARKER_END}`;
 }
-// ─── Shared inline content (for tools without @file import support) ──────────
-const INLINE_CORE_RULES = `## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
-const API_FILES = [
-    'api-entry-points.md',
-    'api-job.md',
-    'api-flow-element.md',
-    'api-connection.md',
-    'api-http.md',
-    'api-enums.md',
-    'api-document-classes.md',
-    'api-script-declaration.md',
-    'api-script-structure.md',
-    'api-tooling.md',
-    'api-debugging.md',
-    'api-vscode.md',
-    'api-property-editors.md',
-    'api-job-patterns.md',
-    'api-switch.md',
-    'api-execution-environment.md',
-    'api-logging.md',
-    'api-logs-and-dataroot.md',
-    'api-app-guidelines.md',
-];
+// ─── Inline block (for tools without @file import support) ──────────────────
 function inlineApiFileList(docsDir) {
-    return API_FILES.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
+    return parseRoutingTable()
+        .map(d => `- \`${docsDir}/switch-api/${d.file}\` — ${d.loadWhen}`)
+        .join('\n');
 }
 function generateInlineBlock(docsDir) {
     return `You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
@@ -165,7 +150,8 @@ ${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
 ${inlineApiFileList(docsDir)}`;
 }
@@ -347,13 +333,25 @@ function applyFileAction(action, dryRun) {
     console.log(`  ${rel} → ${label}`);
 }
 // ─── Docs copy ────────────────────────────────────────────────────────────────
+/** Paths under docs/ that are never shipped to a consuming project. */
+const DOCS_EXCLUDE = ['superpowers', 'temp'];
 function copyDocs(packageRoot, destDir, dryRun) {
     const src = path.join(packageRoot, 'docs');
     if (dryRun) {
         console.log(`  [dry-run] Copying docs/ → ${path.relative(process.cwd(), destDir)}/`);
         return;
     }
-    fs.cpSync(src, destDir, { recursive: true });
+    // The published tarball already omits these, but init may run from a git clone.
+    fs.cpSync(src, destDir, {
+        recursive: true,
+        filter: (from) => {
+            const rel = path.relative(src, from);
+            if (!rel)
+                return true;
+            const [top] = rel.split(path.sep);
+            return !DOCS_EXCLUDE.includes(top) && path.basename(from) !== '.DS_Store';
+        },
+    });
     console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
 }
 // ─── .gitignore update ───────────────────────────────────────────────────────

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

@@ -3,7 +3,8 @@
 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.
+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:
 
@@ -108,15 +109,133 @@ detail.
 
 ## 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.
+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
+  [api-execution-environment.md § Execution modes](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 present on every property and every connection**, not just `Tooltip`.
+  Switch Designer generates the app's HTML documentation from these, so an empty `DetailedInfo`
+  produces a blank entry in the shipped docs.
+- [ ] **`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.
+- [ ] **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](api-script-structure.md#script-folder-files) (`<LanguageCode>.ts`) and
+  `SwitchScriptTool --generate-translations` in [api-tooling.md](api-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 [api-switch.md § Translation extraction rules](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 200×200 version is supplied to Enfocus** for the Appstore listing — it is not
+  part of the pack.
+
+### 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
+  [api-job-patterns.md § Temp file cleanup](api-job-patterns.md#temp-file-cleanup).
+- [ ] Find bundled files at runtime with `flowElement.getPluginResourcesPath()` — see
+  [api-flow-element.md](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
+  [api-script-structure.md § Script folder files](api-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-api/api-execution-environment.md

@@ -1,13 +1,29 @@
 # Execution Environment
 
-How the Node.js process a script runs in behaves, beyond the entry point API itself. These are
-consequences of the host process model, not things a script configures — understanding them avoids
-subtle bugs around state persistence and error handling.
+How the Node.js process a script runs in behaves, beyond the entry point API itself. Apart from the
+execution mode below, these are consequences of the host process model rather than things a script
+configures — understanding them avoids subtle bugs around state persistence and error handling.
+
+## Execution modes
+
+Set in the XML declaration via SwitchScripter, or by editing it directly (see
+[api-script-declaration.md](api-script-declaration.md#built-in-elementfields)). Applies to all
+instances of the script.
+
+**Concurrent** — entry points for the same or different instances may run in parallel. Scripts must
+synchronize access to any shared resources. `NumberOfSlots` is only meaningful in this mode.
+
+**Serialized** — entry points within the same **execution group** are never concurrent. Instances
+in different execution groups may still run in parallel.
+
+**Execution group** — only relevant for Serialized mode. Should be a reverse-domain string (e.g.
+`com.mycompany.myScript`) to avoid collisions. Defaults to the Script ID if left empty.
+
+Neither setting maps to a count of Node.js OS processes — see below.
 
 ## Two independent concurrency tiers
 
-`NumberOfSlots`/`ExecutionGroup` (see
-[Execution modes](api-script-structure.md#execution-modes)) and the pool of Node.js processes that
+`NumberOfSlots`/`ExecutionGroup` (above) and the pool of Node.js processes that
 actually run script code are governed completely separately — there is no one-to-one mapping between
 them:
 

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

@@ -132,3 +132,32 @@ The Node.js executor process is recycled when any of the following thresholds is
 On cleanup, any files/folders created in the temp area are removed. Always close file handles and database connections before the entry point returns.
 
 See [api-execution-environment.md](api-execution-environment.md) for how this process model affects state persistence and error handling across job invocations.
+
+## Driving a third-party CLI application
+
+`findApplicationPath` and the `ApplicationPath` property are the legacy-scripting mechanism for
+locating a third-party application; neither is available to Node.js scripts, and `ApplicationPath`
+is a reserved name Switch silently drops from the declaration (see
+[api-script-declaration.md](api-script-declaration.md#built-in-elementfields)). A Node.js script or
+app that shells out to an external binary resolves the path itself, using the following pattern.
+
+1. Declare an ordinary custom property for the path under a name of your own — `cliPath`, not
+   `ApplicationPath`.
+2. Give it the editor chain `automatic;choosefile;sltextwithvar;scriptexp`, with
+   `Default="Automatic"` and `Subtype="automatic"`. The `automatic` literal editor is what lets the
+   user express "find it yourself" without typing a magic string, and `getPropertyStringValue()`
+   returns the literal `"Automatic"` for it — see
+   [api-property-editors.md § Literal editors](api-property-editors.md#literal-editors).
+3. Resolve the path once per flow start, in `flowStartTriggered`: if the property reads
+   `Automatic`, run whatever discovery the application needs; otherwise take
+   `flowElement.getPropertyStringValue('cliPath')`. Verify the resulting path actually exists, then
+   store it in global data at `Scope.FlowElement`. If it doesn't exist, store an empty string
+   rather than leaving the tag unset.
+4. In `jobArrived`/`timerFired`, read the path back from global data. An empty string means
+   discovery failed: call `flowElement.failProcess()` so the element goes into an error state,
+   instead of failing every individual job.
+5. Remove the global data entry in `flowStopTriggered` — global data is never cleaned up
+   automatically (see [api-switch.md § Global data](api-switch.md#global-data)).
+
+Doing discovery once at flow start rather than per job keeps a filesystem search off the job path,
+and gives the operator a single clear element-level error when the application is missing.

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

@@ -72,39 +72,46 @@ 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 |
 
+## Packing an app
+
+An app is produced by SwitchScripter, not by SwitchScriptTool, and the two workflows have to be
+joined up explicitly:
+
+- **A script folder can only be typed `Script`.** To ship one as an app, pack it with
+  `SwitchScriptTool --pack` first, then open the resulting package in SwitchScripter and change the
+  type to `App` before creating the `.enfpack`. If "Create pack" is greyed out, the type is still
+  `Script`.
+- **Extra files can't be managed while SwitchScripter is working with a script folder.** Convert to
+  a script package first. The conversion is reversible, so the `.pdesc` holding the extra-files
+  configuration can be round-tripped back into the script folder and kept in version control.
+- **Creating a pack does not save the script.** Save first, or the pack is built from the last
+  saved state.
+- **The pack ID is derived from the script ID and always starts with `com.enfocus.`**, whatever the
+  company name and domain in SwitchScripter preferences. To keep it stable across an update, open
+  the previous `.enfpack` rather than the `.sscript` — SwitchScripter carries the pack ID over from
+  the pack it opened, even if the script ID or domain has since changed.
+
+### SwitchScripter and Switch version compatibility
+
+An app loads in the Switch version it was built with **or newer**, never older. So the SwitchScripter
+used must be at or below the oldest Switch version you intend to support, and portable
+SwitchScripters exist for older releases specifically to build backwards-compatible apps. There is
+no SwitchScripter for Switch 25.07 or 25.11 — use the Switch 2024 Fall SwitchScripter for those.
+Apps as a concept require Switch 13.1 or later.
+
+An unsigned app loads only in Switch on the machine that created it. That's what allows local
+testing before submission; it loads elsewhere only once Enfocus has signed it.
+
 ## App Store submission guidelines
 
-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).
+App-specific submission rules (localization, universal/signed macOS binaries, immutable extra
+files) live in [api-app-guidelines.md § App-only](api-app-guidelines.md#app-only), alongside the
+rest of the pre-publish checklist.
 
 ## Execution modes
 
-Set in the XML declaration via SwitchScripter. Applies to all instances of the script.
-
-**Concurrent** — entry points for the same or different instances may run in parallel. Scripts must synchronize access to any shared resources.
-
-**Serialized** — entry points within the same **execution group** are never concurrent. Instances in different execution groups may still run in parallel.
-
-**Execution group** — only relevant for Serialized mode. Should be a reverse-domain string (e.g. `com.mycompany.myScript`) to avoid collisions. Defaults to the Script ID if left empty.
-
-See [api-execution-environment.md](api-execution-environment.md#two-independent-concurrency-tiers) — neither `NumberOfSlots` nor execution group maps to a count of Node.js OS processes; they gate job dispatch on the Switch Server, separate from the pooled executor processes that actually run script code.
+`Concurrent`/`Serialized`, `ExecutionGroup` and `NumberOfSlots` are set in the XML declaration (see
+[api-script-declaration.md](api-script-declaration.md#built-in-elementfields) for the attributes)
+and documented in
+[api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes),
+which also explains why none of them maps to a count of Node.js processes.

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

@@ -73,3 +73,52 @@ Returns the Switch server version as `majorVersion + updateNumber/100` (e.g. Swi
 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 [api-logging.md § Placeholders instead of concatenation](api-logging.md#placeholders-instead-of-concatenation)
+for the same rule stated from the logging side.

package/docs/switch-scripting.md

@@ -14,26 +14,32 @@ Detailed API docs are in `docs/switch-api/`:
 | `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 |
+| `switch-api/api-job.md` | `Job` **signatures**: routing, file access, child jobs, private data, datasets | Looking up what a `job.*` method takes, returns, or throws |
 | `switch-api/api-connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
 | `switch-api/api-http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
 | `switch-api/api-enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
 | `switch-api/api-document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
-| `switch-api/api-script-structure.md` | Script folder/package files, manifest format, App vs Script, execution modes | Setting up a new script project or converting to an App |
-| `switch-api/api-tooling.md` | SwitchScriptTool commands, script folder vs package, build and deployment | Creating, building, packaging, or deploying a script |
+| `switch-api/api-script-structure.md` | What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App | Setting up a new script project, or converting a Script to an App |
+| `switch-api/api-tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
 | `switch-api/api-debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
 | `switch-api/api-vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
 | `switch-api/api-script-declaration.md` | XML declaration reference: properties, connections, execution config — agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
 | `switch-api/api-property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
-| `switch-api/api-job-patterns.md` | File access semantics, temp cleanup, routing rules, child jobs, executor limits | Processing jobs, creating child jobs, working with datasets, routing to multiple connections |
-| `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-job-patterns.md` | `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits | Writing or reviewing job-handling code. Pair with `api-job.md` when you also need signatures |
+| `switch-api/api-execution-environment.md` | Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Choosing or changing an execution mode, 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 |
+| `switch-api/api-app-guidelines.md` | 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) | 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.
-- Do not `export` entry point functions.
+- Do not `export` entry point functions. Declare them with the literal `function` keyword at top
+  level — arrow functions, `exports.name = ...`, and class methods are invisible to Switch.
+- Switch discovers entry points with a regex, not a parser. Never write a string literal whose
+  content ends with a backslash, a regex literal, or division outside the plain `word / word`
+  shape — each silently deletes a span of real code, and every entry point inside that span
+  disappears with no error anywhere. Read `switch-api/api-entry-points.md` §
+  Entry-point scanner constraints before editing `main.ts`/`main.js`.
 - Every `jobArrived` invocation must end with exactly one `job.sendTo*()` or `job.fail()` call — either in the same invocation or deferred to `timerFired` via job information stored in global data.
 - Use `AccessLevel.ReadOnly` for `job.get()` unless the file content will be modified.
 - Use VS Code snippets (`.vscode/switch.code-snippets`, prefix `switch…`) to scaffold entry points.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.0-beta.12",
+  "version": "25.11.0-beta.13",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",