@enfocussw/switch-scripting-context 25.11.0-beta.8 → 25.11.1-beta.0

package/CHANGELOG.md

@@ -5,11 +5,257 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.1-beta.0] - 2026-09-15
+
+### Added
+
+- New `api-versions.md` lists which Switch release added each scripting API class, method, and
+  enum value. The API docs now mark each method, class, and enum value that needs a newer release
+  than the baseline with its minimum Switch version. Agents can check calls against the oldest
+  Switch a script or app must support.
+
+### Changed
+
+- The Node.js version table now covers Switch 25.07, 26.03, and 26.07. It also explains that
+  `--pack` and SwitchScripter overwrite `SwitchVersion`, so a packed script can run on a newer
+  Node.js than its folder. It covers fallbacks for unlisted values and notes that API methods
+  follow the running Switch, not the manifest.
+
+### Fixed
+
+- The routing table in `switch-scripting.md` now renders correctly in strict markdown parsers,
+  including VS Code's preview. The generated marker comments previously sat between the table's
+  header and its first row, which ended the table early per the GFM table spec; they now wrap the
+  whole table instead.
+
+## [25.11.0-beta.18] - 2026-09-11
+
+### Fixed
+
+- The script declaration doc no longer tells agents to bump `Version` on every declaration change.
+  It now says to bump once per release and keep an unreleased number while editing, matching the
+  Appstore guidelines. It also notes that SwitchScripter only accepts minor versions for apps.
+
+## [25.11.0-beta.17] - 2026-09-11
+
+### Changed
+- `job.md`'s `sendToData()` entry and `connection.md`'s `getPropertyStringValue()` entry now warn
+  directly, at the point an agent is most likely to read them, that there is no way to check in
+  advance whether a connection accepts a given traffic light level. The warning previously lived
+  only in a separate section agents weren't always reaching first.
+
+## [25.11.0-beta.16] - 2026-09-10
+
+### Added
+- Connection docs clarify that traffic light levels (`Connection.Level.Success`/`Warning`/`Error`)
+  only select where `sendToData()`/`sendToLog()` route a job; they cannot be read back from a
+  connection object, and `sendToData()` fails the job if no connected level matches. Scripts that
+  need optional traffic light routing should expose a custom property and fall back to
+  `sendToNull()`.
+
+### Fixed
+- `switch-scripting.md`'s own text told agents to grep a `docs/` prefix that only exists in this
+  repo's source tree, not in a consuming project's copied docs folder. Agents following that
+  instruction literally hit a folder that doesn't exist. The text now describes the copied layout.
+
+## [25.11.0-beta.15] - 2026-09-10
+
+### Added
+- `property-documentation.md`, `app-store-listing.md`, `app-manual.md`, and
+  `app-store-submission.md`: writing guidance for the four separate places app documentation
+  ends up (per-property `Tooltip`/`DetailedInfo`, the declaration's listing fields, the uploaded
+  app manual document, and the Appstore website submission forms), including which content is
+  reused between them, icon specs, and a shared checklist against generic-sounding text.
+
+### Changed
+- Docs reorganized under `docs/`: the scripting API stays in `docs/switch-api/`; project structure
+  and tooling docs moved to `docs/switch-project/`; Appstore publishing guidance moved to
+  `docs/switch-appstore/`. Update any bookmarked doc paths after upgrading.
+- Dropped the `api-` prefix from doc filenames, for example `switch-api/job.md`, since each file's
+  folder already says what kind of doc it is.
+- Each doc file now carries its own routing metadata (trigger and summary) as YAML frontmatter,
+  generated into the routing table and README's doc list instead of hand-duplicated in both.
+  README's descriptions now match the table's wording exactly; a few had drifted apart.
+
+### Fixed
+- `init` now removes the destination docs folder before copying, instead of only adding and
+  overwriting. Previously, a doc renamed or moved between versions left the old file behind
+  permanently after an upgrade, since the destination folder is gitignored and nothing surfaced
+  the stale copy.
+
+## [25.11.0-beta.14] - 2026-09-09
+
+### Added
+- `switch-scripting.md` now tells agents to grep `docs/switch-api/` for `known issue`, `gotcha`,
+  `quirk`, `caveat` to find documented pitfalls before writing code in an area.
+- `api-entry-points.md` documents that a flow restart replays every queued job through `jobArrived`
+  again, even one whose processing was deferred to `timerFired`. A script relying on that pattern
+  must recognize an already-registered job and return quickly, or a large backlog is slow to clear.
+- `api-project-planning.md`, a pre-scaffolding checklist for new scripts and apps: Script vs App,
+  job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm
+  dependency feasibility, and Appstore competition risk. Loaded before any files are scaffolded.
+
+### Changed
+- `README.md` no longer uses dashes as punctuation. Wording is unchanged otherwise.
+- The published README now links to the changelog on jsdelivr, pinned to the version being
+  installed. Relative links were rewritten by npm to the private repo, so they were dead for
+  consumers. `prepack` swaps them in and `postpack` swaps them back.
+
+## [25.11.0-beta.13] - 2026-09-09
+
+### Fixed
+- README's two CHANGELOG links pointed at an unversioned jsdelivr URL, which always serves the
+  *latest published* file. On GitHub that showed the published file rather than the repo's live one,
+  hiding unreleased entries. Both are now relative links, so GitHub resolves them to the live file.
+- Generated tool config (Cursor, Codex/OpenCode, Windsurf, Zed, Cline) — the "Core rules" block told
+  agents never to edit `<ScriptID>.xml` and to send the user to SwitchScripter instead. That has
+  contradicted `api-script-declaration.md` and the `switch-scripting.md` key rules since the agent
+  editing policy was added, and it sat in an always-on rules file that outranks any doc the agent
+  loads later. Now matches the docs: direct editing is fine under the declaration's rules.
+
+### Added
+- `api-switch.md` — a "Translation extraction rules" section under `Switch.tr()`. Extraction is
+  static source analysis, so aliasing `Switch.tr`, concatenating with a variable, or interpolating
+  a template literal silently produces no translation entry at all. Documents what does work
+  (all quote styles, multi-line, literal-only concatenation, marking a string away from its use
+  site) and the `%1` + `messageParams` pattern for dynamic values.
+- `api-job-patterns.md` — "Driving a third-party CLI application", the Node.js replacement for the
+  legacy `findApplicationPath`/`ApplicationPath` mechanism: a custom path property on the
+  `automatic;choosefile;sltextwithvar;scriptexp` chain, resolved once in `flowStartTriggered` into
+  `Scope.FlowElement` global data, with `failProcess()` when discovery fails and cleanup in
+  `flowStopTriggered`.
+- `api-script-structure.md` — "Packing an app" and SwitchScripter/Switch version compatibility:
+  script folders can only be typed `Script` (pack, then retype to `App` in SwitchScripter), extra
+  files are unavailable in script-folder mode, the pack ID is always `com.enfocus.*` and is carried
+  over by opening the previous `.enfpack`, an app loads only in its build version or newer (no
+  Scripter for 25.07/25.11 — use 2024 Fall), and an unsigned app loads only on the machine that
+  built it.
+- `api-app-guidelines.md` — the App-only section is now split into Identity and versioning,
+  Top-level declaration properties, Password protection, Localization, Icon, Extra files, Source
+  and review hygiene, and what review does and doesn't cover. New rules from the App SDK: script ID
+  charset and uniqueness, resubmit-without-bumping after a rejection, minor-version format, the
+  three-category limit and Product Management approval, unsigned apps always loading under
+  "Custom", `DetailedInfo` feeding the generated HTML docs, `ExecutionGroup` coordination for a
+  shared third-party application, `Compatibility`/`SupportInfo`/`AppDiscovery` being required to
+  build the pack at all, Node.js password protection being unrecoverable, the six-language limit on
+  app translations, the 200×200 Appstore icon, and macOS notarization checks via `codesign -dv`.
+- Generated tool config and `switch-scripting.md` key rules — added the entry-point scanner
+  constraints (literal `function` keyword; no trailing-backslash string literals, regex literals, or
+  non-`word / word` division) to the always-on rules. Previously these lived only in
+  `api-entry-points.md`, so an agent making a small edit without opening that file had no signal
+  that the failure mode exists, and it fails silently.
+
+### Changed
+- Generated tool config for Cursor, Codex/OpenCode, Windsurf, Zed and Cline now lists each API doc
+  with its "Load when" routing text instead of a bare filename, so those agents can open the one
+  file they need without reading `switch-scripting.md` first. Costs ~600 tokens in the always-on
+  block, saves a ~1,300-token hub read per session.
+- The routing table in `docs/switch-scripting.md` is now the single source for that list. `init.ts`
+  parses it (`parseRoutingTable()`); the two hardcoded 19-entry arrays are gone, as is the drift
+  they invited.
+- `api-script-structure.md` — moved "App Store submission guidelines" into
+  `api-app-guidelines.md` § App-only and "Execution modes" into `api-execution-environment.md`,
+  leaving pointers at both old headings. Reviewing an app or reasoning about concurrency previously
+  needed two files for one topic. Existing anchor links still resolve.
+- `docs/switch-scripting.md` and `README.md` — sharpened the routing descriptions for
+  `api-job.md` (signatures) vs `api-job-patterns.md` (rules and gotchas), and for
+  `api-script-structure.md` vs `api-tooling.md`. Their triggers overlapped enough that an agent had
+  to load both files for any job-handling task.
+- `init` no longer copies `docs/superpowers`, `docs/temp`, or `.DS_Store` into a consuming project.
+  The published tarball already excludes them, but `init` run from a git clone did not.
+
+## [25.11.0-beta.12] - 2026-09-08
+
+### Fixed
+- `README.md` — linked the two `CHANGELOG.md` mentions to the jsdelivr-served copy of the file
+  instead of leaving them as unlinked plain text. A relative link would have npm rewrite it to a
+  GitHub blob URL that 404s on npmjs.com, since the source repo is private; jsdelivr serves the file
+  straight from the published tarball regardless of repo visibility.
+
+## [25.11.0-beta.11] - 2026-09-08
+
+### Added
+- `api-entry-points.md` — documented that Switch's entry-point scanner is regex-based (not a real
+  parser) and can silently drop `function` declarations from certain source shapes: string literals
+  ending in a backslash, regex literals (especially ones containing an unescaped `/` inside a
+  character class), and division not in a plain `word / word` shape. Applies to every entry point,
+  not just the ones checked at load time; `calculateScriptExpression` is the one exception, since
+  it's dispatched directly rather than through this scanner. Verified against real
+  `SwitchScriptTool --pack` output for each failure mode.
+- `api-tooling.md` — new "Verify entry points before packing" section with a Python/Node.js script
+  to check a built `main.js` for the expected entry points before relying on `--pack`, which doesn't
+  validate this itself.
+- `api-script-structure.md` — cross-linked the entry-point scanner constraints from the "Agent
+  editing policy" callout.
+- `api-app-guidelines.md` — new pre-publish checklist for scripts submitted to the Enfocus Appstore,
+  covering property naming/tooltip/editor/default requirements, entry point and `sendTo*()`
+  consistency with declared connections, logging quality, temp file/path handling, and app-only
+  packaging rules (no embedded Oracle JRE, universal signed macOS Mach-O binaries in extra files,
+  immutable extra files, translation completeness). Registered in the routing table, both `init.ts`
+  doc-file arrays, and the README's included-docs list.
+
+### Changed
+- `switch-scripting.md` — broadened the `api-entry-points.md` routing-table trigger to any edit to
+  `main.ts`/`main.js`, not just adding a new entry point.
+- `api-property-editors.md` — documented that the `nofiles`/`allfiles`/`allotherfiles` and
+  `nofolders`/`allfolders`/`allotherfolders` literal editors are specifically for connection
+  include/exclude filter mask properties, with the exact `Editor`/`Default`/`Subtype` chain verified
+  against Switch's own built-in connection filter declarations; added the matching rows to Common
+  practices. Noted that `next`/`current` have no confirmed script-facing use case. Noted that `none`
+  is the sanctioned way to allow an empty value under `Validation="Standard"`.
+- `api-script-declaration.md` — cross-linked the `Validation` row to the `none` literal editor for
+  allowing empty values under `Standard` validation.
+- `api-app-guidelines.md`, `api-script-declaration.md`, `api-property-editors.md`,
+  `api-entry-points.md`, `api-job-patterns.md`, `api-logging.md`, `api-script-structure.md` —
+  reclassified the Appstore submission rules added previously: most turned out to be universal
+  correctness rules (functional requirements or bugs if violated) rather than app-specific policy,
+  so their "App guideline" framing was removed and they're now stated as plain rules that apply to
+  every script. Only a handful remain "mandatory for apps, recommended for scripts" (property
+  naming/tooltip/default, non-module-editor requirement, log volume, platform-independent paths).
+  "No embedded Oracle JRE" moved out of the app-only section entirely, since it applies to any
+  script bundling extra files. `api-app-guidelines.md` is now organized into three explicit tiers
+  (Universal / Apps required-scripts recommended / Apps only) instead of one flat list.
+- `api-script-declaration.md`, `api-property-editors.md`, `api-entry-points.md`, `api-job-patterns.md`,
+  `api-job.md`, `api-logging.md`, `api-script-structure.md` — wove the individual Appstore submission
+  rules (above) directly into the relevant existing sections (property attributes, editor tables,
+  entry point signatures, `sendTo*()`/`ConnectionType` rules, logging conventions, packaging), each
+  cross-linked to and from the new checklist, so they're followed from the start rather than caught
+  only at a pre-publish review.
+- `api-script-declaration.md` — fixed the `Validation="Custom"` row, which named a nonexistent
+  `isPropertyValid` entry point; the actual entry point (per `api-entry-points.md`) is
+  `validateProperties`/`validateConnectionProperties`.
+- `api-job-patterns.md` — clarified that the automatic executor-refresh cleanup only applies to
+  temp files created via `flowElement.createPathWithName()` (the recommended default); temp files
+  created any other way must be cleaned up explicitly by the script. Also notes that the `tmp` npm
+  package is not recommended, and if used anyway, its `setGracefulCleanup()` is not always reliable
+  in the Switch execution environment and `discardDescriptor: true` should be set.
+- `api-flow-element.md`, `api-connection.md`, `api-script-declaration.md` — cross-linked and made
+  explicit that `getPropertyStringValue()`/`connection.getPropertyStringValue()` throws
+  `"Invalid tag: <tag>"` for a `Dependency` dependent property currently hidden by its master's
+  value, and that `hasProperty()`/`connection.hasProperty()` should be used to guard against this
+  (e.g. before fetching properties dependent on a drop-down/enum master). Also notes that the shown
+  set can vary per job if the master's value is dynamic, and that a hidden dependent's value cannot
+  be read at all — a script needing more than one dependency group's data at once must use a
+  different property structure, not `Dependency`-based hiding.
+
+## [25.11.0-beta.10] - 2026-09-03
+
+### Added
+- `api-job-patterns.md` — documented a known ordering bug: creating a child job before writing a
+  pending dataset causes the child to inherit the stale dataset, leading to a destructive
+  file-move race at `sendTo*()`. `api-job.md`'s dataset/child-job entries now note which calls
+  are immediate vs. deferred.
+
+## [25.11.0-beta.9] - 2026-08-26
+
 ### Added
 - `package.json` now declares `"main": "dist/init.js"`. Deliberately no `"exports"` field, so
   `switch-scripting-context/package.json` also stays reachable for consumers that need to read the
   package's own version (e.g. to compare against a script's target Switch version).
 
+### Changed
+- Package now publishes to the public npm registry instead of GitHub Packages.
+
 ## [25.11.0-beta.8] - 2026-08-25
 
 ### Removed

package/README.md

@@ -4,21 +4,11 @@ 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) for what's changed between versions.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.0/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
-> **Private beta.** This package is not on npm yet. Beta testers install from a
-> tarball supplied directly; the npm commands below apply once it is published.
-
-Install the tarball you were given, then run `init` in any Switch scripting project:
-
-```bash
-npm install --save-dev ./enfocussw-switch-scripting-context-25.11.0-beta.1.tgz
-npx switch-scripting-context init
-```
-
-After publication, install straight from npm instead:
+Run `init` in any Switch scripting project:
 
 ```bash
 npx @enfocussw/switch-scripting-context init
@@ -44,16 +34,14 @@ 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.
-- The next Switch release moves the first two numbers (e.g. Switch 26.05 → `26.5.0`). Note that semver forbids leading zeros, so `26.05` is published as `26.5`.
+- `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.
-During the beta these are distributed as tarballs rather than published, so the suffix is
-purely a label telling testers which build they have.
 
 ## What it does
 
@@ -65,9 +53,9 @@ purely a label telling testers which build they have.
 
 | 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 |
@@ -75,28 +63,28 @@ purely a label telling testers which build they have.
 | 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.1-beta.0/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -142,22 +130,31 @@ npm install --save-dev "https://github.com/enfocus-switch/types-switch-scripting
 
 The `switch-docs/` folder contains:
 
-- `switch-scripting.md` — master index with execution environment rules and "load when" routing table
-- `switch-api/api-entry-points.md` — all entry point signatures and when each is called
-- `switch-api/api-job.md` — `Job` class: routing, file access, child jobs, private data, datasets
-- `switch-api/api-flow-element.md` — `FlowElement`: properties, connections, job creation, logging
-- `switch-api/api-switch.md` — `Switch` global: global data, webhooks, abort, server utilities
-- `switch-api/api-connection.md` — `Connection`: type, properties, file count
-- `switch-api/api-http.md` — `HttpRequest` / `HttpResponse` and webhook pattern
-- `switch-api/api-enums.md` — all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
-- `switch-api/api-document-classes.md` — `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
-- `switch-api/api-script-declaration.md` — XML declaration reference
-- `switch-api/api-script-structure.md` — script folder/package structure and manifest format
-- `switch-api/api-tooling.md` — SwitchScriptTool commands, script folder vs package, build and deployment
-- `switch-api/api-debugging.md` — enabling debug mode, debuggable entry points, VS Code attach
-- `switch-api/api-logging.md` — log levels, when/what to log, `console.log` limitation, common gotchas
-- `switch-api/api-logs-and-dataroot.md` — locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
-- `switch-api/api-vscode.md` — type declarations, tsconfig for TypeScript 6, ESLint rules
-- `switch-api/api-property-editors.md` — property editor types and string return values
-- `switch-api/api-job-patterns.md` — file access semantics, routing rules, child jobs, executor limits
-- `switch-api/api-execution-environment.md` — process model, state persistence across jobs, error handling, npm/native module constraints
+- `switch-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-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
+- `switch-api/job.md`: `Job` **signatures**: routing, file access, child jobs, private data, datasets
+- `switch-api/connection.md`: `Connection`: type, properties, file count
+- `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/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
+- `switch-project/script-declaration.md`: XML declaration reference: properties, connections, execution config; agents may edit this file directly
+- `switch-project/property-editors.md`: Property editor types, string return values, literal editors, dropdowns
+- `switch-api/job-patterns.md`: `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits
+- `switch-api/execution-environment.md`: Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints
+- `switch-api/logging.md`: Log level semantics, logging practice, `console.log` limitation, common gotchas
+- `switch-project/logs-and-dataroot.md`: Locating the Application Data Root, querying `ServerLogs.db3` directly
+- `switch-appstore/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)
+- `switch-project/property-documentation.md`: Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections
+- `switch-appstore/app-store-listing.md`: Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`
+- `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`
+<!-- docs-index:readme end -->

package/dist/init.d.ts

@@ -9,6 +9,21 @@ export interface ToolDefinition {
     altIds?: string[];
     files: ToolFile[];
 }
+export interface ApiDoc {
+    /** Path within docs/, e.g. "switch-api/job.md". */
+    file: string;
+    /** The routing table's "Load when" text, verbatim. */
+    loadWhen: string;
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+export declare function parseRoutingTable(root?: string): ApiDoc[];
+/** Filenames only, in routing-table order. */
+export declare function apiFiles(root?: string): string[];
 export declare function generateAgentsMd(docsDir: string): string;
 export declare function generateGeminiMd(docsDir: string): string;
 export declare function generateWindsurfRules(docsDir: string): string;

package/dist/init.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutingTable = parseRoutingTable;
+exports.apiFiles = apiFiles;
 exports.generateAgentsMd = generateAgentsMd;
 exports.generateGeminiMd = generateGeminiMd;
 exports.generateWindsurfRules = generateWindsurfRules;
@@ -47,6 +49,46 @@ const readline = __importStar(require("readline"));
 // ─── Markers ─────────────────────────────────────────────────────────────────
 const MARKER_BEGIN = '<!-- switch-scripting-context begin -->';
 const MARKER_END = '<!-- switch-scripting-context end -->';
+// ─── Shared content (single source of truth for all generated tool files) ────
+/** Package root, whether running from src/ (ts-node) or dist/. */
+function packageRoot() {
+    return path.resolve(__dirname, '..');
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+function parseRoutingTable(root = packageRoot()) {
+    const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
+    const docs = [];
+    for (const line of hub.split('\n')) {
+        // | `<switch-api|switch-project|switch-appstore>/<file>.md` | <contents> | <load when> |
+        const m = /^\|\s*`(switch-api|switch-project|switch-appstore)\/([a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
+        if (m)
+            docs.push({ file: `${m[1]}/${m[2]}`, loadWhen: m[4].trim() });
+    }
+    if (docs.length === 0) {
+        throw new Error('No API docs found in docs/switch-scripting.md — the routing table format changed. ' +
+            'Generated tool config would be empty; fix parseRoutingTable() before publishing.');
+    }
+    return docs;
+}
+/** Filenames only, in routing-table order. */
+function apiFiles(root) {
+    return parseRoutingTable(root).map(d => d.file);
+}
+const INLINE_CORE_RULES = `## Core rules
+
+- Entry point functions are top-level async functions — do NOT use \`export\`, arrow functions, or class methods; declare them with the literal \`function\` keyword.
+- Switch finds entry points with a regex, not a parser. Never write a string literal whose content ends with a backslash, a regex literal, or division outside the plain \`word / word\` shape — each silently deletes a span of real code and the entry points inside it, with no error. Read \`entry-points.md\` § Entry-point scanner constraints before editing \`main.ts\`/\`main.js\`.
+- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
+- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
+- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
+- The XML declaration (\`<ScriptID>.xml\`) can be edited directly — read \`script-declaration.md\` first and follow its rules exactly (nothing validates this format, so mistakes fail silently). Never change an existing script's \`Name\`; bump \`Version\` on every declaration edit. Leave \`manifest.xml\` to the user unless explicitly asked.
+- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
+- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
 // ─── Content generators ──────────────────────────────────────────────────────
 function generateClaudeMd(docsDir) {
     return `${MARKER_BEGIN}
@@ -76,27 +118,6 @@ You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 ${MARKER_END}`;
 }
 function generateCursorMdc(docsDir) {
-    const apiFiles = [
-        'api-entry-points.md',
-        'api-job.md',
-        'api-flow-element.md',
-        'api-connection.md',
-        'api-http.md',
-        'api-enums.md',
-        'api-document-classes.md',
-        'api-script-declaration.md',
-        'api-script-structure.md',
-        'api-tooling.md',
-        'api-debugging.md',
-        'api-vscode.md',
-        'api-property-editors.md',
-        'api-job-patterns.md',
-        'api-switch.md',
-        'api-execution-environment.md',
-        'api-logging.md',
-        'api-logs-and-dataroot.md',
-    ];
-    const fileList = apiFiles.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
     return `---
 description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
 globs: ["**/*.ts", "**/*.js"]
@@ -106,55 +127,21 @@ alwaysApply: false
 ${MARKER_BEGIN}
 You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
 
-## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.
+${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
-${fileList}
+${inlineApiFileList(docsDir)}
 ${MARKER_END}`;
 }
-// ─── Shared inline content (for tools without @file import support) ──────────
-const INLINE_CORE_RULES = `## Core rules
-
-- Entry point functions are top-level async functions — do NOT use \`export\`.
-- Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
-- Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
-- After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- Never edit \`<ScriptID>.xml\` or \`manifest.xml\` directly. For property/connection changes, instruct the user to use SwitchScripter.
-- After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
-- Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
-const API_FILES = [
-    'api-entry-points.md',
-    'api-job.md',
-    'api-flow-element.md',
-    'api-connection.md',
-    'api-http.md',
-    'api-enums.md',
-    'api-document-classes.md',
-    'api-script-declaration.md',
-    'api-script-structure.md',
-    'api-tooling.md',
-    'api-debugging.md',
-    'api-vscode.md',
-    'api-property-editors.md',
-    'api-job-patterns.md',
-    'api-switch.md',
-    'api-execution-environment.md',
-    'api-logging.md',
-    'api-logs-and-dataroot.md',
-];
+// ─── Inline block (for tools without @file import support) ──────────────────
 function inlineApiFileList(docsDir) {
-    return API_FILES.map(f => `- \`${docsDir}/switch-api/${f}\``).join('\n');
+    return parseRoutingTable()
+        .map(d => `- \`${docsDir}/${d.file}\` — ${d.loadWhen}`)
+        .join('\n');
 }
 function generateInlineBlock(docsDir) {
     return `You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
@@ -163,7 +150,8 @@ ${INLINE_CORE_RULES}
 
 ## API reference
 
-Read \`${docsDir}/switch-scripting.md\` for the full index, then consult the relevant file:
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` has the same index plus
+the project-wide key rules:
 
 ${inlineApiFileList(docsDir)}`;
 }
@@ -345,13 +333,36 @@ function applyFileAction(action, dryRun) {
     console.log(`  ${rel} → ${label}`);
 }
 // ─── Docs copy ────────────────────────────────────────────────────────────────
+/** Paths under docs/ that are never shipped to a consuming project. */
+const DOCS_EXCLUDE = ['superpowers', 'temp'];
 function copyDocs(packageRoot, destDir, dryRun) {
     const src = path.join(packageRoot, 'docs');
+    const rel = path.relative(process.cwd(), destDir);
     if (dryRun) {
-        console.log(`  [dry-run] Copying docs/ → ${path.relative(process.cwd(), destDir)}/`);
+        if (fs.existsSync(destDir)) {
+            console.log(`  [dry-run] ${rel}/ → wiped (removes files from a previous version, e.g. after a doc was renamed or moved)`);
+        }
+        console.log(`  [dry-run] Copying docs/ → ${rel}/`);
         return;
     }
-    fs.cpSync(src, destDir, { recursive: true });
+    // destDir is entirely owned by this tool (see the .gitignore comment it writes), so wiping
+    // it first is safe. Without this, a doc renamed or moved between versions (e.g. a docs/
+    // folder restructuring) would leave the old file behind forever: cpSync only adds/overwrites,
+    // it never removes, and destDir is gitignored so nothing would surface the staleness.
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    // The published tarball already omits these, but init may run from a git clone.
+    fs.cpSync(src, destDir, {
+        recursive: true,
+        filter: (from) => {
+            const rel = path.relative(src, from);
+            if (!rel)
+                return true;
+            const [top] = rel.split(path.sep);
+            return !DOCS_EXCLUDE.includes(top) && path.basename(from) !== '.DS_Store';
+        },
+    });
     console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
 }
 // ─── .gitignore update ───────────────────────────────────────────────────────