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

package/CHANGELOG.md

@@ -5,6 +5,66 @@ 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
+
+- The property editor and declaration docs listed a `rational` (decimal) inline editor type,
+  which Node.js scripts do not allow. The docs no longer offer it and now say it is not allowed.
+- `createJob()` was documented as valid only from `jobArrived` and `timerFired`. It also works from
+  `httpRequestTriggeredAsync`, the only webhook entry point that receives `flowElement`.
+- Documented that `Type="password"` needs `Subtype=""`, not `"inline"`. The latter fails at script
+  load with an unsupported-editor error, even though it is the usual `Subtype` for a single inline
+  editor.
+- Documented that `IncomingConnections="Yes"` with `RequireAtLeastOne="No"` makes the incoming
+  connection optional per flow element instance, letting one script support both a flow-starting
+  role and a mid-flow role.
+
 ## [25.11.1-beta.4] - 2026-09-20
 
 ### Added

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.4/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.4/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()`.