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

package/CHANGELOG.md

@@ -5,6 +5,87 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.0-beta.14] - 2026-09-09
+
+### Added
+- `switch-scripting.md` now tells agents to grep `docs/switch-api/` for `known issue`, `gotcha`,
+  `quirk`, `caveat` to find documented pitfalls before writing code in an area.
+- `api-entry-points.md` documents that a flow restart replays every queued job through `jobArrived`
+  again, even one whose processing was deferred to `timerFired`. A script relying on that pattern
+  must recognize an already-registered job and return quickly, or a large backlog is slow to clear.
+- `api-project-planning.md`, a pre-scaffolding checklist for new scripts and apps: Script vs App,
+  job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm
+  dependency feasibility, and Appstore competition risk. Loaded before any files are scaffolded.
+
+### Changed
+- `README.md` no longer uses dashes as punctuation. Wording is unchanged otherwise.
+- The published README now links to the changelog on jsdelivr, pinned to the version being
+  installed. Relative links were rewritten by npm to the private repo, so they were dead for
+  consumers. `prepack` swaps them in and `postpack` swaps them back.
+
+## [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](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.14/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -34,13 +34,13 @@ The package version tracks the Switch release its docs describe:
   └────── Switch version (25.11)
 ```
 
-- `25.11.x` — every release of this package documenting **Switch 25.11**. Patch increments are doc updates, fixes, and new features of the CLI itself.
+- `25.11.x`: every release of this package documenting **Switch 25.11**. Patch increments are doc updates, fixes, and new features of the CLI itself.
 - The next Switch release moves the first two numbers (e.g. Switch 27.07 → `27.7.0`). Note that semver forbids leading zeros, so `27.07` is published as `27.7`.
 - **Pin with `~`, not `^`.** `~25.11.0` stays on Switch 25.11; `^25.11.0` would happily install `25.12.0`, which targets a different Switch release.
 
 ### Prereleases
 
-Beta builds append a prerelease suffix — `25.11.0-beta.1`. These sort *below* `25.11.0`,
+Beta builds append a prerelease suffix, for example `25.11.0-beta.1`. These sort *below* `25.11.0`,
 so the beta line precedes GA and leaves `25.11.0` free for the first published release.
 
 ## What it does
@@ -53,9 +53,9 @@ so the beta line precedes GA and leaves `25.11.0` free for the first published r
 
 | Tool | File | How context is loaded |
 |---|---|---|
-| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import — hub file routes to specific API docs on demand |
+| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import; hub file routes to specific API docs on demand |
 | GitHub Copilot | `.github/copilot-instructions.md` | `#file:` reference to hub |
-| GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"` — auto-attaches to every TypeScript file edit |
+| GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"`; auto-attaches to every TypeScript file edit |
 | Cursor | `.cursor/rules/switch-scripting.mdc` | Inline key rules + full API file path list |
 | Codex CLI / OpenCode | `AGENTS.md` | Inline key rules + full API file path list |
 | Gemini CLI | `GEMINI.md` | `@switch-docs/switch-scripting.md` import |
@@ -63,28 +63,28 @@ so the beta line precedes GA and leaves `25.11.0` free for the first published r
 | Zed | `.rules` | Inline key rules + full API file path list |
 | Cline | `.clinerules` | Inline key rules + full API file path list |
 
-All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers. Re-running `init` replaces only the Switch section in existing files — project-specific rules outside the markers are untouched.
+All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers. Re-running `init` replaces only the Switch section in existing files. Project-specific rules outside the markers are untouched.
 
 ## Using this with your coding agent
 
-Once `init` has run, just work normally — describe what you want in plain terms and prompt as you
+Once `init` has run, just work normally. Describe what you want in plain terms and prompt as you
 usually would. Your agent picks up the Switch context automatically (via `@import` for Claude
 Code/Gemini, or the inlined rules + file list for the others) whenever it's working in the project,
 and pulls in the specific API doc it needs for the task at hand on its own. You don't need to know
 the doc file names or tell it which one to read.
 
 A few things this gets you without asking for them by name:
-- Scaffolding a new entry point, handling a webhook, or reading/creating datasets and jobs — the
+- Scaffolding a new entry point, handling a webhook, or reading/creating datasets and jobs. The
   agent consults the matching API reference before writing the code.
-- Diagnosing why a script isn't behaving as expected — the agent knows it can locate and query
+- Diagnosing why a script isn't behaving as expected. The agent knows it can locate and query
   Switch's own log database (`ServerLogs.db3`) rather than only re-reasoning about the code.
-- Creating, packing, or deploying a script — the agent uses `SwitchScriptTool` with the documented
-  flags and behavior, rather than hand-rolling the steps.
-- Editing the script's XML declaration — the agent follows the documented rules and knows which
-  properties (app path/license) are off-limits and left to SwitchScripter's GUI instead.
+- Creating, packing, or deploying a script. The agent uses `SwitchScriptTool` with the documented
+  flags and behaviour, rather than hand-rolling the steps.
+- Editing the script's XML declaration. The agent follows the documented rules and knows which
+  properties (app path/licence) 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.
+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@25.11.0-beta.14/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -130,23 +130,24 @@ npm install --save-dev "https://github.com/enfocus-switch/types-switch-scripting
 
 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-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
-- `switch-api/api-http.md` — `HttpRequest` / `HttpResponse` and webhook pattern
-- `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-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-scripting.md`: master index with execution environment rules and "load when" routing table
+- `switch-api/api-project-planning.md`: pre-scaffolding checklist covering Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `switch-api/api-entry-points.md`: all entry point signatures and when each is called
+- `switch-api/api-job.md`: `Job` class signatures for 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
+- `switch-api/api-http.md`: `HttpRequest` / `HttpResponse` and webhook pattern
+- `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 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`: `Job` rules and gotchas covering 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 covering 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-entry-points.md

@@ -86,6 +86,16 @@ Called when a job arrives. Must eventually call a `job.sendTo*()` or `job.fail()
 [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.
 
+**Gotcha: a flow restart replays every queued job through `jobArrived` again.** This includes a job
+whose real processing was deferred elsewhere, such as a job registered in global data and actually
+handled later in `timerFired`. `jobArrived` does not skip a job just because it was already
+registered on a previous run; if the element still has a large backlog queued when the flow
+restarts, every one of those jobs fires `jobArrived` again, and working through a long backlog this
+way can take a long time even when each invocation only needs to recognize the job as already
+registered and return. A script that defers processing this way must check global data at the top
+of `jobArrived` and return immediately for a job already registered there, rather than assuming
+`jobArrived` fires exactly once per job.
+
 ```ts
 async function abort(s: Switch, flowElement: FlowElement, job: Job, abortData: any): Promise<void>
 ```

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-project-planning.md

@@ -0,0 +1,100 @@
+# Project Planning
+
+A pre-scaffolding checklist for a new script or app. Work through this with the user before
+creating any files. The goal is to make a few decisions deliberately up front, because retrofitting
+them after code exists is expensive: password protection and localization for an app, path handling
+for a second target OS, synchronizing shared-resource access for concurrency, or restructuring entry
+points around a job-processing approach chosen too casually.
+
+Two items below are direct questions for the user. The rest are not questions to ask upfront; they
+are checks the agent runs against what's actually being built, raised only when they become
+relevant.
+
+## Ask the user directly
+
+### 1. Script or App?
+
+Ask whether this is for private or internal use (a plain `Script`, distributed freely) or intended
+for the Enfocus Appstore (an `App`). See
+[api-script-structure.md § Script vs App](api-script-structure.md#script-vs-app) for what differs.
+
+This answer gates several items below:
+
+- **App**: localization, password protection, `Name`-never-changes discipline, `Concurrent`-by-default
+  expectation, icon/keywords, and the version-baseline and Appstore-competition checks further down
+  all apply. See [api-app-guidelines.md](api-app-guidelines.md) for the full pre-publish checklist,
+  most of which is worth designing toward from the start rather than retrofitting later.
+- **Script**: none of the app-only items apply. Keep it simple and don't raise app concerns for a
+  plain script.
+
+If App, also ask which languages it must support. English is required; more than one language is
+preferable, see [api-app-guidelines.md § Localization](api-app-guidelines.md#localization).
+
+### 2. What should job processing look like in their flow?
+
+Ask about job handling at a functional level: what should happen when a job arrives, does anything
+need to wait on an external process or resource, could more than one job at a time contend for a
+shared resource. Don't ask the user to pick entry points or connection types directly. Translate the
+answer into a concrete proposal (which entry points, which `sendTo*()` methods, whether `jobArrived`
+alone is enough or work must be deferred to `timerFired`) using
+[api-entry-points.md](api-entry-points.md) and
+[api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs), and be upfront about
+limitations and tradeoffs so the user can make an informed choice, rather than silently picking an
+approach.
+
+If the design defers job processing to `timerFired` via global data, say explicitly that a flow
+restart replays every queued job through `jobArrived` again, and the script must recognize and skip
+an already-registered job quickly, or a large backlog is slow to clear, see
+[api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+
+## Evaluate and flag, don't ask upfront
+
+### Target OS
+
+Switch Server runs on Windows and macOS. Default to writing platform-independent code (the `path`
+module, no hardcoded separators, see
+[api-job-patterns.md § Platform-independent paths](api-job-patterns.md#platform-independent-paths))
+without asking. Only raise target OS as an explicit question once the script needs OS-specific code,
+bundles a native binary, or ships a platform-specific package build, since only then does the answer
+change anything.
+
+### Switch version baseline (apps only)
+
+Once Script vs App is answered as App, ask or infer the oldest Switch version the app must support.
+This sets the Node.js baseline (see
+[api-script-structure.md § Node.js version per Switch version](api-script-structure.md#nodejs-version-per-switch-version))
+and which SwitchScripter build is needed to produce a compatible `.enfpack`. Don't ask this for a
+plain script.
+
+### Concurrency
+
+Default to `Concurrent` execution; it's the preferred choice for apps per
+[api-app-guidelines.md § Top-level declaration properties](api-app-guidelines.md#top-level-declaration-properties).
+Don't ask the user to choose upfront. Only raise `Serialized`, and explain why, when the design has
+an actual reason to need it: a third-party application or shared resource that can't tolerate
+concurrent access, or an API the script drives that isn't safe to call in parallel. See
+[api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes).
+
+### Native or binary npm dependencies
+
+A file-based script or app that ends up on the ESM bundling path cannot use native (binary) Node
+addons at all, see
+[api-execution-environment.md § Native (binary) addons are not supported](api-execution-environment.md#native-binary-addons-are-not-supported).
+If a planned dependency needs one, for example `sharp` or native `sqlite3` bindings, say so before
+the user commits to that library, and suggest a pure JavaScript alternative or a workaround, such as
+shelling out to an external binary, see
+[api-job-patterns.md § Driving a third-party CLI application](api-job-patterns.md#driving-a-third-party-cli-application),
+where one exists.
+
+### Appstore competition risk (apps only)
+
+An app whose core functionality duplicates an existing Switch module without requiring that module
+risks Appstore rejection. For example, an app that performs database CRUD operations without
+requiring the Database Module competes directly with it. If the planned app looks like it falls into
+this category, say so before significant effort is spent, and suggest either gating the app behind
+the relevant module license or contacting Enfocus to check before proceeding.
+
+---
+
+This checklist stops at planning. Once these are answered, move to
+[api-script-structure.md](api-script-structure.md) to scaffold the project.

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

@@ -11,29 +11,40 @@ Detailed API docs are in `docs/switch-api/`:
 
 | File | Contents | Load when |
 |---|---|---|
+| `switch-api/api-project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
 | `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
+- Before scaffolding a new script or app, work through `switch-api/api-project-planning.md` with the user.
 - Always consult the API reference files above before writing or modifying script code.
-- Do not `export` entry point functions.
+- To find documented behavioural pitfalls before writing code in an area, grep `docs/switch-api/`
+  for `known issue`, `gotcha`, `quirk`, `caveat` (case-insensitive) — every documented pitfall uses
+  one of these four terms.
+- 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.14",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",
@@ -27,14 +27,17 @@
     "docs/",
     "!docs/superpowers",
     "!docs/temp",
+    "!docs/adr",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "build:test": "tsc src/init.test.ts --outDir dist --target ES2020 --module commonjs --lib ES2020 --types node --strict --esModuleInterop --skipLibCheck",
-    "test": "npm run build && npm run build:test && node dist/init.test.js",
-    "prepack": "npm run build",
-    "postpack": "node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\""
+    "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js",
+    "prepack": "npm run build && node scripts/readme-links.js --publish",
+    "postpack": "node scripts/readme-links.js --restore && node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\"",
+    "lint:prose": "node scripts/check-prose.js",
+    "lint:gotchas": "node scripts/check-gotcha-tags.js"
   },
   "author": "Sam Wallace",
   "license": "ISC",