@enfocussw/switch-scripting-context 25.11.0-beta.15 → 25.11.0-beta.17

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this package are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [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
@@ -18,6 +42,9 @@ All notable changes to this package are documented here. Format follows
   `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

package/README.md

@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
 
 Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.15/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.17/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -84,7 +84,7 @@ A few things this gets you without asking for them by name:
   properties (app path/licence) are off-limits and left to SwitchScripter's GUI instead.
 
 Re-run `init` after upgrading this package so the copied docs and generated config files catch up.
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.15/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.17/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -131,27 +131,29 @@ 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-project/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/entry-points.md`: all entry point signatures and when each is called
-- `switch-api/job.md`: `Job` class signatures for routing, file access, child jobs, private data, datasets
+<!-- 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/switch.md`: `Switch` global: global data, webhooks, abort, server utilities
+- `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` and webhook pattern
-- `switch-api/enums.md`: all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
-- `switch-api/document-classes.md`: `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
-- `switch-project/script-declaration.md`: XML declaration reference
-- `switch-project/script-structure.md`: script folder contents, manifest format, Node.js version per Switch release, Script vs App
-- `switch-project/tooling.md`: SwitchScriptTool commands, script folder vs package, build and deployment
-- `switch-project/debugging.md`: enabling debug mode, debuggable entry points, VS Code attach
-- `switch-api/logging.md`: log levels, when/what to log, `console.log` limitation, common gotchas
-- `switch-project/logs-and-dataroot.md`: locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
-- `switch-project/vscode.md`: type declarations, tsconfig for TypeScript 6, ESLint rules
-- `switch-project/property-editors.md`: property editor types and string return values
-- `switch-api/job-patterns.md`: `Job` rules and gotchas covering file access semantics, temp cleanup, routing rules, child jobs, executor limits
-- `switch-api/execution-environment.md`: execution modes, process model, state persistence across jobs, error handling, npm/native module constraints
-- `switch-appstore/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
-- `switch-project/property-documentation.md`: writing guidance for `Tooltip` and `DetailedInfo` content on properties and connections
-- `switch-appstore/app-store-listing.md`: writing guidance for the 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
-- `switch-appstore/app-store-submission.md`: writing guidance for the Appstore website submission forms (Short Description, What's new, Eula, icon specs)
+- `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, Node.js version per Switch release, 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
+<!-- docs-index:readme end -->

package/docs/switch-api/connection.md

@@ -1,3 +1,12 @@
+---
+id: connection
+category: switch-api
+order: 6
+summary: "`Connection`: type, properties, file count"
+triggers:
+  - "Routing to specific connections or reading connection properties"
+---
+
 # Connection Class
 
 A `Connection` represents an outgoing connection from the flow element. Obtain instances via `flowElement.getOutConnections()`.
@@ -28,6 +37,8 @@ connection.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
 Returns the connection property value as a string. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [script-declaration.md § Dependency](../switch-project/script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally.
 
+This is **not** how to check which traffic light level(s) a connection accepts before calling `job.sendToData()` — `"Success"`/`"Warning"`/`"Error"` are not property tags, so passing one throws the same invalid-tag error. There is no supported way to check in advance; see [Connection.Level enum](#connectionlevel-enum) below.
+
 ```ts
 connection.getPropertyType(tag: string): PropertyType
 ```
@@ -52,7 +63,7 @@ Returns the number of files in the folder at the other end of this connection. I
 
 ## Connection.Level enum
 
-Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections.
+Used with `job.sendToData()` and `job.sendToLog()` to select which traffic light connection a job routes to.
 
 | Value | String |
 |---|---|
@@ -61,3 +72,9 @@ Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections
 | `Connection.Level.Error` | `"error"` |
 
 Available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+
+**Traffic light levels are not a readable connection property.** `flowElement.getOutConnections()`
+returns the outgoing `Connection` objects, but the supported API has no way to determine which
+level(s) a given connection accepts. Don't call `connection.getPropertyStringValue("Success")`, `"Warning"`, or `"Error"` expecting to
+read this back; those are not valid property tags for a traffic light connection. To route
+optionally, see [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs).

package/docs/switch-api/document-classes.md

@@ -1,3 +1,12 @@
+---
+id: document-classes
+category: switch-api
+order: 9
+summary: "`PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection"
+triggers:
+  - "Inspecting PDF, image, XML, or XMP file contents"
+---
+
 # Document Classes
 
 Read-only document introspection utilities. All methods may throw — wrap in `try/catch`. Load this file when working with PDF, image, XML, or XMP documents.

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

@@ -1,3 +1,12 @@
+---
+id: entry-points
+category: switch-api
+order: 2
+summary: "All entry point signatures, constraints, and when each is called"
+triggers:
+  - "Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js"
+---
+
 # Switch Script Entry Points
 
 Entry points are top-level `async` functions with specific names. They are **not exported**. Switch calls them automatically based on flow events.

package/docs/switch-api/enums.md

@@ -1,3 +1,12 @@
+---
+id: enums
+category: switch-api
+order: 8
+summary: "All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)"
+triggers:
+  - "Looking up enum values"
+---
+
 # Switch Scripting Enums
 
 All enums are available globally in `main.ts`. They are also accessible via `EnfocusSwitch.*` when used outside `main.ts` (e.g. in imported modules).
@@ -68,7 +77,9 @@ Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections
 | `Connection.Level.Warning` | `"warning"` |
 | `Connection.Level.Error` | `"error"` |
 
-Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`. It selects which level to
+route to; it is not a property you can read back from a `Connection` object, see
+[connection.md § Connection.Level enum](connection.md#connectionlevel-enum).
 
 ## HttpRequest.Method
 

package/docs/switch-api/execution-environment.md

@@ -1,3 +1,12 @@
+---
+id: execution-environment
+category: switch-api
+order: 17
+summary: "Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints"
+triggers:
+  - "Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages"
+---
+
 # Execution Environment
 
 How the Node.js process a script runs in behaves, beyond the entry point API itself. Apart from the

package/docs/switch-api/flow-element.md

@@ -1,3 +1,12 @@
+---
+id: flow-element
+category: switch-api
+order: 4
+summary: "`FlowElement`: properties, connections, job creation, logging"
+triggers:
+  - "Reading properties, creating jobs, logging, connections"
+---
+
 # FlowElement Class
 
 The `FlowElement` instance `flowElement` is passed to every entry point that operates on a flow element. It provides access to properties, connections, job creation, and logging.

package/docs/switch-api/http.md

@@ -1,3 +1,12 @@
+---
+id: http
+category: switch-api
+order: 7
+summary: "`HttpRequest` / `HttpResponse` + webhook pattern"
+triggers:
+  - "Handling incoming HTTP webhooks"
+---
+
 # HttpRequest & HttpResponse Classes
 
 Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`.

package/docs/switch-api/job-patterns.md

@@ -1,3 +1,12 @@
+---
+id: job-patterns
+category: switch-api
+order: 16
+summary: "`Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits"
+triggers:
+  - "Writing or reviewing job-handling code. Pair with `job.md` when you also need signatures"
+---
+
 # Job Patterns and Behavioral Rules
 
 Common behavioral rules for file access, routing, temp file cleanup, and child jobs. These are the most frequent sources of bugs.
@@ -82,6 +91,12 @@ await fs.promises.rm(tempPath);
   Conversely, don't declare a Success/Warning/Error element the script never routes to — omit it from
   `ConnectionFields` entirely (see the TrafficLight example in
   [script-declaration.md](../switch-project/script-declaration.md#connectionfields)).
+  `sendToData(level)` fails the job if no connected outgoing data connection accepts that level,
+  and there is no supported way to check in advance which levels are wired up (see
+  [connection.md § Connection.Level enum](connection.md#connectionlevel-enum)). If routing at a
+  given level is optional rather than guaranteed by the flow design, expose an explicit custom
+  property that lets the flow author opt in or out, and call `job.sendToNull()` when opted out
+  instead of guessing whether `sendToData()` will succeed.
 - Prefer `job.fail()`/`flowElement.failProcess()` for genuine processing errors (see
   [logging.md](logging.md)) over silently routing a failed job to a generic error connection —
   reserve an error `TrafficLight` connection for cases the flow author should be able to reroute

package/docs/switch-api/job.md

@@ -1,3 +1,12 @@
+---
+id: job
+category: switch-api
+order: 5
+summary: "`Job` **signatures**: routing, file access, child jobs, private data, datasets"
+triggers:
+  - "Looking up what a `job.*` method takes, returns, or throws"
+---
+
 # Job Class
 
 A `Job` represents a file or folder moving through the flow. It is passed to `jobArrived` and can be created via `flowElement.createJob()` or `job.createChild()`. Every job must be routed with a `sendTo*()` call or `fail()` before the entry point ends (or at a later time via `timerFired`).
@@ -56,7 +65,7 @@ Send to a specific connection (any type). Get connections via `flowElement.getOu
 ```ts
 job.sendToData(level: Connection.Level, newName?: string): Promise<void>
 ```
-Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists.
+Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists. **There is no supported way to check in advance whether a connection at that level exists** — don't call `connection.getPropertyStringValue("Success")`/`"Warning"`/`"Error"` expecting to detect this; that throws an invalid-tag error, since traffic light levels aren't a readable connection property. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for the pattern (an explicit custom property plus `job.sendToNull()`).
 
 ```ts
 job.sendToLog(level: Connection.Level, model: DatasetModel, newName?: string): Promise<void>

package/docs/switch-api/logging.md

@@ -1,3 +1,12 @@
+---
+id: logging
+category: switch-api
+order: 18
+summary: "Log level semantics, logging practice, `console.log` limitation, common gotchas"
+triggers:
+  - "Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls"
+---
+
 # Logging Practices
 
 Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElement.failProcess()`

package/docs/switch-api/switch.md

@@ -1,3 +1,12 @@
+---
+id: switch
+category: switch-api
+order: 3
+summary: "`Switch` (`s`): global data, webhooks, abort, server utilities"
+triggers:
+  - "Using global data, webhooks, abort, or server settings"
+---
+
 # Switch Class
 
 The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.

package/docs/switch-appstore/app-guidelines.md

@@ -1,3 +1,12 @@
+---
+id: app-guidelines
+category: switch-appstore
+order: 20
+summary: "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)"
+triggers:
+  - "Preparing a script for publication as an app, or reviewing one against Appstore submission criteria"
+---
+
 # App Publishing Guidelines
 
 A pre-publish checklist for a script intended for the Enfocus Appstore (`ScriptPackageType="App"`

package/docs/switch-appstore/app-manual.md

@@ -1,3 +1,12 @@
+---
+id: app-manual
+category: switch-appstore
+order: 23
+summary: "Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template)"
+triggers:
+  - "Preparing the app manual document for Appstore submission"
+---
+
 # Writing the App Manual
 
 Guidance for the separate Word/PDF document an app creator uploads during Appstore review,

package/docs/switch-appstore/app-store-listing.md

@@ -1,3 +1,12 @@
+---
+id: app-store-listing
+category: switch-appstore
+order: 22
+summary: "Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`"
+triggers:
+  - "Writing or reviewing the app's Appstore listing text"
+---
+
 # Writing the Appstore Listing Fields
 
 Guidance for the *content* of the declaration's prose fields that appear on the app's Enfocus

package/docs/switch-appstore/app-store-submission.md

@@ -1,3 +1,12 @@
+---
+id: app-store-submission
+category: switch-appstore
+order: 24
+summary: "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"
+triggers:
+  - "Preparing content for the Appstore website submission forms"
+---
+
 # Writing the Appstore Submission Forms
 
 Guidance for the two web forms on the Enfocus Appstore site: **Create Appstore App** (once per

package/docs/switch-project/debugging.md

@@ -1,3 +1,12 @@
+---
+id: debugging
+category: switch-project
+order: 12
+summary: "Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach"
+triggers:
+  - "Debugging a script"
+---
+
 # Debugging Scripts
 
 Debugging requires configuring the Script element in Switch Designer — the agent cannot do this directly but can guide the user through the steps.

package/docs/switch-project/logs-and-dataroot.md

@@ -1,3 +1,12 @@
+---
+id: logs-and-dataroot
+category: switch-project
+order: 19
+summary: "Locating the Application Data Root, querying `ServerLogs.db3` directly"
+triggers:
+  - "Diagnosing or validating a script from its actual log output rather than by reading the code"
+---
+
 # Locating and Querying Switch's Log Database
 
 For diagnosing or validating a script from the outside — reading what the user themselves would see

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

@@ -1,3 +1,12 @@
+---
+id: project-planning
+category: switch-project
+order: 1
+summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+triggers:
+  - "Starting a new script or app, before scaffolding any files"
+---
+
 # Project Planning
 
 A pre-scaffolding checklist for a new script or app. Work through this with the user before

package/docs/switch-project/property-documentation.md

@@ -1,3 +1,12 @@
+---
+id: property-documentation
+category: switch-project
+order: 21
+summary: "Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections"
+triggers:
+  - "Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo`"
+---
+
 # Writing Property and Connection Documentation
 
 Guidance for the *content* of `Tooltip` and `DetailedInfo` on properties and connections — see

package/docs/switch-project/property-editors.md

@@ -1,3 +1,12 @@
+---
+id: property-editors
+category: switch-project
+order: 15
+summary: "Property editor types, string return values, literal editors, dropdowns"
+triggers:
+  - "Defining property editors in XML or reading property values in code"
+---
+
 # Property Editors
 
 Property editors determine how a user enters a value in Switch Designer, and what string is

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

@@ -1,3 +1,12 @@
+---
+id: script-declaration
+category: switch-project
+order: 14
+summary: "XML declaration reference: properties, connections, execution config; agents may edit this file directly"
+triggers:
+  - "Understanding, adding, or editing script properties/connections/execution config"
+---
+
 # Script Declaration (XML)
 
 The file `<ScriptID>.xml` defines the script's metadata, custom properties, connection properties,

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

@@ -1,3 +1,12 @@
+---
+id: script-structure
+category: switch-project
+order: 10
+summary: "What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App"
+triggers:
+  - "Setting up a new script project, or converting a Script to an App"
+---
+
 # Script Project Structure
 
 A Switch script project lives in a **script folder** during development and is distributed as a `.sscript` package (ZIP).

package/docs/switch-project/tooling.md

@@ -1,3 +1,12 @@
+---
+id: tooling
+category: switch-project
+order: 11
+summary: "SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment"
+triggers:
+  - "Running SwitchScriptTool: transpiling, packing, unpacking, or deploying"
+---
+
 # Script Folders, Packages & SwitchScriptTool
 
 ## Script folder vs script package

package/docs/switch-project/vscode.md

@@ -1,3 +1,12 @@
+---
+id: vscode
+category: switch-project
+order: 13
+summary: "Type declarations, tsconfig for TypeScript 6, ESLint rules"
+triggers:
+  - "Setting up VS Code or fixing type errors"
+---
+
 # VS Code Setup
 
 ## Type declarations

package/docs/switch-scripting.md

@@ -7,25 +7,27 @@ Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
 - Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely.
 
 ## API reference
-Detailed docs live in three folders: `docs/switch-api/` (the scripting API itself), `docs/switch-project/`
-(script/app project structure and tooling), and `docs/switch-appstore/` (Appstore publishing guidance).
+Detailed docs live in three folders, alongside this file: `switch-api/` (the scripting API itself),
+`switch-project/` (script/app project structure and tooling), and `switch-appstore/` (Appstore
+publishing guidance).
 
 | File | Contents | Load when |
 |---|---|---|
+<!-- docs-index:table 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 | Starting a new script or app, before scaffolding any files |
 | `switch-api/entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
-| `switch-api/switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
-| `switch-api/flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
+| `switch-api/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
+| `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
 | `switch-api/job.md` | `Job` **signatures**: routing, file access, child jobs, private data, datasets | Looking up what a `job.*` method takes, returns, or throws |
-| `switch-api/connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
+| `switch-api/connection.md` | `Connection`: type, properties, file count | Routing to specific connections or reading connection properties |
 | `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
 | `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
-| `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
+| `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
 | `switch-project/script-structure.md` | What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App | Setting up a new script project, or converting a Script to an App |
 | `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
 | `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
 | `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
-| `switch-project/script-declaration.md` | XML declaration reference: properties, connections, execution config — agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
+| `switch-project/script-declaration.md` | XML declaration reference: properties, connections, execution config; agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
 | `switch-project/property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
 | `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 | Writing or reviewing job-handling code. Pair with `job.md` when you also need signatures |
 | `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 | Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
@@ -36,13 +38,14 @@ Detailed docs live in three folders: `docs/switch-api/` (the scripting API itsel
 | `switch-appstore/app-store-listing.md` | Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections` | Writing or reviewing the app's Appstore listing text |
 | `switch-appstore/app-manual.md` | Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template) | Preparing the app manual document for Appstore submission |
 | `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 | Preparing content for the Appstore website submission forms |
+<!-- docs-index:table end -->
 
 ## Key rules
 - Before scaffolding a new script or app, work through `switch-project/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/`,
-  `docs/switch-project/`, and `docs/switch-appstore/` for `known issue`, `gotcha`, `quirk`, `caveat`
-  (case-insensitive) — every documented pitfall uses one of these four terms.
+- To find documented behavioural pitfalls before writing code in an area, grep the `switch-api/`,
+  `switch-project/`, and `switch-appstore/` folders alongside this file 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.15",
+  "version": "25.11.0-beta.17",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",
@@ -33,11 +33,12 @@
   "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 && node scripts/check-prose.js && node scripts/check-gotcha-tags.js",
+    "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js && node scripts/generate-docs-index.js --check",
     "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"
+    "lint:gotchas": "node scripts/check-gotcha-tags.js",
+    "docs:generate": "node scripts/generate-docs-index.js"
   },
   "author": "Sam Wallace",
   "license": "ISC",