@enfocussw/switch-scripting-context 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,504 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-09
+
+### Changed
+
+- Cursor now loads the Switch rules in every chat, not only when a TypeScript or JavaScript file is
+  in context, so questions asked without a file get them too. Re-run `init` to update the rule. It
+  keeps the rule's frontmatter if you edited it.
+- **Breaking:** Version numbers no longer follow Switch releases. The next version is 0.1.0, and
+  1.0.0 marks the public release. A dependency pinned to `~25.11.0` or similar won't receive the
+  new versions, so change it to `^0.1.0`. Which Switch release added each API member is listed in
+  the docs themselves.
+
+### Added
+
+- The docs now say that after a script's properties change, the element needs "Reload script" in
+  Switch Designer before the flow is activated. Until then a new property is missing and reading it
+  throws `Invalid tag`.
+- The docs now explain the message Switch logs when an entry point returns with a promise, timer
+  or callback still pending. Switch logs it as a Warning before 26.11 and as a Debug message from
+  26.11.
+
+### Fixed
+
+- The webhook and debugging docs now link to the related entry point, tooling, execution mode and
+  logging docs. Before, they linked nowhere, so an agent that opened one had no route to the details
+  it named.
+- The always-loaded rules told agents to bump the declaration's `Version` on every edit, which
+  contradicted the declaration docs. They now say to bump it only when the current value has already
+  been released.
+- The global data docs now describe how `lock` behaves, measured on Switch 26.11. Other
+  invocations wait for a lock instead of failing, until released or their entry point times out.
+  Writing or removing the tag releases it, as does the entry point ending, even by a throw or
+  timeout. One invocation can hold only one lock, so retrying `Token is already locked` never works.
+- Every agent now gets the same core rules. Cursor, Codex, Windsurf, Zed, Cline and Continue gain
+  the planning step, the Switch version check and the pitfall search. Claude Code, Copilot, Gemini
+  and Aider gain the rules to transpile with SwitchScriptTool and to pack a script before production
+  use. Re-run `init` to update the generated files.
+- The `Job` docs now list JSON as a dataset model. They named only XML, XMP, JDF and Opaque, so an
+  agent could claim a JSON log or dataset had to travel as Opaque. `DatasetModel.JSON` exists from
+  Switch 22.0.
+- The VS Code docs now list the entry point snippets SwitchScriptTool generates and their prefixes,
+  instead of pointing to a summary that had no details. The always-loaded rules no longer tell
+  agents to use snippets, which only a person typing in VS Code can expand.
+- The docs now say that `flowElement.setTimerInterval()` only works when called from `timerFired`.
+  Called from another entry point, such as `flowStartTriggered`, Switch ignores the interval and logs
+  a Warning.
+- Agents often looked for a doc at the project root, such as `switch-api/job.md`, and sometimes
+  answered that the docs were missing. The copied index now gives every doc path with the docs folder
+  in front. Re-run `init` to update the copy.
+- The entry point docs gave 60 seconds as a time limit, which agents read as the limit on
+  `jobArrived` and `timerFired`. It is the limit on the `abort` handler. The docs now say those
+  entry points use the flow element's "Abort after (minutes)" property or the matching Switch
+  preference.
+- The `Job` docs now say that `sendTo*()` routing reaches Switch only when the entry point returns,
+  and not at all if it throws or is aborted.
+
+## [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
+
+- Guidance in `docs/switch-project/property-editors.md` for a property whose shape varies by a
+  type selector. Declare an enum master and one dependent per shape instead of encoding JSON in a
+  single property, so each shape gets a native editor and most parsing disappears. Includes the
+  two constraints: the master must be static, and a hidden dependent throws when read.
+- A rule in `docs/switch-api/logging.md` against adding a script-level verbosity property. Switch
+  already gates `Debug` behind a preference, so the property duplicates a control the user has and
+  costs a pane row and translated strings.
+
+### Changed
+
+- `init` and `remove` now write to a docs folder named `docs-for-agents` instead of
+  `switch-docs`. Re-running `init` after an upgrade deletes the old folder, drops its gitignore
+  line, and repoints the generated AI config files, so no stale copy of the docs is left for an
+  agent to load. Pass `--docs-dir switch-docs` to keep the old name.
+- The `DetailedInfo` item in `docs/switch-appstore/app-guidelines.md` no longer reads as requiring
+  it on every property and connection. It is optional, matching what the property documentation
+  and app manual guidance already said, and points at the app manual as the surface users read.
+
+### Fixed
+
+- The secret property row in `docs/switch-project/property-editors.md` listed `password` as an
+  editor chain. It is a `Type`, and there is no such editor token, so following the row produced an
+  invalid declaration.
+- The array property row in `docs/switch-project/property-editors.md` claimed the chain always
+  returns a `string[]`, which the modal editor table contradicts. Both files now say the behaviour
+  is unverified and that code should handle a bare string too.
+
+## [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
+
+- `remove --tools <list>` removes the Switch section only from the named tools' AI config files.
+  The docs folder, the `.gitignore` entry and other tools' config stay in place. Without
+  `--tools`, or with every tool listed, `remove` still removes everything.
+
+### Fixed
+
+- `remove` now deletes the Cursor rule file and the scoped GitHub Copilot instructions file,
+  plus their folders if nothing else is in them. Before, it left both files behind containing
+  only their frontmatter. A file whose frontmatter you edited or wrote yourself is kept, with only
+  the Switch section removed.
+
+## [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
+- `init` no longer copies `.vscode/switch.code-snippets` (or removes it on `remove`) — Switch script folders already come with these snippets via `SwitchScriptTool --create`, so this package's own copy was redundant.
+- `snippets/switch.code-snippets` and `scripts/scrape_switch_docs.py` (unused internal tooling) removed from the repo.
+
+## [25.11.0-beta.7] - 2026-08-25
+
+### Added
+- README — "Using this with your coding agent" usage guide.
+
+### Fixed
+- `switch-scripting.md`'s routing table and the two hardcoded doc-list arrays in `src/init.ts` (used for Cursor's rules and the shared inline block for Codex/Windsurf/Zed/Cline) were missing `api-execution-environment.md`, `api-logging.md`, and `api-logs-and-dataroot.md` — those three docs were copied to `switch-docs/` but never referenced in 5 of the 8 tools' generated config, making them undiscoverable.
+
+## [25.11.0-beta.6] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-logs-and-dataroot.md` — locating the Application Data Root, querying `ServerLogs.db3` directly (schema, `%N` placeholder reconstruction, retention, and the debug-level logging gate) to diagnose or validate a script from its actual log output.
+
+## [25.11.0-beta.5] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-tooling.md` — `--generate-translations` command, `ScriptID` character constraint, macOS fallback binary path.
+
+### Fixed
+Corrections found by live-testing `SwitchScriptTool` (create/pack/unpack/list/verbose) against `api-tooling.md`:
+- Clarified `--transpile` is only needed for testing a script folder in Switch, not before packing — `--pack` always transpiles `main.ts` fresh and never touches an existing `main.js` in the source folder.
+- Documented that `--pack` always excludes `package.json`/`.vscode/` from the package, and strengthened the `npm prune --production` advice with the concrete reason (unpruned `devDependencies`, especially `@types/*`, get bundled for no runtime benefit).
+- Documented that `--unpack` strips `main.js`/`main.js.map` back out for a TypeScript-sourced package and prints `Type`/`Protection`/`Status` metadata.
+- Clarified `--create` scaffolds into a new `<Path>/<ScriptID>/` subfolder, not into `<Path>` directly.
+
+## [25.11.0-beta.4] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-execution-environment.md` — process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints.
+
+### Known issue
+- `docs/switch-api/api-document-classes.md` — flagged that `PdfPage.getArtBoxHeight`/`getArtBoxWidth` (and the `PdfDocument` static equivalents) currently return the crop box value instead of the art box, due to a bug on the Switch side.
+
+### Fixed
+Corrections found by auditing the docs against the actual API/runtime source:
+- `api-execution-environment.md` — corrected the concurrency model: `NumberOfSlots`/`ExecutionGroup` gate job dispatch on the Switch Server per flow-element instance (or via a cross-element named lock for `Serialized` mode); they do not map to a dedicated Node.js OS process per slot. The executor process pool is sized independently and reused across jobs/elements.
+- `api-connection.md` — `getFileCount`'s `nested` parameter is optional (defaults to `true`), not required. Tightened `getId()`'s stability description (renaming the flow is safe; renaming the flow element is not).
+- `api-job.md` — `processLater`'s `seconds` parameter is optional (defaults to `300`). `sendToChannel` throws synchronously on no-subscriber/empty args rather than failing the job. Documented that `getPrivateData`/`listDatasets`/`getDataset` throw on jobs from `getJobs()`, while `setPrivateData`/`removePrivateData` are not restricted. Documented that `getxmlData`/`getxmpData`/`getJdfData`/`getJSONData` resolve to `undefined` on error rather than throwing.
+- `api-flow-element.md` — `createPathWithName`'s `createFolder` parameter is required, not optional; corrected its return-value description (empty string only on a caught exception, not because the path already exists). `getFileCount`'s `nested` parameter is optional (defaults to `true`). Documented `failProcess`'s and `getJobs`'s throw conditions. Corrected `createJob`'s supported entry points (`jobArrived`/`timerFired` only). Documented `getPluginResourcesPath`'s local-only `.sscript` behavior and throw case.
+- `api-http.md` / `api-switch.md` — fixed the `httpRequestSubscribe` example to use a leading-slash path; documented the path-format validation and `httpRequestUnsubscribe` example.
+- `api-switch.md` — `getGlobalData` returns `''` for a missing tag, not `undefined`; documented the 100-call advisory warning. Documented `getPreferenceSetting`'s field redaction and JSON-stringify behavior, and `getServerVersion`'s `major + minor/100` numeric format.
+- `api-document-classes.md` — documented `XmlDocument.evaluate()`'s `object` return case, the `jdf` default-namespace prefix, and `ImageDocument.getICCProfile()`'s EXIF fallback.
+- `api-property-editors.md` / `api-script-declaration.md` — corrected `getPropertyType()`'s description (returns one of several `PropertyType` values, not a literal-vs-user-entered flag) and noted the XML `Type` vocabulary doesn't map one-to-one onto the runtime `PropertyType` enum.
+
+## [25.11.0-beta.3] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-logging.md` — log level semantics, logging practice, `console.log` limitation.
+- `docs/switch-api/api-property-editors.md` — "Common practices" section recommending editor chains by property kind.
+- `docs/switch-api/api-script-declaration.md` — clarified that `ApplicationPath`/`ApplicationLicense` are app-only properties set by the user via the Switch Scripter GUI after packing, not by editing the declaration file.