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

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [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

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.14/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.16/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.14/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.0-beta.16/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -131,23 +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-api/api-project-planning.md`: pre-scaffolding checklist covering Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
-- `switch-api/api-entry-points.md`: all entry point signatures and when each is called
-- `switch-api/api-job.md`: `Job` class signatures for routing, file access, child jobs, private data, datasets
-- `switch-api/api-flow-element.md`: `FlowElement`: properties, connections, job creation, logging
-- `switch-api/api-switch.md`: `Switch` global: global data, webhooks, abort, server utilities
-- `switch-api/api-connection.md`: `Connection`: type, properties, file count
-- `switch-api/api-http.md`: `HttpRequest` / `HttpResponse` and webhook pattern
-- `switch-api/api-enums.md`: all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
-- `switch-api/api-document-classes.md`: `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
-- `switch-api/api-script-declaration.md`: XML declaration reference
-- `switch-api/api-script-structure.md`: script folder contents, manifest format, Node.js version per Switch release, Script vs App
-- `switch-api/api-tooling.md`: SwitchScriptTool commands, script folder vs package, build and deployment
-- `switch-api/api-debugging.md`: enabling debug mode, debuggable entry points, VS Code attach
-- `switch-api/api-logging.md`: log levels, when/what to log, `console.log` limitation, common gotchas
-- `switch-api/api-logs-and-dataroot.md`: locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
-- `switch-api/api-vscode.md`: type declarations, tsconfig for TypeScript 6, ESLint rules
-- `switch-api/api-property-editors.md`: property editor types and string return values
-- `switch-api/api-job-patterns.md`: `Job` rules and gotchas covering file access semantics, temp cleanup, routing rules, child jobs, executor limits
-- `switch-api/api-execution-environment.md`: execution modes, process model, state persistence across jobs, error handling, npm/native module constraints
-- `switch-api/api-app-guidelines.md`: pre-publish checklist for Appstore apps covering property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, app-only submission rules
+<!-- docs-index:readme begin -->
+- `switch-project/project-planning.md`: Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `switch-api/entry-points.md`: All entry point signatures, constraints, and when each is called
+- `switch-api/switch.md`: `Switch` (`s`): global data, webhooks, abort, server utilities
+- `switch-api/flow-element.md`: `FlowElement`: properties, connections, job creation, logging
+- `switch-api/job.md`: `Job` **signatures**: routing, file access, child jobs, private data, datasets
+- `switch-api/connection.md`: `Connection`: type, properties, file count
+- `switch-api/http.md`: `HttpRequest` / `HttpResponse` + webhook pattern
+- `switch-api/enums.md`: All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)
+- `switch-api/document-classes.md`: `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection
+- `switch-project/script-structure.md`: What files a script folder contains, `manifest.xml` format, 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/dist/init.d.ts

@@ -10,7 +10,7 @@ export interface ToolDefinition {
     files: ToolFile[];
 }
 export interface ApiDoc {
-    /** Filename within docs/switch-api/, e.g. "api-job.md". */
+    /** Path within docs/, e.g. "switch-api/job.md". */
     file: string;
     /** The routing table's "Load when" text, verbatim. */
     loadWhen: string;

package/dist/init.js

@@ -64,10 +64,10 @@ function parseRoutingTable(root = packageRoot()) {
     const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
     const docs = [];
     for (const line of hub.split('\n')) {
-        // | `switch-api/<file>.md` | <contents> | <load when> |
-        const m = /^\|\s*`switch-api\/(api-[a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
+        // | `<switch-api|switch-project|switch-appstore>/<file>.md` | <contents> | <load when> |
+        const m = /^\|\s*`(switch-api|switch-project|switch-appstore)\/([a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
         if (m)
-            docs.push({ file: m[1], loadWhen: m[3].trim() });
+            docs.push({ file: `${m[1]}/${m[2]}`, loadWhen: m[4].trim() });
     }
     if (docs.length === 0) {
         throw new Error('No API docs found in docs/switch-scripting.md — the routing table format changed. ' +
@@ -82,11 +82,11 @@ function apiFiles(root) {
 const INLINE_CORE_RULES = `## Core rules
 
 - Entry point functions are top-level async functions — do NOT use \`export\`, arrow functions, or class methods; declare them with the literal \`function\` keyword.
-- Switch finds entry points with a regex, not a parser. Never write a string literal whose content ends with a backslash, a regex literal, or division outside the plain \`word / word\` shape — each silently deletes a span of real code and the entry points inside it, with no error. Read \`api-entry-points.md\` § Entry-point scanner constraints before editing \`main.ts\`/\`main.js\`.
+- Switch finds entry points with a regex, not a parser. Never write a string literal whose content ends with a backslash, a regex literal, or division outside the plain \`word / word\` shape — each silently deletes a span of real code and the entry points inside it, with no error. Read \`entry-points.md\` § Entry-point scanner constraints before editing \`main.ts\`/\`main.js\`.
 - Every \`jobArrived\` must end with exactly one \`job.sendTo*()\` or \`job.fail()\`.
 - Use \`AccessLevel.ReadOnly\` for \`job.get()\` unless the file content will be modified.
 - After \`createJob()\`, \`createChild()\`, or \`createDataset()\` with a file path, delete the source file after routing — Switch does not auto-remove it.
-- The XML declaration (\`<ScriptID>.xml\`) can be edited directly — read \`api-script-declaration.md\` first and follow its rules exactly (nothing validates this format, so mistakes fail silently). Never change an existing script's \`Name\`; bump \`Version\` on every declaration edit. Leave \`manifest.xml\` to the user unless explicitly asked.
+- The XML declaration (\`<ScriptID>.xml\`) can be edited directly — read \`script-declaration.md\` first and follow its rules exactly (nothing validates this format, so mistakes fail silently). Never change an existing script's \`Name\`; bump \`Version\` on every declaration edit. Leave \`manifest.xml\` to the user unless explicitly asked.
 - After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
 - Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
 // ─── Content generators ──────────────────────────────────────────────────────
@@ -140,7 +140,7 @@ ${MARKER_END}`;
 // ─── Inline block (for tools without @file import support) ──────────────────
 function inlineApiFileList(docsDir) {
     return parseRoutingTable()
-        .map(d => `- \`${docsDir}/switch-api/${d.file}\` — ${d.loadWhen}`)
+        .map(d => `- \`${docsDir}/${d.file}\` — ${d.loadWhen}`)
         .join('\n');
 }
 function generateInlineBlock(docsDir) {
@@ -337,10 +337,21 @@ function applyFileAction(action, dryRun) {
 const DOCS_EXCLUDE = ['superpowers', 'temp'];
 function copyDocs(packageRoot, destDir, dryRun) {
     const src = path.join(packageRoot, 'docs');
+    const rel = path.relative(process.cwd(), destDir);
     if (dryRun) {
-        console.log(`  [dry-run] Copying docs/ → ${path.relative(process.cwd(), destDir)}/`);
+        if (fs.existsSync(destDir)) {
+            console.log(`  [dry-run] ${rel}/ → wiped (removes files from a previous version, e.g. after a doc was renamed or moved)`);
+        }
+        console.log(`  [dry-run] Copying docs/ → ${rel}/`);
         return;
     }
+    // destDir is entirely owned by this tool (see the .gitignore comment it writes), so wiping
+    // it first is safe. Without this, a doc renamed or moved between versions (e.g. a docs/
+    // folder restructuring) would leave the old file behind forever: cpSync only adds/overwrites,
+    // it never removes, and destDir is gitignored so nothing would surface the staleness.
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
     // The published tarball already omits these, but init may run from a git clone.
     fs.cpSync(src, destDir, {
         recursive: true,

package/docs/switch-api/{api-connection.md → 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()`.
@@ -21,12 +30,12 @@ Connection type. One of: `"Move"`, `"Filter"`, `"Traffic-data"`, `"Traffic-log"`
 
 ## Connection properties
 
-Connection properties are declared in the script's XML declaration (`ConnectionFields`) and configured per-connection in the canvas. See [api-script-declaration.md](api-script-declaration.md) for how to declare them (via SwitchScripter).
+Connection properties are declared in the script's XML declaration (`ConnectionFields`) and configured per-connection in the canvas. See [script-declaration.md](../switch-project/script-declaration.md) for how to declare them (via SwitchScripter).
 
 ```ts
 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 [api-script-declaration.md § Dependency](api-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.
+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.
 
 ```ts
 connection.getPropertyType(tag: string): PropertyType
@@ -52,7 +61,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 +70,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/{api-document-classes.md → 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.
@@ -121,7 +130,7 @@ img.getSamplesPerPixel(): number
 ImageDocument.getSamplesPerPixel(path: string): Promise<number>
 ```
 
-See [api-enums.md](api-enums.md) for `ImageDocument.ColorMode` and `ImageDocument.ColorSpace` values.
+See [enums.md](enums.md) for `ImageDocument.ColorMode` and `ImageDocument.ColorSpace` values.
 
 ---
 

package/docs/switch-api/{api-entry-points.md → 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.
@@ -47,7 +56,7 @@ or warn about any of this — a script that packs cleanly can still fail to load
    extraction — if another valid entry point is also present the script packs and loads without
    error, the misnamed function just never runs.
 
-See [api-tooling.md § Verify entry points before packing](api-tooling.md#verify-entry-points-before-packing)
+See [tooling.md § Verify entry points before packing](../switch-project/tooling.md#verify-entry-points-before-packing)
 for a script to catch this before it reaches Switch.
 
 ## Flow lifecycle
@@ -83,7 +92,7 @@ Called when a job arrives. Must eventually call a `job.sendTo*()` or `job.fail()
 `jobArrived` and `timerFired` presence must match the declared connections — present when
 `IncomingConnections="Yes"` (`timerFired` may additionally be present); when
 `IncomingConnections="No"`, `timerFired` must be present instead. See
-[api-script-declaration.md](api-script-declaration.md#built-in-elementfields). Never leave an empty
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields). Never leave an empty
 `jobArrived` or `timerFired` in the script — remove the function entirely if it does nothing.
 
 **Gotcha: a flow restart replays every queued job through `jobArrived` again.** This includes a job
@@ -129,7 +138,7 @@ async function getLibraryForProperty(s: Switch, flowElement: FlowElement, tag: s
 ```
 Returns a dynamic list of values for a property's library dropdown. Mandatory if any property uses
 the `askplugin`/`askplugin2` editor (see
-[api-property-editors.md](api-property-editors.md#modal-editors)). Log an error via `flowElement.log()`
+[property-editors.md](../switch-project/property-editors.md#modal-editors)). Log an error via `flowElement.log()`
 if the list would otherwise come back empty, so the user can see why the dropdown has nothing in it.
 
 ```ts
@@ -143,7 +152,7 @@ async function validateProperties(s: Switch, flowElement: FlowElement, tags: str
 ```
 Validates one or more property values. Return one result object per tag. Mandatory if any property
 declares `Validation="Custom"` or `"Standard and custom"` (see
-[api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields)). Log
+[script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields)). Log
 an error via `flowElement.log()` for any tag returned with `valid: false`, so the user sees why.
 
 ```ts
@@ -157,4 +166,4 @@ async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag:
 ```
 Resolves the path to an external editor for a property. Required whenever the
 `external`/`external2`/… editor is used, unless the dependent `Application` property is non-empty —
-see [api-property-editors.md § Notes](api-property-editors.md#notes).
+see [property-editors.md § Notes](../switch-project/property-editors.md#notes).

package/docs/switch-api/{api-enums.md → 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/{api-execution-environment.md → 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
@@ -7,7 +16,7 @@ configures — understanding them avoids subtle bugs around state persistence an
 ## Execution modes
 
 Set in the XML declaration via SwitchScripter, or by editing it directly (see
-[api-script-declaration.md](api-script-declaration.md#built-in-elementfields)). Applies to all
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields)). Applies to all
 instances of the script.
 
 **Concurrent** — entry points for the same or different instances may run in parallel. Scripts must
@@ -39,7 +48,7 @@ them:
   whichever pooled executor is free (or a new one is spawned if none are); executors are reused
   across many jobs and across different flow elements running the same Node.js version, until
   recycled (see
-  [Executor cleanup thresholds](api-job-patterns.md#executor-cleanup-thresholds)).
+  [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
 
 ## Module-level state persists across jobs on the same executor
 
@@ -62,15 +71,15 @@ underlying executor process is **not** killed and continues serving subsequent j
 including for other flow elements pooled onto the same executor. Don't rely on an unhandled
 rejection to surface as a hard failure of the whole executor; always catch and handle errors
 explicitly (e.g. via `job.fail()`/`flowElement.failProcess()` — see
-[api-logging.md](api-logging.md)) rather than letting a promise reject unhandled.
+[logging.md](logging.md)) rather than letting a promise reject unhandled.
 
 ## Third-party npm modules: file-based scripts only
 
 A script **expression** (entered inline in a flow element property, not a file-based script/app —
-see [Script expression](api-entry-points.md#script-expression)) cannot use third-party npm modules
+see [Script expression](entry-points.md#script-expression)) cannot use third-party npm modules
 at all; only Node.js built-ins are available via `require`. A file-based script/app can use
 third-party modules from its own `node_modules` folder (see
-[Script folder files](api-script-structure.md#script-folder-files)).
+[Script folder files](../switch-project/script-structure.md#script-folder-files)).
 
 ## Native (binary) addons are not supported
 
@@ -80,7 +89,7 @@ native/binary Node addons (`.node` files). Stick to pure-JavaScript/TypeScript d
 ## No explicit CPU or memory cap beyond the documented thresholds
 
 Beyond the entry-point abort timeout and executor recycling thresholds already documented (see
-[Job processing](api-entry-points.md#job-processing) and
-[Executor cleanup thresholds](api-job-patterns.md#executor-cleanup-thresholds)), there is no
+[Job processing](entry-points.md#job-processing) and
+[Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)), there is no
 additional CPU-time or memory limit enforced on a script's own code. A runaway loop or leak is
 bounded only by those thresholds, not stopped proactively.

package/docs/switch-api/{api-flow-element.md → 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.
@@ -21,7 +30,7 @@ Properties are configured by the user in the Switch canvas and declared in the s
 ```ts
 flowElement.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
-Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [api-script-declaration.md § Dependency](api-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. See [api-property-editors.md](api-property-editors.md) for editor types and their return value formats.
+Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. 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. See [property-editors.md](../switch-project/property-editors.md) for editor types and their return value formats.
 
 > **Dynamic values (Switch variables and script expressions) are only resolved when `getPropertyStringValue()` is called from `jobArrived`.** In any other entry point (e.g. `timerFired`) the raw unresolved string is returned.
 >
@@ -58,7 +67,7 @@ Sets the interval between `timerFired` invocations. Default is 300 s. The actual
 
 ## Logging
 
-See [api-logging.md](api-logging.md) for log level semantics and logging practice.
+See [logging.md](logging.md) for log level semantics and logging practice.
 
 ```ts
 flowElement.log(level: LogLevel, message: string, messageParams?: (string | number | boolean)[]): Promise<void>
@@ -75,7 +84,7 @@ Logs a fatal error and puts the element into the "problem process" state. `messa
 ```ts
 flowElement.createJob(path: string): Promise<Job>
 ```
-Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [api-job-patterns.md](api-job-patterns.md#sending-jobs) for routing constraints.
+Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [job-patterns.md](job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [job-patterns.md](job-patterns.md#sending-jobs) for routing constraints.
 
 ```ts
 flowElement.getJobs(ids: string[]): Promise<Job[]>
@@ -94,7 +103,7 @@ Subscribes to a channel to receive jobs from it. Only one subscriber per channel
 ```ts
 flowElement.createPathWithName(name: string, createFolder: boolean): Promise<any>
 ```
-Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first. This is the recommended way to create temp files — see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup) for cleanup rules, including why this method should be preferred over ad hoc temp-file approaches like the `tmp` npm package.
+Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first. This is the recommended way to create temp files — see [job-patterns.md](job-patterns.md#temp-file-cleanup) for cleanup rules, including why this method should be preferred over ad hoc temp-file approaches like the `tmp` npm package.
 
 ```ts
 flowElement.getFileCount(nested?: boolean): Promise<number>

package/docs/switch-api/{api-http.md → 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/{api-job-patterns.md → 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.
@@ -73,7 +82,7 @@ await fs.promises.rm(tempPath);
 - If `OutgoingConnections="Unlimited"` (more than one outgoing connection allowed), never use
   `job.sendToSingle()` — it only makes sense when exactly one outgoing connection exists.
 - If no output is produced for a job, call `job.sendToNull()` rather than leaving it unrouted.
-- `ConnectionType="Move"` (see [api-script-declaration.md](api-script-declaration.md#connectionfields)):
+- `ConnectionType="Move"` (see [script-declaration.md](../switch-project/script-declaration.md#connectionfields)):
   never use `job.sendToData()`/`job.sendToLog()` — those are for `TrafficLight` connections only. Use
   `job.sendTo()`/`job.sendToSingle()`.
 - `ConnectionType="TrafficLight"`: use only `job.sendToData()`/`job.sendToLog()` — never
@@ -81,9 +90,15 @@ await fs.promises.rm(tempPath);
   is enabled in the declaration, and `sendToLog` when the corresponding Log connection is enabled.
   Conversely, don't declare a Success/Warning/Error element the script never routes to — omit it from
   `ConnectionFields` entirely (see the TrafficLight example in
-  [api-script-declaration.md](api-script-declaration.md#connectionfields)).
+  [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
-  [api-logging.md](api-logging.md)) over silently routing a failed job to a generic error connection —
+  [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
   downstream, not as a substitute for `fail()`.
 
@@ -93,7 +108,7 @@ await fs.promises.rm(tempPath);
 
 **Known issue — pending a server-side fix; remove this section once fixed.** Applies to all current versions.
 
-`job.createChild()` copies the parent's *current* datasets immediately (see [api-job.md](api-job.md#child-jobs)); `job.createDataset()` only registers a pending write, flushed to disk at the next `sendTo*()` call (see [api-job.md](api-job.md#datasets-metadata)). If a child is created *before* a dataset is written, the child inherits the job's existing dataset under that name instead. At flush time, the pending write fans out concurrently to the parent and to every child created so far, all reading from the same source file on disk — targets that already have a dataset by that name get the file **moved** into place, while targets that don't get it **copied**. When a mix of both happens against a single source file, the move wins the race and the copies fail with errors like `Could not place the file with the decoded data '...' into the datasets folder`, deterministically and on every retry (the source file is gone after the first attempt).
+`job.createChild()` copies the parent's *current* datasets immediately (see [job.md](job.md#child-jobs)); `job.createDataset()` only registers a pending write, flushed to disk at the next `sendTo*()` call (see [job.md](job.md#datasets-metadata)). If a child is created *before* a dataset is written, the child inherits the job's existing dataset under that name instead. At flush time, the pending write fans out concurrently to the parent and to every child created so far, all reading from the same source file on disk — targets that already have a dataset by that name get the file **moved** into place, while targets that don't get it **copied**. When a mix of both happens against a single source file, the move wins the race and the copies fail with errors like `Could not place the file with the decoded data '...' into the datasets folder`, deterministically and on every retry (the source file is gone after the first attempt).
 
 **Rule:** perform every dataset write on a job before creating any child of it. Where a script's structure naturally interleaves the two, iterate the dataset outputs first, then the child-job outputs, rather than handling each output in one pass.
 
@@ -131,14 +146,14 @@ The Node.js executor process is recycled when any of the following thresholds is
 
 On cleanup, any files/folders created in the temp area are removed. Always close file handles and database connections before the entry point returns.
 
-See [api-execution-environment.md](api-execution-environment.md) for how this process model affects state persistence and error handling across job invocations.
+See [execution-environment.md](execution-environment.md) for how this process model affects state persistence and error handling across job invocations.
 
 ## Driving a third-party CLI application
 
 `findApplicationPath` and the `ApplicationPath` property are the legacy-scripting mechanism for
 locating a third-party application; neither is available to Node.js scripts, and `ApplicationPath`
 is a reserved name Switch silently drops from the declaration (see
-[api-script-declaration.md](api-script-declaration.md#built-in-elementfields)). A Node.js script or
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields)). A Node.js script or
 app that shells out to an external binary resolves the path itself, using the following pattern.
 
 1. Declare an ordinary custom property for the path under a name of your own — `cliPath`, not
@@ -147,7 +162,7 @@ app that shells out to an external binary resolves the path itself, using the fo
    `Default="Automatic"` and `Subtype="automatic"`. The `automatic` literal editor is what lets the
    user express "find it yourself" without typing a magic string, and `getPropertyStringValue()`
    returns the literal `"Automatic"` for it — see
-   [api-property-editors.md § Literal editors](api-property-editors.md#literal-editors).
+   [property-editors.md § Literal editors](../switch-project/property-editors.md#literal-editors).
 3. Resolve the path once per flow start, in `flowStartTriggered`: if the property reads
    `Automatic`, run whatever discovery the application needs; otherwise take
    `flowElement.getPropertyStringValue('cliPath')`. Verify the resulting path actually exists, then
@@ -157,7 +172,7 @@ app that shells out to an external binary resolves the path itself, using the fo
    discovery failed: call `flowElement.failProcess()` so the element goes into an error state,
    instead of failing every individual job.
 5. Remove the global data entry in `flowStopTriggered` — global data is never cleaned up
-   automatically (see [api-switch.md § Global data](api-switch.md#global-data)).
+   automatically (see [switch.md § Global data](switch.md#global-data)).
 
 Doing discovery once at flow start rather than per job keeps a filesystem search off the job path,
 and gives the operator a single clear element-level error when the application is missing.

package/docs/switch-api/{api-job.md → 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`).
@@ -36,7 +45,7 @@ Returns the local filesystem path to the job. Use `AccessLevel.ReadOnly` to read
 
 ## Routing
 
-Every job must be routed exactly once. See [api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) for which `sendTo*()` method is appropriate for a given `ConnectionType`/`OutgoingConnections` declaration.
+Every job must be routed exactly once. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for which `sendTo*()` method is appropriate for a given `ConnectionType`/`OutgoingConnections` declaration.
 
 ```ts
 job.sendToNull(): Promise<void>
@@ -75,7 +84,7 @@ Re-queue the job for `jobArrived` after a minimum delay (re-evaluates dynamic pr
 
 ## Failure & logging
 
-See [api-logging.md](api-logging.md) for log level semantics and logging practice.
+See [logging.md](logging.md) for log level semantics and logging practice.
 
 ```ts
 job.fail(message: string, messageParams?: (string | number | boolean)[]): void
@@ -92,7 +101,7 @@ Log a message including job context. To log a literal `%`, pass it as a param: `
 ```ts
 job.createChild(path: string): Promise<Job>
 ```
-Creates a new job inheriting the processing history, metadata, and private data of the parent. Takes effect immediately: the child's datasets are copied from the parent's *current* server-side state, so any pending `createDataset()` write not yet flushed by a `sendTo*()` call is not reflected in it. See [api-job-patterns.md](api-job-patterns.md#dataset-writes-must-precede-child-job-creation) — creating a child before writing a dataset is a common source of bugs. The caller is responsible for cleaning up the source file after routing (see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup)).
+Creates a new job inheriting the processing history, metadata, and private data of the parent. Takes effect immediately: the child's datasets are copied from the parent's *current* server-side state, so any pending `createDataset()` write not yet flushed by a `sendTo*()` call is not reflected in it. See [job-patterns.md](job-patterns.md#dataset-writes-must-precede-child-job-creation) — creating a child before writing a dataset is a common source of bugs. The caller is responsible for cleaning up the source file after routing (see [job-patterns.md](job-patterns.md#temp-file-cleanup)).
 
 ## Private data
 
@@ -128,7 +137,7 @@ List all datasets attached to the job. **Immediate**: reads server state at once
 ```ts
 job.createDataset(name: string, filePath: string, model: DatasetModel): Promise<void>
 ```
-Attach a new dataset. **Deferred**: registers in-memory only; the file is not uploaded until the next `sendTo*()` call. Caller must clean up the source file after routing — see [api-job-patterns.md](api-job-patterns.md#temp-file-cleanup).
+Attach a new dataset. **Deferred**: registers in-memory only; the file is not uploaded until the next `sendTo*()` call. Caller must clean up the source file after routing — see [job-patterns.md](job-patterns.md#temp-file-cleanup).
 
 ```ts
 job.getDataset(name: string, accessLevel: AccessLevel): Promise<string>