@enfocussw/switch-scripting-context 25.11.1-beta.5 → 25.11.1-beta.6

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.1-beta.6] - 2026-10-07
+
+### Added
+
+- The Node.js version table now lists Switch 26.11, which runs scripts on Node.js 24.
+- Every doc over 100 lines now opens with a Contents list of its section headings. An agent that
+  reads only the first part of a file can still see which sections exist further down.
+- `--tools pi` configures the Pi coding agent. It is an alias for `codex`, because Pi reads the
+  same instructions file as Codex.
+- `--tools continue` writes a Continue rule that is always in context, with the same rules and doc
+  list the other tools get.
+- `--tools aider` adds the docs index to the read-only files Aider loads at startup. If your Aider
+  config already lists read-only files, `init` leaves it alone and prints the line to add.
+
+### Changed
+
+- The docs now list only publicly released Switch versions. Version tables drop unreleased builds,
+  and examples that named one now use Switch 25.11 or 26.11.
+- The Node.js version table and the rules for `SwitchVersion` moved out of the script project
+  structure doc into their own doc, with its own row in the routing table. Agents
+  asking which Node.js version a script runs on now read only that section.
+
+### Fixed
+
+- The example of packing changing the Node.js version said a `SwitchVersion` of 21.0 runs on
+  Node.js 16. It runs on Node.js 14, as the version table already said.
+- Agents often answered a short Switch question from the index page alone, without opening the doc
+  that holds the answer, and got it wrong. The generated instructions now tell agents to read the
+  matching doc before answering any Switch question, not only before writing code.
+- The `Job` private data docs did not point to the string values of `EnfocusSwitchPrivateDataTag`,
+  so agents reported bare names such as `userEmail`. They now link to the enum reference.
+- The property editor docs told readers to verify the `getLibraryForMultipleProperty` entry point
+  name "against source", which a consuming project does not have. The note now says the name is
+  unconfirmed.
+- Re-running `init` stacked a second copy of the YAML frontmatter in the Cursor and Copilot
+  scoped-instructions files, one copy per run, which left the frontmatter invalid for both tools.
+  `init` now replaces its own frontmatter instead of prepending a new one, and leaves frontmatter
+  you have edited alone.
+- An agent working in an already-scaffolded script folder skipped the Script vs App question. The
+  planning docs now say to ask it anyway, because a scaffolded manifest is always typed `Script`.
+- The execution environment docs said top-level script variables survive between jobs and
+  suggested using them as a cache. The executor re-evaluates the script on every call, so they do
+  not. The docs now list what can leak (globals, `require()` caches, open handles) and say not to
+  rely on any of it.
+
 ## [25.11.1-beta.5] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -2,9 +2,9 @@
 
 AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/switch) scripting projects (Node.js/TypeScript).
 
-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.
+Installs curated API reference docs and generates config files for 10 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode/Pi, Gemini CLI, Windsurf, Zed, Cline, Continue, and Aider) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.5/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.1-beta.6/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -62,13 +62,20 @@ stay on the old name.
 | 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 |
 | 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 |
+| Codex CLI / OpenCode / Pi | `AGENTS.md` | Inline key rules + full API file path list |
 | Gemini CLI | `GEMINI.md` | `@docs-for-agents/switch-scripting.md` import |
 | Windsurf | `.windsurfrules` | Inline key rules + full API file path list |
 | Zed | `.rules` | Inline key rules + full API file path list |
 | Cline | `.clinerules` | Inline key rules + full API file path list |
+| Continue | `.continue/rules/switch-scripting.md` | `alwaysApply: true`; inline key rules + full API file path list |
+| Aider | `.aider.conf.yml` | `read:` entry that loads the hub file read-only at startup |
 
-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, or `# switch-scripting-context begin` / `# switch-scripting-context end` in `.aider.conf.yml`. Re-running `init` replaces only the Switch section in existing files. Project-specific rules outside the markers are untouched.
+
+Two limits apply to Aider:
+
+- Start Aider from the project root. Aider resolves the `read:` path against the folder it starts in, so from a subfolder it skips the file and prints an error.
+- If your `.aider.conf.yml` already has a `read:` key, `init` leaves the file alone and prints the path to add to your list. A second `read:` key would replace your list, not extend it.
 
 ## Using this with your coding agent
 
@@ -89,7 +96,7 @@ A few things this gets you without asking for them by name:
   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@25.11.1-beta.5/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.6/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -97,8 +104,9 @@ See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-cont
 npx switch-scripting-context init [options]
 
   --tools <list>    Tools to configure. Default: all
-                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline
-                    Aliases: opencode (→ codex), clawcode (→ claude)
+                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline,
+                         continue, aider
+                    Aliases: opencode, pi (→ codex), clawcode (→ claude)
   --docs-dir <dir>  Destination folder for docs. Default: docs-for-agents
   --force           Overwrite existing AI config files instead of merging
   --dry-run         Print what would happen without writing any files
@@ -152,7 +160,7 @@ The `docs-for-agents/` folder contains:
 
 - `switch-scripting.md`: master index with execution environment rules and "load when" routing table
 <!-- docs-index:readme begin -->
-- `switch-project/project-planning.md`: Pre-scaffolding checklist: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `switch-project/project-planning.md`: Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
 - `switch-api/entry-points.md`: All entry point signatures, constraints, and when each is called
 - `switch-api/switch.md`: `Switch` (`s`): global data, webhooks, abort, server utilities
 - `switch-api/flow-element.md`: `FlowElement`: properties, connections, job creation, logging
@@ -161,7 +169,7 @@ The `docs-for-agents/` folder contains:
 - `switch-api/http.md`: `HttpRequest` / `HttpResponse` + webhook pattern
 - `switch-api/enums.md`: All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)
 - `switch-api/document-classes.md`: `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection
-- `switch-project/script-structure.md`: What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App
+- `switch-project/script-structure.md`: What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter
 - `switch-project/tooling.md`: SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment
 - `switch-project/debugging.md`: Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach
 - `switch-project/vscode.md`: Type declarations, tsconfig for TypeScript 6, ESLint rules
@@ -177,4 +185,5 @@ The `docs-for-agents/` folder contains:
 - `switch-appstore/app-manual.md`: Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template)
 - `switch-appstore/app-store-submission.md`: Writing guidance for the Create Appstore App / Create Appstore App Version web forms: Short Description, What's new, Eula, icon specs, and which fields reuse content already written elsewhere
 - `switch-api/api-versions.md`: Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml`
+- `switch-project/node-versions.md`: How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion`
 <!-- docs-index:readme end -->

package/dist/init.d.ts

@@ -1,6 +1,17 @@
+export interface Markers {
+    begin: string;
+    end: string;
+}
 export interface ToolFile {
     targetPath: (root: string, docsDir: string) => string;
     generate: (docsDir: string) => string;
+    /** Comment syntax around the generated section. Default: HTML comments, for Markdown files. */
+    markers?: Markers;
+    /**
+     * Checks an existing file that has no Switch section yet. Returns why appending one would break
+     * the file, or null when appending is safe. init then skips the file and prints the reason.
+     */
+    appendConflict?: (existing: string, docsDir: string) => string | null;
 }
 export interface ToolDefinition {
     id: string;
@@ -29,8 +40,15 @@ export declare function generateGeminiMd(docsDir: string): string;
 export declare function generateWindsurfRules(docsDir: string): string;
 export declare function generateZedRules(docsDir: string): string;
 export declare function generateClineRules(docsDir: string): string;
+export declare function generateContinueRule(docsDir: string): string;
+export declare function generateAiderConf(docsDir: string): string;
+/**
+ * A second top-level read key would not merge with the user's own: Aider keeps only the last
+ * one, so appending ours would silently drop every file the user already loads.
+ */
+export declare function aiderReadConflict(existing: string, docsDir: string): string | null;
 export declare function buildIdMap(registry: ToolDefinition[]): Map<string, string>;
-export declare function findMarkerRange(content: string): [number, number] | null;
+export declare function findMarkerRange(content: string, markers?: Markers): [number, number] | null;
 /** The running package's own version, so a git-clone install stamps what actually ran. */
 export declare function packageVersion(root?: string): string;
 /** The comment init writes as the first line of the copied hub file. */

package/dist/init.js

@@ -40,6 +40,9 @@ exports.generateGeminiMd = generateGeminiMd;
 exports.generateWindsurfRules = generateWindsurfRules;
 exports.generateZedRules = generateZedRules;
 exports.generateClineRules = generateClineRules;
+exports.generateContinueRule = generateContinueRule;
+exports.generateAiderConf = generateAiderConf;
+exports.aiderReadConflict = aiderReadConflict;
 exports.buildIdMap = buildIdMap;
 exports.findMarkerRange = findMarkerRange;
 exports.packageVersion = packageVersion;
@@ -52,6 +55,12 @@ const readline = __importStar(require("readline"));
 // ─── Markers ─────────────────────────────────────────────────────────────────
 const MARKER_BEGIN = '<!-- switch-scripting-context begin -->';
 const MARKER_END = '<!-- switch-scripting-context end -->';
+const HTML_MARKERS = { begin: MARKER_BEGIN, end: MARKER_END };
+// YAML has no HTML comments, so a YAML config file marks its section with # comments instead.
+const YAML_MARKERS = {
+    begin: '# switch-scripting-context begin',
+    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() {
@@ -84,6 +93,7 @@ function apiFiles(root) {
 }
 const INLINE_CORE_RULES = `## Core rules
 
+- Read the matching file from the API reference list below before answering any question about Switch scripting, not only before writing code, including short and yes/no questions. These rules only summarise; Switch often differs from what general Node.js knowledge suggests.
 - 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 \`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()\`.
@@ -95,11 +105,12 @@ const INLINE_CORE_RULES = `## Core rules
 // ─── Content generators ──────────────────────────────────────────────────────
 // Claude Code and Gemini CLI resolve @file imports themselves, so their generated
 // block is just a pointer to switch-scripting.md; the routing table and key rules
-// living there are the actual instructions. Codex, Windsurf, Zed, and Cline don't
-// reliably follow that import syntax, so their generators (generateInlineBlock)
+// living there are the actual instructions. Codex, Windsurf, Zed, Cline, and Continue
+// don't reliably follow that import syntax, so their generators (generateInlineBlock)
 // paste INLINE_CORE_RULES and the routing table directly into the generated file
-// instead. Don't collapse these into one shared generator; the split is deliberate,
-// not duplication.
+// instead. Aider has no instructions file at all; its config loads the hub as a
+// read-only file. Don't collapse these into one shared generator; the split is
+// deliberate, not duplication.
 function generateClaudeMd(docsDir) {
     return `${MARKER_BEGIN}
 ## Switch Scripting (Enfocus Switch)
@@ -112,7 +123,7 @@ function generateCopilotInstructions(docsDir) {
 ## Switch Scripting (Enfocus Switch)
 
 This project uses Enfocus Switch scripting (Node.js/TypeScript).
-Consult the Switch scripting reference before writing or modifying code.
+Consult the Switch scripting reference before answering questions about Switch scripting or writing or modifying code.
 
 #file:../${docsDir}/switch-scripting.md
 ${MARKER_END}`;
@@ -200,6 +211,38 @@ function generateClineRules(docsDir) {
 ${generateInlineBlock(docsDir)}
 ${MARKER_END}`;
 }
+// Continue reads every Markdown file in .continue/rules/. alwaysApply keeps the rules in context
+// for questions too, not only when a matching file is open.
+function generateContinueRule(docsDir) {
+    return `---
+name: Switch scripting
+description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
+alwaysApply: true
+---
+
+${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+// Aider resolves a relative read path against the folder it was started from, not the git root,
+// so this entry only works when Aider starts at the project root.
+function generateAiderConf(docsDir) {
+    return `${YAML_MARKERS.begin}
+read:
+  - ${docsDir}/switch-scripting.md
+${YAML_MARKERS.end}`;
+}
+/**
+ * A second top-level read key would not merge with the user's own: Aider keeps only the last
+ * one, so appending ours would silently drop every file the user already loads.
+ */
+function aiderReadConflict(existing, docsDir) {
+    if (!/^read\s*:/m.test(existing))
+        return null;
+    return `it already has a read: key. Add ${docsDir}/switch-scripting.md to that list yourself.`;
+}
 // ─── Tool registry ───────────────────────────────────────────────────────────
 const TOOL_REGISTRY = [
     {
@@ -240,8 +283,8 @@ const TOOL_REGISTRY = [
     },
     {
         id: 'codex',
-        label: 'Codex CLI / OpenCode',
-        altIds: ['opencode'],
+        label: 'Codex CLI / OpenCode / Pi',
+        altIds: ['opencode', 'pi'],
         files: [
             {
                 targetPath: (root) => path.join(root, 'AGENTS.md'),
@@ -289,6 +332,28 @@ const TOOL_REGISTRY = [
             },
         ],
     },
+    {
+        id: 'continue',
+        label: 'Continue',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.continue', 'rules', 'switch-scripting.md'),
+                generate: generateContinueRule,
+            },
+        ],
+    },
+    {
+        id: 'aider',
+        label: 'Aider',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.aider.conf.yml'),
+                generate: generateAiderConf,
+                markers: YAML_MARKERS,
+                appendConflict: aiderReadConflict,
+            },
+        ],
+    },
 ];
 // ─── ID map ──────────────────────────────────────────────────────────────────
 function buildIdMap(registry) {
@@ -301,16 +366,18 @@ function buildIdMap(registry) {
     return map;
 }
 // ─── Merge logic ─────────────────────────────────────────────────────────────
-function findMarkerRange(content) {
-    const begin = content.indexOf(MARKER_BEGIN);
-    const end = content.indexOf(MARKER_END);
+function findMarkerRange(content, markers = HTML_MARKERS) {
+    const begin = content.indexOf(markers.begin);
+    const end = content.indexOf(markers.end);
     if (begin === -1 || end === -1)
         return null;
     if (begin >= end)
         return null;
-    return [begin, end + MARKER_END.length];
+    return [begin, end + markers.end.length];
 }
-function resolveFileAction(targetPath, block, force) {
+function resolveFileAction(targetPath, file, docsDir, force) {
+    const block = file.generate(docsDir);
+    const markers = file.markers ?? HTML_MARKERS;
     if (!fs.existsSync(targetPath)) {
         return { path: targetPath, action: 'create', content: block };
     }
@@ -318,16 +385,40 @@ function resolveFileAction(targetPath, block, force) {
         return { path: targetPath, action: 'overwrite', content: block };
     }
     const existing = fs.readFileSync(targetPath, 'utf8');
-    const range = findMarkerRange(existing);
+    const range = findMarkerRange(existing, markers);
     if (range) {
-        const updated = existing.slice(0, range[0]) + block + existing.slice(range[1]);
+        // The Cursor .mdc and Copilot scoped-instructions blocks carry frontmatter above the marker,
+        // and only the marker range is replaced. Writing the block whole would stack a second copy of
+        // that frontmatter on every re-run, so drop one of the two copies.
+        const frontmatter = block.slice(0, block.indexOf(markers.begin)).trim();
+        let before = existing.slice(0, range[0]);
+        let incoming = block;
+        if (frontmatter) {
+            if (before.replace(/\r\n/g, '\n').trim() === frontmatter) {
+                before = ''; // our own frontmatter from an earlier run; the block's copy replaces it
+            }
+            else {
+                // User-written or user-edited frontmatter, or init appended below the user's own content.
+                // Leave what is there and write only the marker section.
+                incoming = block.slice(block.indexOf(markers.begin));
+            }
+        }
+        const updated = before + incoming + existing.slice(range[1]);
         return { path: targetPath, action: 'merge-replace', content: updated };
     }
+    const reason = file.appendConflict?.(existing, docsDir);
+    if (reason) {
+        return { path: targetPath, action: 'skip', content: existing, reason };
+    }
     const separator = existing.endsWith('\n') ? '\n' : '\n\n';
     return { path: targetPath, action: 'merge-append', content: existing + separator + block + '\n' };
 }
 function applyFileAction(action, dryRun) {
     const rel = path.relative(process.cwd(), action.path);
+    if (action.action === 'skip') {
+        console.log(`  ${rel} → skipped: ${action.reason}`);
+        return;
+    }
     const label = action.action === 'create' ? 'created'
         : action.action === 'overwrite' ? 'overwritten'
             : action.action === 'merge-replace' ? 'updated (replaced Switch section)'
@@ -458,7 +549,7 @@ function aiConfigFiles(targetRoot, docsDir, tools) {
 /** The frontmatter a generator writes above the marker, trimmed; empty if it writes none. */
 function generatedFrontmatter(file, docsDir) {
     const generated = file.generate(docsDir);
-    return generated.slice(0, generated.indexOf(MARKER_BEGIN)).trim();
+    return generated.slice(0, generated.indexOf((file.markers ?? HTML_MARKERS).begin)).trim();
 }
 /** Deletes now-empty folders from dir upwards, stopping at targetRoot. */
 function removeEmptyDirs(dir, targetRoot) {
@@ -473,13 +564,13 @@ function removeAiConfig(filePath, file, docsDir, targetRoot, dryRun) {
     const raw = fs.readFileSync(filePath, 'utf8');
     const eol = raw.includes('\r\n') ? '\r\n' : '\n';
     const content = raw.replace(/\r\n/g, '\n');
-    const range = findMarkerRange(content);
+    const range = findMarkerRange(content, file.markers);
     if (!range)
         return; // nothing from us in this file
     const rel = path.relative(process.cwd(), filePath);
     let before = content.slice(0, range[0]).trim();
     const after = content.slice(range[1]).trim();
-    // Copilot scoped instructions and Cursor .mdc put frontmatter above the marker. Only an exact
+    // Copilot scoped instructions, Cursor .mdc, and Continue rules put frontmatter above the marker. Only an exact
     // copy of what the generator writes counts as ours; edited or user-written frontmatter stays.
     const ours = generatedFrontmatter(file, docsDir);
     if (ours && before === ours) {
@@ -598,16 +689,13 @@ function init(options) {
         if (!options.tools.includes(toolDef.id))
             continue;
         for (const f of toolDef.files) {
-            toolActions.push({
-                targetPath: f.targetPath(targetRoot, options.docsDir),
-                block: f.generate(options.docsDir),
-            });
+            toolActions.push({ targetPath: f.targetPath(targetRoot, options.docsDir), file: f });
         }
     }
     if (toolActions.length > 0) {
         console.log('\nGenerating AI config files...');
-        for (const { targetPath, block } of toolActions) {
-            const action = resolveFileAction(targetPath, block, options.force);
+        for (const { targetPath, file } of toolActions) {
+            const action = resolveFileAction(targetPath, file, options.docsDir, options.force);
             applyFileAction(action, options.dryRun);
         }
     }
@@ -705,8 +793,9 @@ Commands:
 
 Options (init):
   --tools <list>    Comma-separated tools to configure
-                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline
-                    Aliases: opencode (→ codex), clawcode (→ claude)
+                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline,
+                         continue, aider
+                    Aliases: opencode, pi (→ codex), clawcode (→ claude)
                     Default: all tools
   --docs-dir <dir>  Destination folder for docs in target project (default: docs-for-agents)
   --force           Overwrite existing AI config files rather than merging

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

@@ -9,18 +9,30 @@ triggers:
 
 # API availability by Switch version
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- The running Switch decides which methods exist
+  - Checking at runtime
+- Release names
+- Source and limits of this list
+- Baseline (every Switch version with Node.js scripting)
+- Added per release
+- Declaration changes to existing methods
+<!-- docs-index:contents end -->
+
 ## The running Switch decides which methods exist
 
 Each Switch installation ships one copy of the scripting module, and every bundled Node.js version
 uses that same copy. So which API methods a script can call depends on the Switch Server the script
 runs on, not on anything in the script package. A script whose `manifest.xml` says `20.1` runs on
-Node.js 12 in Switch 26.07, and it still gets the full 26.07 API.
+Node.js 12 in Switch 26.11, and it still gets the full 26.11 API.
 
 The two versions are independent:
 
 | Depends on | Decided by |
 |---|---|
-| Node.js version (language features, Node built-ins) | `SwitchVersion` in `manifest.xml`, looked up by the running Switch. See [script-structure.md § Node.js version per Switch version](../switch-project/script-structure.md#nodejs-version-per-switch-version) |
+| Node.js version (language features, Node built-ins) | `SwitchVersion` in `manifest.xml`, looked up by the running Switch. See [node-versions.md](../switch-project/node-versions.md) |
 | Scripting API (classes, methods, enum values below) | The version of the Switch Server the script runs on |
 
 When code must run on an older Switch, check every API call against the tables below for the
@@ -54,10 +66,8 @@ if (typeof job.getVariableAsString === 'function') {
 | `23.1` | Switch 2023 Fall |
 | `24.0` | Switch 2024 Spring |
 | `24.1` | Switch 2024 Fall |
-| `25.07` | Switch 25.07 |
 | `25.11` | Switch 25.11 |
-| `26.03` | Switch 26.03 |
-| `26.07` | Switch 26.07 |
+| `26.11` | Switch 26.11 |
 
 ## Source and limits of this list
 
@@ -72,9 +82,10 @@ nothing.
   that runs Node.js scripts.
 - Tag 1.1.0 (May 2021) is Switch 2021 Spring. The later tags carry the release number (21.1.x,
   22.0.x, 22.1.x, 24.0.x, 24.1.x).
-- The declarations end at v24.1.1-final (Switch 2024 Fall). SwitchScriptTool 26.07 still scaffolds
-  that version. A check of the Switch 26.07 scripting module found no public class, method, or enum
-  value that v24.1.1 lacks. So nothing was added in 23.1, 25.07, 25.11, 26.03, or 26.07.
+- The declarations end at v24.1.1-final (Switch 2024 Fall). SwitchScriptTool 26.11 still scaffolds
+  that version. A check of the scripting module in a pre-release Switch build found no public class,
+  method, or enum value that v24.1.1 lacks, and 26.11 adds no scripting API. So nothing was added in
+  23.1, 25.11, or 26.11.
 - Entry points aren't part of the type declarations, so this list doesn't record when each entry
   point appeared. The webhook entry points (`httpRequestTriggeredSync`/`Async`) need
   `s.httpRequestSubscribe()`, so they can't be used before Switch 21.1 either.
@@ -100,7 +111,7 @@ nothing.
 | 23.1 | Nothing |
 | 24.0 | `flowElement.getScriptDataPath()`, `flowElement.createPathWithName()`; `job.getVariableAsString()`, `job.getxmlData()`, `job.getxmpData()`, `job.getJdfData()`, `job.getJSONData()`; `s.getPreferenceSetting()`, `s.getServerVersion()`; `NoYesListPropertyStringValue` |
 | 24.1 | `connection.getType()`, `connection.getFileCount()`, `flowElement.getFileCount()` |
-| 25.07, 25.11, 26.03, 26.07 | Nothing |
+| 25.11, 26.11 | Nothing |
 
 ## Declaration changes to existing methods
 

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

@@ -13,6 +13,17 @@ Read-only document introspection utilities. All methods may throw — wrap in `t
 
 Each class needs a minimum Switch version: `PdfDocument` and `PdfPage` 21.0+, `ImageDocument` 21.1+, `XmlDocument` 22.0+, `XmpDocument` and `doc.getXMP()` 22.1+.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- PdfDocument
+  - Static page dimension methods
+- PdfPage
+- ImageDocument
+- XmlDocument
+- XmpDocument
+<!-- docs-index:contents end -->
+
 ## PdfDocument
 
 Open a PDF to inspect metadata and page geometry.

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

@@ -11,6 +11,18 @@ triggers:
 
 Entry points are top-level `async` functions with specific names. They are **not exported**. Switch calls them automatically based on flow events.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Entry-point scanner constraints
+- Flow lifecycle
+- Timer
+- Job processing
+- Webhooks
+- Script expression
+- Property UI callbacks
+<!-- docs-index:contents end -->
+
 ## Entry-point scanner constraints
 
 Switch discovers a script's entry points by regex, not by parsing. Before matching

package/docs/switch-api/enums.md

@@ -11,6 +11,23 @@ triggers:
 
 All enums are available globally in `main.ts`. They are also accessible via `EnfocusSwitch.*` when used outside `main.ts` (e.g. in imported modules). Enums and values without a Switch version below exist in every Switch version with Node.js scripting; see [api-versions.md](api-versions.md).
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- LogLevel
+- AccessLevel
+- DatasetModel
+- Scope
+- Priority
+- Connection.Level
+- HttpRequest.Method
+- PropertyType
+- NoYesListPropertyStringValue
+- EnfocusSwitchPrivateDataTag
+- ImageDocument.ColorMode
+- ImageDocument.ColorSpace
+<!-- docs-index:contents end -->
+
 ## LogLevel
 
 Used with `job.log()` and `flowElement.log()`.

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

@@ -13,6 +13,18 @@ How the Node.js process a script runs in behaves, beyond the entry point API its
 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.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Execution modes
+- Two independent concurrency tiers
+- Don't rely on in-memory state between entry point calls
+- Unhandled promise rejections end the run, not the process
+- Third-party npm modules: file-based scripts only
+- Native (binary) addons are not supported
+- No explicit CPU or memory cap beyond the documented thresholds
+<!-- docs-index:contents end -->
+
 ## Execution modes
 
 Set in the XML declaration via SwitchScripter, or by editing it directly (see
@@ -50,19 +62,40 @@ them:
   recycled (see
   [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
 
-## Module-level state persists across jobs on the same executor
+## Don't rely on in-memory state between entry point calls
+
+Write every entry point so it neither depends on state from an earlier call nor assumes it starts
+from a clean process.
+
+The executor evaluates the whole script again before every entry point call. Top-level
+`let`/`const`/`var` declarations and functions in the script file are recreated each time, so a
+counter or cache held in one does not carry over to the next job.
+
+Some in-memory state can still outlive a call, because executor processes are long-lived and
+shared:
+
+- Properties set on `global`/`globalThis`. One executor runs code for every script element pooled
+  onto it, so a global can be read or overwritten by a different script.
+- Internal state of CommonJS packages loaded with `require()`. Node caches a required module for
+  the life of the process, so a singleton inside the package (a client, a connection pool, a
+  configured default) can be reused by a later call. ES-module packages that are bundled into the
+  script (see [Native (binary) addons](#native-binary-addons-are-not-supported)) are evaluated
+  again on each call like the script itself.
+- Timers, sockets, and other handles a call leaves open keep running after the entry point returns.
+
+Whether any of this reaches a given job depends on which executor the job lands on and whether that
+executor was recycled in between. A script cannot control or predict either. This is a side effect
+of the process model, not a supported feature, and it can change between Switch versions:
 
-Because executor processes are long-lived and reused, any state held outside an entry point function
-— module-level `let`/`const`/`var`, an in-memory cache, a counter — can survive from one job
-invocation to the next if the same executor happens to service both. It is **not** reset before each
-`jobArrived`/`timerFired`/etc. call, and which executor services a given job is not something a
-script controls or can predict. This is useful for caching (e.g. a parsed config file, a pooled
-connection) but also a common source of bugs: don't assume module-level state starts fresh for every
-job, and don't assume it's shared with an *arbitrary* other job either — reset explicitly at the
-start of an entry point if a fresh value is required per job.
+- Don't use globals or package-level singletons to cache data or pass it between jobs. Store data
+  that must outlive a call with `s.setGlobalData()` (see [switch.md](switch.md)) or on the job
+  itself.
+- Don't set globals. If a package keeps internal state, configure it explicitly at the start of
+  each entry point rather than assuming either a fresh or a previously configured instance.
+- Close connections, clear timers, and release file handles before the entry point returns.
 
-`getInitialize()`/`getFinalize()` (if the script uses them) run once per script per process
-lifetime, not once per job — the same caveat applies to anything they set up.
+The executor also recognises `getInitialize()`/`getFinalize()` functions in a script. They are not
+part of the public scripting API; don't define them.
 
 ## Unhandled promise rejections end the run, not the process
 
@@ -85,7 +118,7 @@ third-party modules from its own `node_modules` folder (see
 
 Scripts with ESM dependencies are bundled before execution, when `SwitchVersion` in `manifest.xml`
 is `24.0` or higher (see
-[script-structure.md § Other effects of `SwitchVersion`](../switch-project/script-structure.md#other-effects-of-switchversion)); this bundling path does not support
+[node-versions.md § Other effects of `SwitchVersion`](../switch-project/node-versions.md#other-effects-of-switchversion)); this bundling path does not support
 native/binary Node addons (`.node` files). Stick to pure-JavaScript/TypeScript dependencies.
 
 ## No explicit CPU or memory cap beyond the documented thresholds

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

@@ -11,6 +11,19 @@ triggers:
 
 The `FlowElement` instance `flowElement` is passed to every entry point that operates on a flow element. It provides access to properties, connections, job creation, and logging.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Properties
+- Connections
+- Timer
+- Logging
+- Job creation (jobArrived / timerFired / httpRequestTriggeredAsync)
+- Channels
+- Utilities
+<!-- docs-index:contents end -->
+
 ## Identity
 
 ```ts

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

@@ -13,6 +13,19 @@ Common behavioral rules for file access, routing, temp file cleanup, and child j
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- File access semantics
+- Temp file cleanup
+- Platform-independent paths
+- Sending jobs
+- Dataset writes must precede child job creation
+- processLater
+- Executor cleanup thresholds
+- Driving a third-party CLI application
+<!-- docs-index:contents end -->
+
 ## File access semantics
 
 `job.get(accessLevel)` and `job.getDataset(name, accessLevel)` behave differently depending on the access level:

package/docs/switch-api/job.md

@@ -11,6 +11,21 @@ triggers:
 
 A `Job` represents a file or folder moving through the flow. It is passed to `jobArrived` and can be created via `flowElement.createJob()` or `job.createChild()`. Every job must be routed with a `sendTo*()` call or `fail()` before the entry point ends (or at a later time via `timerFired`).
 > Jobs obtained via `flowElement.getJobs()` throw on `getPrivateData()`, `listDatasets()`, and `getDataset()` in the same entry point invocation — private data/metadata cannot be *read* back. `setPrivateData()`/`removePrivateData()` are not restricted this way.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Priority
+- File access
+- Routing
+- Failure & logging
+- Child jobs
+- Private data
+- Datasets (metadata)
+- Variables & structured data
+<!-- docs-index:contents end -->
+
 ## Identity
 
 ```ts
@@ -108,7 +123,7 @@ Creates a new job inheriting the processing history, metadata, and private data
 
 ## Private data
 
-Private data is arbitrary key/value storage attached to a job and passed along with it. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
+Private data is arbitrary key/value storage attached to a job and passed along with it. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). For each tag's string value (`"EnfocusSwitch.<name>"`) and the release that added it, see [enums.md § EnfocusSwitchPrivateDataTag](enums.md#enfocusswitchprivatedatatag).
 
 ```ts
 job.getPrivateData(tag: string | EnfocusSwitchPrivateDataTag): Promise<any>

package/docs/switch-api/logging.md

@@ -15,6 +15,21 @@ Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElem
 listed in [enums.md](enums.md). Each log call has a small performance overhead, so where
 and how often to log is a deliberate choice, not a default.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Log levels
+- Don't add a verbosity property
+- Logging in loops
+- `console.log` does not work
+- Don't double-log before a failure
+- Message formatting and the `%` gotcha
+- Signature gotcha: array vs. single value
+- Placeholders instead of concatenation
+- Message quality
+- Log volume
+<!-- docs-index:contents end -->
+
 ## Log levels
 
 | Level | Use for |

package/docs/switch-api/switch.md

@@ -11,6 +11,16 @@ triggers:
 
 The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Global data
+- Webhooks
+- Abort
+- Server utilities
+  - Translation extraction rules
+<!-- docs-index:contents end -->
+
 ## Global data
 
 Global data is key/value storage shared across entry point invocations, scoped by `Scope`.

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

@@ -25,6 +25,25 @@ Items fall into three tiers, marked on each one:
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Properties
+- Entry points
+- Sending jobs
+- Logging
+- Temp files and paths
+- App-only
+  - Identity and versioning
+  - Top-level declaration properties
+  - Password protection
+  - Localization
+  - Icon
+  - Extra files
+  - Source and review hygiene
+  - What review does and doesn't cover
+<!-- docs-index:contents end -->
+
 ## Properties
 
 - [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30

package/docs/switch-project/node-versions.md

@@ -0,0 +1,87 @@
+---
+id: node-versions
+category: switch-project
+order: 26
+summary: "How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion`"
+triggers:
+  - "Working out which Node.js version a script or app will run on, or what `SwitchVersion` in manifest.xml does"
+---
+
+# Node.js version per Switch version
+
+
+The Switch Server running the script picks its Node.js version by looking up `SwitchVersion` from
+`manifest.xml` in a fixed table that ships with each Switch release:
+
+| Switch version | `SwitchVersion` | Node.js used |
+|---|---|---|
+| Switch 2020 Spring | `20.0` | 12 |
+| Switch 2020 Fall | `20.1` | 12 |
+| Switch 2021 Spring | `21.0` | 14 |
+| Switch 2021 Fall | `21.1` | 16 |
+| Switch 2022 Spring | `22.0` | 16 |
+| Switch 2022 Fall | `22.1` | 16 |
+| Switch 2023 Fall | `23.1` | 18 |
+| Switch 2024 Spring | `24.0` | 18 |
+| Switch 2024 Fall | `24.1` | 20 |
+| Switch 25.11 | `25.11` | 20 |
+| Switch 26.11 | `26.11` | 24 |
+
+Switch 26.11 bundles Node.js 12.22.12, 14.21.3, 16.20.2, 18.20.8, 20.20.0, and 24.13.0.
+
+`SwitchVersion` controls the Node.js version only. Which scripting API methods exist depends on the
+Switch version the script runs on, see [api-versions.md](../switch-api/api-versions.md).
+
+## What writes `SwitchVersion`
+
+`SwitchVersion` is the version of whichever tool last wrote the manifest. It is not a setting the
+author picks:
+
+- `SwitchScriptTool --create` writes the tool's own version into the new script folder.
+- `SwitchScriptTool --pack` writes the tool's own version into the packed `.sscript`, whatever the
+  script folder's manifest says. The script folder's manifest itself is left unchanged. With
+  SwitchScriptTool 26.11, a folder whose manifest says `21.0` packs to a `.sscript` whose manifest
+  says `26.11`, which moves the script from Node.js 14 to Node.js 24. This was verified with a
+  pre-release SwitchScriptTool build.
+- SwitchScripter writes its own version on every save. Opening a script with a different
+  `SwitchVersion` shows a warning that saving updates the script to the current Node.js version.
+
+**Gotcha:** a script folder tested directly in Switch and the `.sscript` packed from it can run on
+different Node.js versions. A folder created with an older SwitchScriptTool keeps that tool's
+version, but packing it with a newer SwitchScriptTool stamps the newer one. Test the packed
+`.sscript`, not only the folder, before shipping it.
+
+To target an older Node.js version, pack the script with the SwitchScriptTool of a Switch release
+whose row in the table gives that version. For example, a script packed with SwitchScriptTool 25.11
+gets `SwitchVersion` `25.11` and runs on Node.js 20, in Switch 26.11 too. Apps work the same way
+with SwitchScripter, except that there is no SwitchScripter for Switch 25.11. An app that
+needs Node.js 20 is built with the Switch 2024 Fall SwitchScripter (`SwitchVersion` `24.1`), see
+[script-structure.md § SwitchScripter and Switch version compatibility](script-structure.md#switchscripter-and-switch-version-compatibility).
+Editing `SwitchVersion` by hand doesn't last, because `--pack` and SwitchScripter overwrite it.
+
+## Values missing from the table
+
+Behavior of the Switch 26.11 Server:
+
+- No `SwitchVersion` element: treated as `20.1`, so Node.js 12.
+- Lower than the first entry: Node.js 12.
+- Higher than the last entry, for example a package built by a newer tool than the Switch it runs
+  on: the newest Node.js that Switch bundles. The Server logs a debug message that the script
+  "might not be compatible with the current Switch version" and runs it anyway.
+- **Known issue:** a value that isn't an exact entry but falls numerically between the first and
+  last entries matches no Node.js version, for example `25.1` instead of `25.11`, `24.10` instead of
+  `24.1`, or `23.0`. The Server then fails to build the path to a Node.js binary, so no executor
+  process starts for the script. This was confirmed by running the Switch 26.11 lookup code with
+  these values, not by running such a script in Switch, so the exact symptom in Switch hasn't been
+  checked. A value such as `26.3` works today only because it's higher than the last entry, and it
+  will break once a later release adds an entry above it. Never hand-edit `SwitchVersion`. If you
+  must, copy a value exactly as the table above spells it.
+
+## Other effects of `SwitchVersion`
+
+- npm dependencies that are ES modules are bundled with esbuild before execution only when
+  `SwitchVersion` is `24.0` or higher.
+- A script expression has no manifest. It always runs on the newest Node.js the running Switch
+  bundles.
+
+> **Mac (Apple Silicon):** For scripts whose `SwitchVersion` is `21.1` (Switch 2021 Fall) or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts with an earlier `SwitchVersion` run under Rosetta, because the bundled Node.js 12 and 14 are Intel-only builds. If a script bundles platform-specific binaries, ship both Intel and ARM variants.

package/docs/switch-project/project-planning.md

@@ -2,15 +2,20 @@
 id: project-planning
 category: switch-project
 order: 1
-summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+summary: "Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
 triggers:
-  - "Starting a new script or app, before scaffolding any files"
+  - "Starting a new script or app, before scaffolding any files, or working in a script folder that is already scaffolded where Script vs App has not been settled"
 ---
 
 # 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
+A planning checklist for a new script or app. Work through this with the user before
+creating any files.
+
+A script folder that already exists (scaffolded by the user, SwitchScripter, or `SwitchScriptTool
+--create`) does not skip the checklist. The manifest's `ScriptPackageType` is always `Script` in a
+scaffolded folder, so it does not answer item 1. Ask Script or App anyway, and run the other
+checks against the code that exists. 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.
@@ -19,6 +24,21 @@ Two items below are direct questions for the user. The rest are not questions to
 are checks the agent runs against what's actually being built, raised only when they become
 relevant.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Ask the user directly
+  - 1. Script or App?
+  - 2. What should job processing look like in their flow?
+- Evaluate and flag, don't ask upfront
+  - One script folder or several
+  - Target OS
+  - Switch version baseline (apps only)
+  - Concurrency
+  - Native or binary npm dependencies
+  - Appstore competition risk (apps only)
+<!-- docs-index:contents end -->
+
 ## Ask the user directly
 
 ### 1. Script or App?
@@ -86,7 +106,7 @@ This sets two separate limits:
 
 - Which SwitchScripter build is needed to produce a compatible `.enfpack`, and so which Node.js
   version the app runs on (see
-  [script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)).
+  [node-versions.md](node-versions.md)).
   Write code for that Node.js version.
 - Which scripting API methods the code may call. Methods follow the Switch version the app runs on,
   so check every call against [api-versions.md](../switch-api/api-versions.md) for the oldest

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

@@ -27,6 +27,18 @@ the order they're offered. `Type` follows from which editor(s) are chosen — se
 
 ---
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Inline editors
+- Modal editors
+- Literal editors
+- Extra XML attributes for certain editors
+- Common practices
+  - A property whose shape varies by a type selector
+- Notes
+<!-- docs-index:contents end -->
+
 ## Inline editors
 
 The inline editor slot is always the single token `inline` in `Editor` — what differs is `Type`.
@@ -60,7 +72,7 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `filetype` | Filename pattern(s) for the selected file type |
 | `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
 | `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks) |
-| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
+| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one. Unconfirmed, so treat the name as unverified. |
 | `description` | Multi-line text as a single string (may include newlines) |
 | `scriptexp` | Result of script expression evaluated in job context, as a string |
 | `sltextwithvar` | Single-line text with variables substituted, as a string |

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

@@ -13,6 +13,21 @@ The file `<ScriptID>.xml` defines the script's metadata, custom properties, conn
 and execution configuration. It is normally written by **SwitchScripter**, but the format is fully
 documented below — you can edit it directly.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Agent editing policy
+- XML structure overview
+- Built-in ElementFields
+- Custom property elements (ElementFields)
+- ConnectionFields
+- ExtraProperties
+- Type reference
+- Escaped `ValueDescription` payloads
+- Reserved tag names
+- Annotated example
+<!-- docs-index:contents end -->
+
 ## Agent editing policy
 
 - Editing this file directly is safe as long as you follow the rules on this page exactly — the

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

@@ -2,9 +2,9 @@
 id: script-structure
 category: switch-project
 order: 10
-summary: "What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App"
+summary: "What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter"
 triggers:
-  - "Setting up a new script project, converting a Script to an App, or working out which Node.js version a script or app will run on"
+  - "Setting up a new script project or converting a Script to an App"
 ---
 
 # Script Project Structure
@@ -13,6 +13,20 @@ A Switch script project lives in a **script folder** during development and is d
 
 > **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [script-declaration.md](script-declaration.md) for the declaration's rules, and [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Script folder files
+- Several script folders side by side
+- manifest.xml format
+- Node.js version per Switch version
+- Script vs App
+- Packing an app
+  - SwitchScripter and Switch version compatibility
+- App Store submission guidelines
+- Execution modes
+<!-- docs-index:contents end -->
+
 ## Script folder files
 
 | File | Required | Notes |
@@ -80,78 +94,8 @@ my-collection/        the folder the user works in; AI agent config and docs liv
 
 ## Node.js version per Switch version
 
-The Switch Server running the script picks its Node.js version by looking up `SwitchVersion` from
-`manifest.xml` in a fixed table that ships with each Switch release:
-
-| Switch version | `SwitchVersion` | Node.js used |
-|---|---|---|
-| Switch 2020 Spring | `20.0` | 12 |
-| Switch 2020 Fall | `20.1` | 12 |
-| Switch 2021 Spring | `21.0` | 14 |
-| Switch 2021 Fall | `21.1` | 16 |
-| Switch 2022 Spring | `22.0` | 16 |
-| Switch 2022 Fall | `22.1` | 16 |
-| Switch 2023 Fall | `23.1` | 18 |
-| Switch 2024 Spring | `24.0` | 18 |
-| Switch 2024 Fall | `24.1` | 20 |
-| Switch 25.07 | `25.07` | 20 |
-| Switch 25.11 | `25.11` | 20 |
-| Switch 26.03 | `26.03` | 24 |
-| Switch 26.07 | `26.07` | 24 |
-
-Switch 26.07 bundles Node.js 12.22.12, 14.21.3, 16.20.2, 18.20.8, 20.20.0, and 24.13.0.
-
-`SwitchVersion` controls the Node.js version only. Which scripting API methods exist depends on the
-Switch version the script runs on, see [api-versions.md](../switch-api/api-versions.md).
-
-### What writes `SwitchVersion`
-
-`SwitchVersion` is the version of whichever tool last wrote the manifest. It is not a setting the
-author picks:
-
-- `SwitchScriptTool --create` writes the tool's own version into the new script folder.
-- `SwitchScriptTool --pack` writes the tool's own version into the packed `.sscript`, whatever the
-  script folder's manifest says. The script folder's manifest itself is left unchanged. Verified
-  with SwitchScriptTool 26.07: a folder whose manifest said `21.0` packed to a `.sscript` whose
-  manifest says `26.07`, which moves the script from Node.js 16 to Node.js 24.
-- SwitchScripter writes its own version on every save. Opening a script with a different
-  `SwitchVersion` shows a warning that saving updates the script to the current Node.js version.
-
-**Gotcha:** a script folder tested directly in Switch and the `.sscript` packed from it can run on
-different Node.js versions. A folder created with an older SwitchScriptTool keeps that tool's
-version, but packing it with a newer SwitchScriptTool stamps the newer one. Test the packed
-`.sscript`, not only the folder, before shipping it.
-
-To target an older Node.js version, build the package with the SwitchScriptTool or SwitchScripter
-of that Switch release. Editing `SwitchVersion` by hand doesn't last, because `--pack` and
-SwitchScripter overwrite it.
-
-### Values missing from the table
-
-Behavior of the Switch 26.07 Server:
-
-- No `SwitchVersion` element: treated as `20.1`, so Node.js 12.
-- Lower than the first entry: Node.js 12.
-- Higher than the last entry, for example a package built by a newer tool than the Switch it runs
-  on: the newest Node.js that Switch bundles. The Server logs a debug message that the script
-  "might not be compatible with the current Switch version" and runs it anyway.
-- **Known issue:** a value that isn't an exact entry but falls numerically between the first and
-  last entries matches no Node.js version, for example `25.7` instead of `25.07`, `24.10` instead of
-  `24.1`, or `23.0`. The Server then fails to build the path to a Node.js binary, so no executor
-  process starts for the script. This was confirmed by running the Switch 26.07 lookup code with
-  these values, not by running such a script in Switch, so the exact symptom in Switch hasn't been
-  checked. A value such as `26.3` works today only because it's higher than the last entry, and it
-  will break once a later release adds an entry above it. Never hand-edit `SwitchVersion`. If you
-  must, copy a value exactly as the table above spells it.
-
-### Other effects of `SwitchVersion`
-
-- npm dependencies that are ES modules are bundled with esbuild before execution only when
-  `SwitchVersion` is `24.0` or higher.
-- A script expression has no manifest. It always runs on the newest Node.js the running Switch
-  bundles.
-
-> **Mac (Apple Silicon):** For scripts whose `SwitchVersion` is `21.1` (Switch 2021 Fall) or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts with an earlier `SwitchVersion` run under Rosetta, because the bundled Node.js 12 and 14 are Intel-only builds. If a script bundles platform-specific binaries, ship both Intel and ARM variants.
+`SwitchVersion` in `manifest.xml` selects the Node.js version the script runs on, and SwitchScriptTool
+and SwitchScripter overwrite it. See [node-versions.md](node-versions.md).
 
 ## Script vs App
 
@@ -186,14 +130,14 @@ joined up explicitly:
 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.
+no SwitchScripter for Switch 25.11 — use the Switch 2024 Fall SwitchScripter for it.
 Apps as a concept require Switch 13.1 or later.
 
 The SwitchScripter version also fixes the app's Node.js version, see
-[Node.js version per Switch version](#nodejs-version-per-switch-version). An app built with the
+[node-versions.md](node-versions.md). An app built with the
 Switch 2024 Fall SwitchScripter has `SwitchVersion` `24.1`, so it runs on Node.js 20 in every Switch
-version that loads it, including 26.x. Switch 26.07 ships SwitchScripter 26.07. An app built with
-it runs on Node.js 24, and it loads only in Switch 26.07 or newer.
+version that loads it, including 26.x. Switch 26.11 ships SwitchScripter 26.11. An app built with
+it runs on Node.js 24, and it loads only in Switch 26.11 or newer.
 
 An unsigned app loads only in Switch on the machine that created it. That's what allows local
 testing before submission; it loads elsewhere only once Enfocus has signed it.

package/docs/switch-project/tooling.md

@@ -9,6 +9,16 @@ triggers:
 
 # Script Folders, Packages & SwitchScriptTool
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Script folder vs script package
+- SwitchScriptTool
+- Commands
+- Verify entry points before packing
+- Deployment
+<!-- docs-index:contents end -->
+
 ## Script folder vs script package
 
 | | Script folder | Script package (`.sscript`) |
@@ -49,9 +59,9 @@ location for the current OS if the bare command isn't found.
 
 **Pack** transpiles `main.ts` fresh into the package on every run; it never reads or modifies any `main.js` already sitting in the source folder (a stale hand-edited `main.js` there is ignored and left untouched).
 
-Pack copies an allowlist of files, not the whole folder. Only these end up in the `.sscript`: `manifest.xml`, the declaration file named in `ScriptDeclarationFile`, the program file named in `ScriptProgramFiles` plus the `main.js` and `main.js.map` pack transpiles from it, the icon named in `ScriptIconFile`, `tsconfig.json`, the placeholder `<ScriptID>.sscript`, `Resources/`, and `node_modules/`. Everything else in the folder is left out and printed in an "Info: ... will not be packed" list, even without `--verbose`. That includes `package.json`, `package-lock.json`, `.vscode/`, a README, other `.ts`/`.js` files, subfolders other than `Resources/` and `node_modules/`, and AI agent config and docs folders. `--verbose` additionally prints the full list of what *will* be packed. Translation files were not part of this test. Verified with SwitchScriptTool 26.07.
+Pack copies an allowlist of files, not the whole folder. Only these end up in the `.sscript`: `manifest.xml`, the declaration file named in `ScriptDeclarationFile`, the program file named in `ScriptProgramFiles` plus the `main.js` and `main.js.map` pack transpiles from it, the icon named in `ScriptIconFile`, `tsconfig.json`, the placeholder `<ScriptID>.sscript`, `Resources/`, and `node_modules/`. Everything else in the folder is left out and printed in an "Info: ... will not be packed" list, even without `--verbose`. That includes `package.json`, `package-lock.json`, `.vscode/`, a README, other `.ts`/`.js` files, subfolders other than `Resources/` and `node_modules/`, and AI agent config and docs folders. `--verbose` additionally prints the full list of what *will* be packed. Translation files were not part of this test. Verified with a pre-release SwitchScriptTool build.
 
-`node_modules` is packed as-is, so run `npm prune --production` first (see Deployment) — otherwise `devDependencies` (including `@types/*` packages, which the scaffolded `package.json` puts there) get bundled into the package for no runtime benefit. One harmless quirk: the placeholder `<ScriptID>.sscript` file scaffolded by `--create` is on the allowlist and ends up packed inside the real `.sscript` too. Pack also replaces `SwitchVersion` in the packed `manifest.xml` with SwitchScriptTool's own version (`--create` writes it too), and that value picks the Node.js version the package runs on. See [script-structure.md § What writes `SwitchVersion`](script-structure.md#what-writes-switchversion).
+`node_modules` is packed as-is, so run `npm prune --production` first (see Deployment) — otherwise `devDependencies` (including `@types/*` packages, which the scaffolded `package.json` puts there) get bundled into the package for no runtime benefit. One harmless quirk: the placeholder `<ScriptID>.sscript` file scaffolded by `--create` is on the allowlist and ends up packed inside the real `.sscript` too. Pack also replaces `SwitchVersion` in the packed `manifest.xml` with SwitchScriptTool's own version (`--create` writes it too), and that value picks the Node.js version the package runs on. See [node-versions.md § What writes `SwitchVersion`](node-versions.md#what-writes-switchversion).
 
 **Gotcha: local modules break pack.** A `main.ts` that imports a local module (`import { x } from './helper'` or `'./lib/helper'`) fails to pack with TypeScript error TS2307 (`Cannot find module`), and no `.sscript` is written. Pack's own output shows why: `helper.ts` and `lib/helper.ts` appear in its "will not be packed" list, and the TS2307 error points at pack's temporary copy of the folder, which doesn't contain them. A `main.js` that `require`s a local file was not tested, but that file isn't packed either. The manifest also accepts only one `ScriptProgramFile` (pack errors with `The manifest must contain only one script program file`), so listing the helper there doesn't work. The verified option is to keep script code in the single program file. Shared code in an npm package under `node_modules/` might work, since `node_modules/` is packed, but that was not tested, and neither was a `file:` dependency, which npm installs as a symlink.
 

package/docs/switch-project/vscode.md

@@ -24,13 +24,13 @@ Enables autocomplete and type checking for `Switch`, `Job`, `FlowElement` and al
 > `SwitchScriptTool --create` sets this up automatically for new TypeScript script folders.
 
 v24.1.1-final is the last published version and matches the API of every Switch release from 24.1
-to 26.07. It declares every method without marking which Switch release added it, so the compiler
+to 26.11. It declares every method without marking which Switch release added it, so the compiler
 won't flag a call that an older target Switch lacks. Check those against
 [api-versions.md](../switch-api/api-versions.md).
 
-SwitchScriptTool 26.07 also scaffolds `@types/node` 24.x whatever Node.js version the script will
+SwitchScriptTool 26.11 also scaffolds `@types/node` 24.x whatever Node.js version the script will
 run on. When the package will run on an older Node.js (see
-[script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)),
+[node-versions.md](node-versions.md)),
 pin `@types/node` to that major version so the compiler flags newer Node.js APIs.
 
 ## TypeScript 6 / VS Code 1.114+

package/docs/switch-scripting.md

@@ -1,11 +1,13 @@
 # Switch Scripting (Node.js)
 Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
 
+Read the matching file from the API reference table below before answering any question about Switch scripting, not only before writing code. This applies to short and yes/no questions too. This page only summarises; the answer usually depends on a detail that is only in the linked file, and Switch often differs from what general Node.js or scripting knowledge suggests.
+
 ## Execution environment
 - Entry points are top-level `async` functions with specific names — **not exported** — executed in a `node:vm.Script()` context.
 - ESM is supported: if ES modules are present the script is bundled with ESBuild before running (when `SwitchVersion` in `manifest.xml` is `24.0` or higher).
 - Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely. They list every method up to Switch 24.1 without saying which release added it.
-- The Node.js version comes from `SwitchVersion` in `manifest.xml`; the available API methods come from the Switch version the script runs on. See `switch-project/script-structure.md` and `switch-api/api-versions.md`.
+- The Node.js version comes from `SwitchVersion` in `manifest.xml`; the available API methods come from the Switch version the script runs on. See `switch-project/node-versions.md` and `switch-api/api-versions.md`.
 
 ## API reference
 Detailed docs live in three folders, alongside this file: `switch-api/` (the scripting API itself),
@@ -15,7 +17,7 @@ publishing guidance).
 <!-- docs-index:table begin -->
 | File | Contents | Load when |
 |---|---|---|
-| `switch-project/project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
+| `switch-project/project-planning.md` | Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files, or working in a script folder that is already scaffolded where Script vs App has not been settled |
 | `switch-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/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
 | `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
@@ -24,7 +26,7 @@ publishing guidance).
 | `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
 | `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
 | `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
-| `switch-project/script-structure.md` | What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App | Setting up a new script project, converting a Script to an App, or working out which Node.js version a script or app will run on |
+| `switch-project/script-structure.md` | What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter | Setting up a new script project or converting a Script to an App |
 | `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
 | `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
 | `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
@@ -40,11 +42,12 @@ publishing guidance).
 | `switch-appstore/app-manual.md` | Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template) | Preparing the app manual document for Appstore submission |
 | `switch-appstore/app-store-submission.md` | Writing guidance for the Create Appstore App / Create Appstore App Version web forms: Short Description, What's new, Eula, icon specs, and which fields reuse content already written elsewhere | Preparing content for the Appstore website submission forms |
 | `switch-api/api-versions.md` | Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml` | Writing or reviewing code for a script or app that must run on a Switch version older than the latest, or when the user names a minimum Switch version |
+| `switch-project/node-versions.md` | How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion` | Working out which Node.js version a script or app will run on, or what `SwitchVersion` in manifest.xml does |
 <!-- docs-index:table end -->
 
 ## Key rules
 - Before scaffolding a new script or app, work through `switch-project/project-planning.md` with the user.
-- Always consult the API reference files above before writing or modifying script code.
+  If the script folder is already scaffolded, still ask Script or App; the manifest cannot answer it.
 - If the script or app must run on a Switch version older than the latest, check each API call
   against `switch-api/api-versions.md`. The API files mark anything newer than the baseline with
   "Switch X+" (a `// Switch X+` comment above a signature, or a note in the text), meaning that

package/package.json

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