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

package/docs/{switch-api/api-property-editors.md → switch-project/property-editors.md}

@@ -3,18 +3,18 @@
 Property editors determine how a user enters a value in Switch Designer, and what string is
 returned by `getPropertyStringValue()` at runtime. They're set in the XML declaration via the
 `Editor` and `Type` attributes on a custom property — see
-[api-script-declaration.md](api-script-declaration.md) for the surrounding attribute grammar.
+[script-declaration.md](script-declaration.md) for the surrounding attribute grammar.
 
 All property values are returned as `string` or `string[]`. `getPropertyType()` returns one of a
 fixed set of `PropertyType` values (`literal`, `string`, `number`, `date`, `boolean`, `filepath`,
-`folderpath`, `regex`, `oauthtoken`, etc. — see [api-enums.md](api-enums.md)) describing what kind of
+`folderpath`, `regex`, `oauthtoken`, etc. — see [enums.md](../switch-api/enums.md)) describing what kind of
 value is actually present; `literal` is only one of these, not a binary "literal vs. user-entered"
 flag. Use it before interpreting the returned string, e.g. to check for a literal editor's constant
 before comparing it.
 
 `Editor` is a `;`-joined list: the inline editor's token (if any) first, then modal editor tokens in
 the order they're offered. `Type` follows from which editor(s) are chosen — see the tables below and
-[the Type reference](api-script-declaration.md#type-reference).
+[the Type reference](script-declaration.md#type-reference).
 
 ---
 
@@ -48,8 +48,8 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `regexp` | Regular expression string as entered |
 | `filetype` | Filename pattern(s) for the selected file type |
 | `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
-| `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [api-entry-points.md](api-entry-points.md#property-ui-callbacks) |
-| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [api-entry-points.md](api-entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
+| `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks) |
+| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
 | `description` | Multi-line text as a single string (may include newlines) |
 | `scriptexp` | Result of script expression evaluated in job context, as a string |
 | `sltextwithvar` | Single-line text with variables substituted, as a string |
@@ -58,7 +58,7 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
 | `filepatterns` | `string[]` — one pattern string per entry |
 | `folderpatterns` | `string[]` — one pattern string per entry |
 | `stringlist` (`Type="stringlist"`) | `string[]` — one string per line |
-| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](api-script-declaration.md#extraproperties) |
+| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](script-declaration.md#extraproperties) |
 | `external`, `external2`, … | File path to a property set edited by an external companion app |
 
 > Duplicate tokens in `Editor` are meaningless — each modal editor can only be offered once, except
@@ -157,7 +157,7 @@ offer it as the property's only editor — pair it with a module-free option (e.
 | Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
 | Enum (`Type="enum:..."`) | `inline` only, always | No editor guarantees a var/expression result matches one of the declared items. |
 | File/folder path that must exist for the app to work | `choosefile`/`choosefolder` only | Switch validates the picked path exists at flow start. |
-| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [api-flow-element.md](api-flow-element.md#properties) if the path is needed later in the flow. |
+| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [flow-element.md](../switch-api/flow-element.md#properties) if the path is needed later in the flow. |
 | Connection include-mask filter (which jobs pass through) | `allfiles;allotherfiles;types;filepatterns;regexp;scriptexp`, `Default="All Files"`, `Subtype="allfiles"` | Matches Switch's own built-in connection filter properties exactly — `Default`/`Subtype` must hold the chosen literal's exact rendered string. Folder version: `allfolders;allotherfolders;folderpatterns;regexp;scriptexp` with `Default="All Folders"`, `Subtype="allfolders"`. |
 | Connection exclude-mask filter (which jobs are blocked) | `nofiles;types;filepatterns;regexp;scriptexp`, `Default="No Files"`, `Subtype="nofiles"` | Same reasoning as the include mask, starting from `nofiles` instead since there's no "exclude all/all other" case. Folder version: `nofolders;folderpatterns;regexp;scriptexp` with `Default="No Folders"`, `Subtype="nofolders"`. |
 
@@ -171,12 +171,12 @@ dedicated row above.
 
 - **OAuth 2.0**: endpoint, client ID/secret, scope, and redirect ports are configured per-property
   in a matching `<ExtraProperties>` child element (see
-  [api-script-declaration.md § ExtraProperties](api-script-declaration.md#extraproperties)), not in
+  [script-declaration.md § ExtraProperties](script-declaration.md#extraproperties)), not in
   `Editor`/`Type`. The script receives a ready-to-use access token string via
   `getPropertyStringValue()`.
 - **External editor**: requires a separate companion application. The script receives a file path to
   the property set file. Entry point `findExternalEditorPath` resolves the editor executable path.
   One of these two must be true — either a dependent property named `Application` (see
-  [Dependency](api-script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
+  [Dependency](script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
   the script implements `findExternalEditorPath` — see
-  [api-entry-points.md](api-entry-points.md#property-ui-callbacks).
+  [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks).

package/docs/{switch-api/api-script-declaration.md → switch-project/script-declaration.md}

@@ -57,8 +57,8 @@ value is non-string (see the table); an empty string field can omit `Type`.
 | `Version` | number | Format `[1-9][0-9]*(\.(0\|[1-9][0-9]*))*`, e.g. `1`, `2.1`. Bump on every declaration change. |
 | `Keywords` | string | Space/comma/semicolon-separated. Elements pane search. |
 | `Tooltip` | string | Elements pane tooltip. |
-| `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [api-entry-points.md](api-entry-points.md#job-processing). |
-| `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs). |
+| `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [entry-points.md](../switch-api/entry-points.md#job-processing). |
+| `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs). |
 | `ConnectionType` | `Move` \| `Filter` \| `TrafficLight` | Governs which `ConnectionFields` children are legal — see [ConnectionFields](#connectionfields). |
 | `FunctionsNodeJSScript` | `;`-separated names | Entry point function names found in the script. Omit the element entirely if there is no Node.js program. |
 | `ExecutionMode` | `Concurrent` \| `Serialized` | |
@@ -108,12 +108,12 @@ Key attributes:
 |---|---|
 | `UserDefined` | Always `"true"` for custom properties. |
 | `Type` | Value type discriminator — see [Type reference](#type-reference). |
-| `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [api-property-editors.md](api-property-editors.md). |
+| `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [property-editors.md](property-editors.md). |
 | `Subtype` | Which editor in the `Editor` chain is currently active for the stored value. For a single-editor property this equals that editor's token (e.g. `"inline"`); for a bare modal editor with no inline component, leave it `""`. This attribute is read by Switch's validator at runtime, not just bookkeeping — keep it consistent with `Editor`. |
 | `LocalizedTagName` | Display name shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** 30 characters max, sentence-style capitalization (`"Customer name"`, not `"Customer Name"`). |
 | `Tooltip` | Tooltip shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** give every property a tooltip. The only exception is a property that's fully self-explanatory from its name alone with no extra constraints (e.g. "Number of copies" with no min/max) — if there's anything a user would need to know (units, valid range, format, an example value), put it in the tooltip. |
 | `DetailedInfo` | Long-form description for generated docs. Always include the attribute (empty string `""` is fine) — omitting it makes the property non-editable in Switch Designer. |
-| `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [api-entry-points.md](api-entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [api-property-editors.md § Literal editors](api-property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
+| `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [property-editors.md § Literal editors](property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
 | `Default` | Default value string. Omit only if the value is emitted as CDATA instead. **App guideline (mandatory for apps, recommended for scripts):** always provide a default unless there's genuinely no sensible one; if a default truly isn't possible, give an example value in the `Tooltip` instead. |
 | `Dependency` | Tag of the master property this one depends on. Written flat (not nested) — the dependent element is a sibling of its master, not a child. |
 | `DependencyCondition` | One of: `Not-empty`, `Equals`, `Not-equals`, `Contains`, `Does not contain`, `Matches`, `Does not match`, `Starts with`, `Does not start with`. |
@@ -134,7 +134,7 @@ Key attributes:
 **Runtime pitfall:** when a dependent property is hidden (its master's current value doesn't satisfy
 `DependencyCondition`/`Dependencyvalue`), Switch treats the tag as if it doesn't exist. Calling
 `flowElement.getPropertyStringValue(tag)` on it throws `"Invalid tag: <tag>"` — see
-[api-flow-element.md](api-flow-element.md#properties). Only fetch a dependent property once you know
+[flow-element.md](../switch-api/flow-element.md#properties). Only fetch a dependent property once you know
 its condition holds, either by checking the already-read master value yourself, or by calling
 `flowElement.hasProperty(tag)` first (it returns `false` for a hidden dependent). This matters most
 for an enum/drop-down master with several dependents keyed off different values — fetch only the
@@ -191,7 +191,7 @@ most important thing to get right when hand-editing this section:
 Custom (author-defined) connection properties may be added regardless of `ConnectionType`.
 
 The declared connections and the script's `sendTo*()` calls must agree with each other — see
-[api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) for the exact rules per
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) for the exact rules per
 `ConnectionType`. In particular, omit a `Success`/`Warning`/`Error` element entirely (as shown
 above) if the script never routes to it, rather than leaving an unused connection declared.
 
@@ -207,7 +207,7 @@ properties to reset on next package update.
 ## ExtraProperties
 
 Only used for OAuth 2.0 (`Editor` containing `oauth`, see
-[api-property-editors.md](api-property-editors.md)). One child element per OAuth property, named
+[property-editors.md](property-editors.md)). One child element per OAuth property, named
 identically to the property's tag, in `ElementFields` or `ConnectionFields`:
 
 ```xml
@@ -259,7 +259,7 @@ If no OAuth property exists on the script, omit `ExtraProperties` entirely or le
 
 This is the *authoring* vocabulary written into the XML `Type` attribute. It does not map one-to-one
 onto the runtime `PropertyType` returned by `getPropertyType()` (see
-[api-property-editors.md](api-property-editors.md) and [api-enums.md](api-enums.md)) — e.g. XML
+[property-editors.md](property-editors.md) and [enums.md](../switch-api/enums.md)) — e.g. XML
 `bool` becomes runtime `boolean`, XML `path` splits into runtime `filepath`/`folderpath`, and several
 XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `time`) have no direct
 `PropertyType` counterpart while several runtime values (`filetype`, `folderpattern`, `regex`,
@@ -267,7 +267,7 @@ XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `tim
 interchangeable.
 
 `Type` is not independently authored on properties with a modal editor chain — it follows from
-which editor(s) you choose, per [api-property-editors.md](api-property-editors.md). When combining
+which editor(s) you choose, per [property-editors.md](property-editors.md). When combining
 an inline editor with modal editors (e.g. `Editor="inline;sltextwithvar;scriptexp"`), the inline
 editor's type wins: an inline Number editor plus those modal editors still yields `Type="number"`.
 

package/docs/{switch-api/api-script-structure.md → switch-project/script-structure.md}

@@ -2,14 +2,14 @@
 
 A Switch script project lives in a **script folder** during development and is distributed as a `.sscript` package (ZIP).
 
-> **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [api-script-declaration.md](api-script-declaration.md) for the declaration's rules, and [api-entry-points.md § Entry-point scanner constraints](api-entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
+> **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [script-declaration.md](script-declaration.md) for the declaration's rules, and [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
 
 ## Script folder files
 
 | File | Required | Notes |
 |---|---|---|
 | `manifest.xml` | Yes | Switch internal use only. Do not edit manually. |
-| `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [api-script-declaration.md](api-script-declaration.md). |
+| `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [script-declaration.md](script-declaration.md). |
 | `main.ts` | Yes (TypeScript) | Source file. Edit this. |
 | `main.js` | Yes | Compiled output executed by Switch. Generated by transpiling `main.ts`. |
 | `main.js.map` | No | Source map, generated alongside `main.js`. |
@@ -105,13 +105,13 @@ testing before submission; it loads elsewhere only once Enfocus has signed it.
 ## App Store submission guidelines
 
 App-specific submission rules (localization, universal/signed macOS binaries, immutable extra
-files) live in [api-app-guidelines.md § App-only](api-app-guidelines.md#app-only), alongside the
+files) live in [app-guidelines.md § App-only](../switch-appstore/app-guidelines.md#app-only), alongside the
 rest of the pre-publish checklist.
 
 ## Execution modes
 
 `Concurrent`/`Serialized`, `ExecutionGroup` and `NumberOfSlots` are set in the XML declaration (see
-[api-script-declaration.md](api-script-declaration.md#built-in-elementfields) for the attributes)
+[script-declaration.md](script-declaration.md#built-in-elementfields) for the attributes)
 and documented in
-[api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes),
+[execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes),
 which also explains why none of them maps to a count of Node.js processes.

package/docs/{switch-api/api-tooling.md → switch-project/tooling.md}

@@ -44,7 +44,7 @@ location for the current OS if the bare command isn't found.
 
 Switch's entry-point scanner is regex-based, not a real parser, and can silently drop entry-point
 functions from certain string/regex/division shapes — see
-[api-entry-points.md § Entry-point scanner constraints](api-entry-points.md#entry-point-scanner-constraints).
+[entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints).
 `--pack` does not validate or warn about this: a script that packs cleanly can still fail to load,
 or load with a property callback that silently never runs. Compiling and passing tests doesn't
 catch it either, since the source is syntactically valid JS/TS — only extraction against the built

package/docs/switch-scripting.md

@@ -7,41 +7,51 @@ 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 API docs are in `docs/switch-api/`:
+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).
 
 | File | Contents | Load when |
 |---|---|---|
-| `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
-| `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
-| `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
-| `switch-api/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/api-connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
-| `switch-api/api-http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
-| `switch-api/api-enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
-| `switch-api/api-document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
-| `switch-api/api-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-api/api-tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
-| `switch-api/api-debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
-| `switch-api/api-vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
-| `switch-api/api-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-api/api-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/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 `api-job.md` when you also need signatures |
-| `switch-api/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 |
-| `switch-api/api-logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
-| `switch-api/api-logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
-| `switch-api/api-app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
+| `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/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/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
+| `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
+| `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
+| `switch-project/script-structure.md` | What files a script folder contains, `manifest.xml` format, 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/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 |
+| `switch-api/logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
+| `switch-project/logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
+| `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) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
+| `switch-project/property-documentation.md` | Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections | Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo` |
+| `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 |
 
 ## 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.
 - 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
   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 every entry point inside that span
-  disappears with no error anywhere. Read `switch-api/api-entry-points.md` §
+  disappears with no error anywhere. Read `switch-api/entry-points.md` §
   Entry-point scanner constraints before editing `main.ts`/`main.js`.
 - Every `jobArrived` invocation must end with exactly one `job.sendTo*()` or `job.fail()` call — either in the same invocation or deferred to `timerFired` via job information stored in global data.
 - Use `AccessLevel.ReadOnly` for `job.get()` unless the file content will be modified.
 - Use VS Code snippets (`.vscode/switch.code-snippets`, prefix `switch…`) to scaffold entry points.
 - After calling `createJob()`, `createChild()`, or `createDataset()` with a file path, the script must delete the source file/folder after routing — Switch does not auto-remove it.
-- The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-api/api-script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.
+- The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-project/script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.

package/package.json

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