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

package/CHANGELOG.md

@@ -3,7 +3,27 @@
 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.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.
+
+### 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
 

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.15/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.15/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -131,23 +131,27 @@ 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
+- `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
+- `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/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)

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}

@@ -21,12 +21,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

package/docs/switch-api/{api-document-classes.md → document-classes.md}

@@ -121,7 +121,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}

@@ -47,7 +47,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 +83,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 +129,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 +143,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 +157,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-execution-environment.md → execution-environment.md}

@@ -7,7 +7,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 +39,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 +62,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 +80,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}

@@ -21,7 +21,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 +58,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 +75,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 +94,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-job-patterns.md → job-patterns.md}

@@ -73,7 +73,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 +81,9 @@ 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)).
 - 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 +93,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 +131,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 +147,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 +157,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}

@@ -36,7 +36,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 +75,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 +92,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 +128,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>

package/docs/switch-api/{api-logging.md → logging.md}

@@ -1,9 +1,9 @@
 # Logging Practices
 
 Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElement.failProcess()`
-— see [api-job.md](api-job.md#failure--logging) and
-[api-flow-element.md](api-flow-element.md#logging) for their signatures. `LogLevel` values are
-listed in [api-enums.md](api-enums.md). Each log call has a small performance overhead, so where
+— see [job.md](job.md#failure--logging) and
+[flow-element.md](flow-element.md#logging) for their signatures. `LogLevel` values are
+listed in [enums.md](enums.md). Each log call has a small performance overhead, so where
 and how often to log is a deliberate choice, not a default.
 
 ## Log levels
@@ -13,7 +13,7 @@ and how often to log is a deliberate choice, not a default.
 | `Error` | The job/step failed or produced a wrong/unusable result. Often accompanies or precedes a hard stop, but can stand alone if the job continues in a degraded way. |
 | `Warning` | Something unexpected happened but processing continued successfully (a fallback was used, an optional resource was missing). |
 | `Info` | Normal, expected checkpoints worth surfacing to a flow operator without them needing debug mode (e.g. "processed 40 records", "output written to X"). |
-| `Debug` | Verbose detail for diagnosing execution. Many users leave debug logging enabled in production to self-diagnose issues and to help app developers and Enfocus Support — leave meaningful checkpoints in, but trim noisy or no-longer-useful debug logs before shipping. **`Debug` messages only reach the log database if the Switch preference "Log debug messages" is turned on** (off by default) — see [api-logs-and-dataroot.md](api-logs-and-dataroot.md#retention-and-the-debug-level-gate). |
+| `Debug` | Verbose detail for diagnosing execution. Many users leave debug logging enabled in production to self-diagnose issues and to help app developers and Enfocus Support — leave meaningful checkpoints in, but trim noisy or no-longer-useful debug logs before shipping. **`Debug` messages only reach the log database if the Switch preference "Log debug messages" is turned on** (off by default) — see [logs-and-dataroot.md](../switch-project/logs-and-dataroot.md#retention-and-the-debug-level-gate). |
 
 ## Logging in loops
 
@@ -24,7 +24,7 @@ one call per iteration, e.g. `"Found 12 matching jobs"` instead of one log line
 ## `console.log` does not work
 
 `console.log` only produces output when a debug session is attached (see
-[api-debugging.md](api-debugging.md)); in a normal run it is not visible anywhere. Never rely on it
+[debugging.md](../switch-project/debugging.md)); in a normal run it is not visible anywhere. Never rely on it
 in production scripts — use `job.log()`/`flowElement.log()` for anything that should be visible in
 the log/message pane.
 
@@ -75,7 +75,7 @@ job.log(LogLevel.Info, 'Processed file %1 in %2s', [fileName, seconds]);
   looks unfinished and undermines trust.
 - Log an `Error` when a custom `validateProperties`/`validateConnectionProperties` check returns
   `valid: false` for a tag, and when `getLibraryForProperty`/`getLibraryForConnectionProperty` would
-  otherwise return an empty list — see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+  otherwise return an empty list — see [entry-points.md § Property UI callbacks](entry-points.md#property-ui-callbacks).
   Silently returning `false`/`[]` with no log line leaves the user without any explanation.
 
 ## Log volume

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

@@ -120,5 +120,5 @@ const mode = readOnly ? Switch.tr('Read-only') : Switch.tr('Regular');
 await job.log(LogLevel.Info, Switch.tr('Job ID = %1, Mode = %2'), [job.getId(), mode]);
 ```
 
-See [api-logging.md § Placeholders instead of concatenation](api-logging.md#placeholders-instead-of-concatenation)
+See [logging.md § Placeholders instead of concatenation](logging.md#placeholders-instead-of-concatenation)
 for the same rule stated from the logging side.