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

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.0-beta.14] - 2026-09-09
+
+### Added
+- `switch-scripting.md` now tells agents to grep `docs/switch-api/` for `known issue`, `gotcha`,
+  `quirk`, `caveat` to find documented pitfalls before writing code in an area.
+- `api-entry-points.md` documents that a flow restart replays every queued job through `jobArrived`
+  again, even one whose processing was deferred to `timerFired`. A script relying on that pattern
+  must recognize an already-registered job and return quickly, or a large backlog is slow to clear.
+- `api-project-planning.md`, a pre-scaffolding checklist for new scripts and apps: Script vs App,
+  job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm
+  dependency feasibility, and Appstore competition risk. Loaded before any files are scaffolded.
+
+### Changed
+- `README.md` no longer uses dashes as punctuation. Wording is unchanged otherwise.
+- The published README now links to the changelog on jsdelivr, pinned to the version being
+  installed. Relative links were rewritten by npm to the private repo, so they were dead for
+  consumers. `prepack` swaps them in and `postpack` swaps them back.
+
 ## [25.11.0-beta.13] - 2026-09-09
 
 ### Fixed

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](CHANGELOG.md) (also included in this package) for what's changed between versions.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.14/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -34,13 +34,13 @@ The package version tracks the Switch release its docs describe:
   └────── Switch version (25.11)
 ```
 
-- `25.11.x` — every release of this package documenting **Switch 25.11**. Patch increments are doc updates, fixes, and new features of the CLI itself.
+- `25.11.x`: every release of this package documenting **Switch 25.11**. Patch increments are doc updates, fixes, and new features of the CLI itself.
 - The next Switch release moves the first two numbers (e.g. Switch 27.07 → `27.7.0`). Note that semver forbids leading zeros, so `27.07` is published as `27.7`.
 - **Pin with `~`, not `^`.** `~25.11.0` stays on Switch 25.11; `^25.11.0` would happily install `25.12.0`, which targets a different Switch release.
 
 ### Prereleases
 
-Beta builds append a prerelease suffix — `25.11.0-beta.1`. These sort *below* `25.11.0`,
+Beta builds append a prerelease suffix, for example `25.11.0-beta.1`. These sort *below* `25.11.0`,
 so the beta line precedes GA and leaves `25.11.0` free for the first published release.
 
 ## What it does
@@ -53,9 +53,9 @@ so the beta line precedes GA and leaves `25.11.0` free for the first published r
 
 | Tool | File | How context is loaded |
 |---|---|---|
-| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import — hub file routes to specific API docs on demand |
+| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import; hub file routes to specific API docs on demand |
 | GitHub Copilot | `.github/copilot-instructions.md` | `#file:` reference to hub |
-| GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"` — auto-attaches to every TypeScript file edit |
+| GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"`; auto-attaches to every TypeScript file edit |
 | Cursor | `.cursor/rules/switch-scripting.mdc` | Inline key rules + full API file path list |
 | Codex CLI / OpenCode | `AGENTS.md` | Inline key rules + full API file path list |
 | Gemini CLI | `GEMINI.md` | `@switch-docs/switch-scripting.md` import |
@@ -63,28 +63,28 @@ so the beta line precedes GA and leaves `25.11.0` free for the first published r
 | Zed | `.rules` | Inline key rules + full API file path list |
 | Cline | `.clinerules` | Inline key rules + full API file path list |
 
-All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers. Re-running `init` replaces only the Switch section in existing files — project-specific rules outside the markers are untouched.
+All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers. Re-running `init` replaces only the Switch section in existing files. Project-specific rules outside the markers are untouched.
 
 ## Using this with your coding agent
 
-Once `init` has run, just work normally — describe what you want in plain terms and prompt as you
+Once `init` has run, just work normally. Describe what you want in plain terms and prompt as you
 usually would. Your agent picks up the Switch context automatically (via `@import` for Claude
 Code/Gemini, or the inlined rules + file list for the others) whenever it's working in the project,
 and pulls in the specific API doc it needs for the task at hand on its own. You don't need to know
 the doc file names or tell it which one to read.
 
 A few things this gets you without asking for them by name:
-- Scaffolding a new entry point, handling a webhook, or reading/creating datasets and jobs — the
+- Scaffolding a new entry point, handling a webhook, or reading/creating datasets and jobs. The
   agent consults the matching API reference before writing the code.
-- Diagnosing why a script isn't behaving as expected — the agent knows it can locate and query
+- Diagnosing why a script isn't behaving as expected. The agent knows it can locate and query
   Switch's own log database (`ServerLogs.db3`) rather than only re-reasoning about the code.
-- Creating, packing, or deploying a script — the agent uses `SwitchScriptTool` with the documented
-  flags and behavior, rather than hand-rolling the steps.
-- Editing the script's XML declaration — the agent follows the documented rules and knows which
-  properties (app path/license) are off-limits and left to SwitchScripter's GUI instead.
+- Creating, packing, or deploying a script. The agent uses `SwitchScriptTool` with the documented
+  flags and behaviour, rather than hand-rolling the steps.
+- Editing the script's XML declaration. The agent follows the documented rules and knows which
+  properties (app path/licence) are off-limits and left to SwitchScripter's GUI instead.
 
-Re-run `init` after upgrading this package so the copied docs and generated config files catch up —
-see [CHANGELOG.md](CHANGELOG.md) for what changed.
+Re-run `init` after upgrading this package so the copied docs and generated config files catch up.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.14/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -130,23 +130,24 @@ npm install --save-dev "https://github.com/enfocus-switch/types-switch-scripting
 
 The `switch-docs/` folder contains:
 
-- `switch-scripting.md` — master index with execution environment rules and "load when" routing table
-- `switch-api/api-entry-points.md` — all entry point signatures and when each is called
-- `switch-api/api-job.md` — `Job` class signatures: routing, file access, child jobs, private data, datasets
-- `switch-api/api-flow-element.md` — `FlowElement`: properties, connections, job creation, logging
-- `switch-api/api-switch.md` — `Switch` global: global data, webhooks, abort, server utilities
-- `switch-api/api-connection.md` — `Connection`: type, properties, file count
-- `switch-api/api-http.md` — `HttpRequest` / `HttpResponse` and webhook pattern
-- `switch-api/api-enums.md` — all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
-- `switch-api/api-document-classes.md` — `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
-- `switch-api/api-script-declaration.md` — XML declaration reference
-- `switch-api/api-script-structure.md` — script folder contents, manifest format, Node.js version per Switch release, Script vs App
-- `switch-api/api-tooling.md` — SwitchScriptTool commands, script folder vs package, build and deployment
-- `switch-api/api-debugging.md` — enabling debug mode, debuggable entry points, VS Code attach
-- `switch-api/api-logging.md` — log levels, when/what to log, `console.log` limitation, common gotchas
-- `switch-api/api-logs-and-dataroot.md` — locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
-- `switch-api/api-vscode.md` — type declarations, tsconfig for TypeScript 6, ESLint rules
-- `switch-api/api-property-editors.md` — property editor types and string return values
-- `switch-api/api-job-patterns.md` — `Job` rules and gotchas: file access semantics, temp cleanup, routing rules, child jobs, executor limits
-- `switch-api/api-execution-environment.md` — execution modes, process model, state persistence across jobs, error handling, npm/native module constraints
-- `switch-api/api-app-guidelines.md` — pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, app-only submission rules
+- `switch-scripting.md`: master index with execution environment rules and "load when" routing table
+- `switch-api/api-project-planning.md`: pre-scaffolding checklist covering Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `switch-api/api-entry-points.md`: all entry point signatures and when each is called
+- `switch-api/api-job.md`: `Job` class signatures for routing, file access, child jobs, private data, datasets
+- `switch-api/api-flow-element.md`: `FlowElement`: properties, connections, job creation, logging
+- `switch-api/api-switch.md`: `Switch` global: global data, webhooks, abort, server utilities
+- `switch-api/api-connection.md`: `Connection`: type, properties, file count
+- `switch-api/api-http.md`: `HttpRequest` / `HttpResponse` and webhook pattern
+- `switch-api/api-enums.md`: all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
+- `switch-api/api-document-classes.md`: `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
+- `switch-api/api-script-declaration.md`: XML declaration reference
+- `switch-api/api-script-structure.md`: script folder contents, manifest format, Node.js version per Switch release, Script vs App
+- `switch-api/api-tooling.md`: SwitchScriptTool commands, script folder vs package, build and deployment
+- `switch-api/api-debugging.md`: enabling debug mode, debuggable entry points, VS Code attach
+- `switch-api/api-logging.md`: log levels, when/what to log, `console.log` limitation, common gotchas
+- `switch-api/api-logs-and-dataroot.md`: locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
+- `switch-api/api-vscode.md`: type declarations, tsconfig for TypeScript 6, ESLint rules
+- `switch-api/api-property-editors.md`: property editor types and string return values
+- `switch-api/api-job-patterns.md`: `Job` rules and gotchas covering file access semantics, temp cleanup, routing rules, child jobs, executor limits
+- `switch-api/api-execution-environment.md`: execution modes, process model, state persistence across jobs, error handling, npm/native module constraints
+- `switch-api/api-app-guidelines.md`: pre-publish checklist for Appstore apps covering property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, app-only submission rules

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

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

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

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

package/docs/switch-scripting.md

@@ -11,6 +11,7 @@ Detailed API docs are in `docs/switch-api/`:
 
 | File | Contents | Load when |
 |---|---|---|
+| `switch-api/api-project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
 | `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
 | `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
 | `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
@@ -32,7 +33,11 @@ Detailed API docs are in `docs/switch-api/`:
 | `switch-api/api-app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
 
 ## Key rules
+- Before scaffolding a new script or app, work through `switch-api/api-project-planning.md` with the user.
 - Always consult the API reference files above before writing or modifying script code.
+- To find documented behavioural pitfalls before writing code in an area, grep `docs/switch-api/`
+  for `known issue`, `gotcha`, `quirk`, `caveat` (case-insensitive) — every documented pitfall uses
+  one of these four terms.
 - Do not `export` entry point functions. Declare them with the literal `function` keyword at top
   level — arrow functions, `exports.name = ...`, and class methods are invisible to Switch.
 - Switch discovers entry points with a regex, not a parser. Never write a string literal whose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.0-beta.13",
+  "version": "25.11.0-beta.14",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",
@@ -27,14 +27,17 @@
     "docs/",
     "!docs/superpowers",
     "!docs/temp",
+    "!docs/adr",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "build:test": "tsc src/init.test.ts --outDir dist --target ES2020 --module commonjs --lib ES2020 --types node --strict --esModuleInterop --skipLibCheck",
-    "test": "npm run build && npm run build:test && node dist/init.test.js",
-    "prepack": "npm run build",
-    "postpack": "node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\""
+    "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js",
+    "prepack": "npm run build && node scripts/readme-links.js --publish",
+    "postpack": "node scripts/readme-links.js --restore && node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\"",
+    "lint:prose": "node scripts/check-prose.js",
+    "lint:gotchas": "node scripts/check-gotcha-tags.js"
   },
   "author": "Sam Wallace",
   "license": "ISC",