@enfocussw/switch-scripting-context 25.11.1-beta.1 → 25.11.1-beta.3

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.1-beta.3] - 2026-09-17
+
+### Added
+
+- `init` now records the version that produced the docs on the first line of
+  `switch-scripting.md`, as an HTML comment reading `switch-scripting-context <version>`. A tool
+  that installs the docs can read it to tell which version a project has, including a checkout
+  someone else set up. Re-running `init` rewrites the line, and `--dry-run` prints it without
+  writing.
+
+## [25.11.1-beta.2] - 2026-09-17
+
+### Added
+
+- Planning now has agents check whether a design needs more than one flow element, and propose
+  one script folder per element before creating files. The script structure docs describe laying
+  out several script folders side by side, and creating them without deleting the folder you
+  work in.
+
+### Fixed
+
+- The tooling docs now warn that `SwitchScriptTool --create` deletes an existing target folder
+  and everything in it, including git history, without asking. Agents are told to check that the
+  target doesn't exist first.
+- The tooling docs now list the files `--pack` actually includes. Pack copies a fixed set of files,
+  not the whole folder, so a script that imports a local module fails to pack. Before, the docs
+  said pack only left out the npm manifest and VS Code settings.
+
 ## [25.11.1-beta.1] - 2026-09-17
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
 
 Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.1/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.3/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -84,7 +84,7 @@ A few things this gets you without asking for them by name:
   properties (app path/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.1/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.3/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -147,7 +147,7 @@ The `switch-docs/` 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, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `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-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
@@ -156,7 +156,7 @@ The `switch-docs/` 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, `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, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App
 - `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

package/dist/init.d.ts

@@ -31,4 +31,8 @@ export declare function generateZedRules(docsDir: string): string;
 export declare function generateClineRules(docsDir: string): string;
 export declare function buildIdMap(registry: ToolDefinition[]): Map<string, string>;
 export declare function findMarkerRange(content: string): [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. */
+export declare function versionStamp(version: string): string;
 export declare function run(argv?: string[]): Promise<void>;

package/dist/init.js

@@ -42,6 +42,8 @@ exports.generateZedRules = generateZedRules;
 exports.generateClineRules = generateClineRules;
 exports.buildIdMap = buildIdMap;
 exports.findMarkerRange = findMarkerRange;
+exports.packageVersion = packageVersion;
+exports.versionStamp = versionStamp;
 exports.run = run;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -365,6 +367,34 @@ function copyDocs(packageRoot, destDir, dryRun) {
     });
     console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
 }
+// ─── Version stamp ───────────────────────────────────────────────────────────
+/** The hub file in the copied docs folder that carries the version stamp. */
+const HUB_FILE = 'switch-scripting.md';
+/** The running package's own version, so a git-clone install stamps what actually ran. */
+function packageVersion(root = packageRoot()) {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+}
+/** The comment init writes as the first line of the copied hub file. */
+function versionStamp(version) {
+    return `<!-- switch-scripting-context ${version} -->`;
+}
+/**
+ * Records which version produced the copied docs, so a consumer can tell what is installed
+ * without having recorded it at install time. Only the copy is stamped: the repo's own
+ * docs/switch-scripting.md is generated output and a stamp there would fight the generator.
+ * copyDocs wipes destDir on every run, so there is never a stale stamp to remove.
+ */
+function stampDocsVersion(packageRoot, destDir, dryRun) {
+    const stamp = versionStamp(packageVersion(packageRoot));
+    const hubPath = path.join(destDir, HUB_FILE);
+    const rel = path.relative(process.cwd(), hubPath);
+    if (dryRun) {
+        console.log(`  [dry-run] ${rel} → first line ${stamp}`);
+        return;
+    }
+    fs.writeFileSync(hubPath, `${stamp}\n${fs.readFileSync(hubPath, 'utf8')}`, 'utf8');
+    console.log(`  ${rel} → stamped ${stamp}`);
+}
 // ─── .gitignore update ───────────────────────────────────────────────────────
 function updateGitignore(targetRoot, docsDir, dryRun) {
     const gitignorePath = path.join(targetRoot, '.gitignore');
@@ -511,6 +541,7 @@ function init(options) {
     // 1. Copy docs
     console.log('Copying docs...');
     copyDocs(packageRoot, docsDestDir, options.dryRun);
+    stampDocsVersion(packageRoot, docsDestDir, options.dryRun);
     // 2. Generate AI config files
     const toolActions = [];
     for (const toolDef of TOOL_REGISTRY) {

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

@@ -2,7 +2,7 @@
 id: project-planning
 category: switch-project
 order: 1
-summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+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"
 triggers:
   - "Starting a new script or app, before scaffolding any files"
 ---
@@ -58,6 +58,18 @@ an already-registered job quickly, or a large backlog is slow to clear, see
 
 ## Evaluate and flag, don't ask upfront
 
+### One script folder or several
+
+One script folder produces one flow element. Once the job-processing design from question 2 is
+clear, check whether it needs more than one flow element: distinct steps a flow builder should
+place and configure as separate elements, or several related apps meant to ship as an app bundle.
+Most designs need one, so don't ask about this upfront.
+
+If the design needs several, propose the split before creating any files: the Script ID and
+purpose of each script folder and, for apps, whether they form an app bundle. Wait for the user to
+confirm. Then lay them out and create them as described in
+[script-structure.md § Several script folders side by side](script-structure.md#several-script-folders-side-by-side).
+
 ### Target OS
 
 Switch Server runs on Windows and macOS. Default to writing platform-independent code (the `path`

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

@@ -2,7 +2,7 @@
 id: script-structure
 category: switch-project
 order: 10
-summary: "What files a script folder contains, `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, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App"
 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"
 ---
@@ -33,6 +33,31 @@ A Switch script project lives in a **script folder** during development and is d
 
 > After editing `main.ts`, transpile with SwitchScriptTool to regenerate `main.js` before testing in Switch.
 
+## Several script folders side by side
+
+One script folder produces one flow element. A design that needs several flow elements, such as
+the apps in an app bundle, needs one script folder per element. Keep them in one parent folder, a
+**script collection**:
+
+```
+my-collection/        the folder the user works in; AI agent config and docs live here
+├── FirstElement/     script folder (manifest.xml, FirstElement.xml, main.ts, ...)
+└── SecondElement/    script folder
+```
+
+- Put each script folder directly under the collection, one level down. Don't nest a script folder
+  inside another script folder, and don't add grouping folders in between.
+- Create each one with `SwitchScriptTool --create <ScriptID> <CollectionFolder>`. First check that
+  `<CollectionFolder>/<ScriptID>/` doesn't exist: `--create` deletes an existing target folder and
+  everything in it without asking.
+- Never use `--create` to turn the collection folder itself into a script folder
+  (`--create <CollectionFolderName> <ParentFolder>`). That deletes the whole collection, including
+  `.git/` and AI agent config. If the user wants a script folder at the top level of the folder
+  they work in, or wants an existing top-level script folder moved down into a subfolder, stop and
+  leave that step to the user.
+- Each script folder keeps its own `package.json`, `node_modules/` and `tsconfig.json`. Run npm,
+  transpile and pack per script folder.
+
 ## manifest.xml format
 
 ```xml

package/docs/switch-project/tooling.md

@@ -36,16 +36,24 @@ location for the current OS if the bare command isn't found.
 |---|---|---|
 | Create | `SwitchScriptTool --create <ScriptID> <Path> [--JavaScript]` | Scaffold a new script folder with all required files |
 | Transpile | `SwitchScriptTool --transpile <Path>` | Compile `main.ts` → `main.js`. **Must use this, not `tsc` directly** |
-| Pack | `SwitchScriptTool --pack <Folder> <Output> [--password <pwd>] [--verbose]` | Create `.sscript` package for deployment |
+| Pack | `SwitchScriptTool --pack <Folder> <OutputFolder> [--password <pwd>] [--verbose]` | Create `<OutputFolder>/<ScriptID>.sscript` for deployment. `<OutputFolder>` is a directory, created if missing, not the package's file path |
 | Unpack | `SwitchScriptTool --unpack <file.sscript> <Folder> [--password <pwd>]` | Extract package to folder |
 | List | `SwitchScriptTool --list <file.sscript>` | List package contents (no password needed) |
 | Generate translations | `SwitchScriptTool --generate-translations <ScriptFolder> <ResultFolder>` | Generate translation files for the script package |
 
 **Create** scaffolds: `manifest.xml`, `<ScriptID>.xml`, `<ScriptID>.sscript`, `main.ts` (or `main.js` with `--JavaScript`), `.vscode/launch.json`, `Resources/`, plus `package.json`, `tsconfig.json`, `.vscode/switch.code-snippets`, and type declarations for TypeScript. Creates `<Path>/<ScriptID>/` — it does not write into `<Path>` directly. `ScriptID` may only contain letters, digits, hyphens, and underscores.
 
+**Gotcha: `--create` deletes an existing target folder.** If `<Path>/<ScriptID>/` already exists, `--create` removes it and everything in it (including `.git/`, a README, or AI agent config files) without prompting, then scaffolds a fresh folder. The only sign is an `Info: Removed existing target folder` line in its output. Never run `--create` where `<Path>/<ScriptID>/` exists, and never use it to turn the folder you're already working in into a script folder: `--create <FolderName> <ParentOfFolder>` wipes that folder. Check that the target doesn't exist first.
+
 **Transpile** is required after every edit to `main.ts` before testing a **script folder** directly in Switch. Switch executes `main.js` only — `main.ts` is never run directly. Using SwitchScriptTool (not `tsc`) ensures the same transpile options as SwitchScripter, which is required for consistent behavior. This step is **not** needed before packing — see Pack below.
 
-**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 — see the excluded-files note below). It always excludes `package.json` and `.vscode/` from the packed output, printed as an "Info: will not be packed" list even without `--verbose`; `--verbose` additionally prints the full list of what *will* be packed. `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 not excluded 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).
+**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.
+
+`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).
+
+**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.
 
 **Unpack** prints package metadata (`Type`, `Protection`, `Status`) before extracting. For a TypeScript-sourced package it extracts only `main.ts` — the compiled `main.js`/`main.js.map` are not written back out, so a pack → unpack round trip returns a clean, editable script folder rather than a compiled snapshot.
 

package/docs/switch-scripting.md

@@ -15,7 +15,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, 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` | 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-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 +24,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, `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, 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/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 |

package/package.json

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