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

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

@@ -1,9 +1,18 @@
+---
+id: logging
+category: switch-api
+order: 18
+summary: "Log level semantics, logging practice, `console.log` limitation, common gotchas"
+triggers:
+  - "Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls"
+---
+
 # Logging Practices
 
 Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElement.failProcess()`
-— 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 +22,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 +33,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 +84,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}

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

package/docs/{switch-api/api-app-guidelines.md → switch-appstore/app-guidelines.md}

@@ -1,7 +1,16 @@
+---
+id: app-guidelines
+category: switch-appstore
+order: 20
+summary: "Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries)"
+triggers:
+  - "Preparing a script for publication as an app, or reviewing one against Appstore submission criteria"
+---
+
 # App Publishing Guidelines
 
 A pre-publish checklist for a script intended for the Enfocus Appstore (`ScriptPackageType="App"`
-— see [api-script-structure.md § Script vs App](api-script-structure.md#script-vs-app)). Each item
+— see [script-structure.md § Script vs App](../switch-project/script-structure.md#script-vs-app)). Each item
 here is enforced in more detail at the linked section — this page exists to be read top-to-bottom
 right before submission, not as the primary source for any individual rule. The one exception is
 [App-only](#app-only) at the bottom, which is documented in full here.
@@ -20,48 +29,49 @@ Items fall into three tiers, marked on each one:
 
 - [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30
   characters or fewer and uses sentence-style capitalization ("Customer name", not "Customer
-  Name") — see [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+  Name") — see [script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields).
 - [ ] **Apps required / scripts recommended.** Every property has a `Tooltip`, unless it's fully
   self-explanatory with no extra constraints (e.g. "Number of copies" with no min/max) — see
-  [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+  [script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields) for
+  the attribute and [property-documentation.md](../switch-project/property-documentation.md) for what to write in it.
 - [ ] **Universal.** Dynamic editors (`sltextwithvar`/`mltextwithvar`, `conditionwithvar`,
   `scriptexp`) are enabled wherever the value could plausibly vary per job, and omitted where the
   value is inherently static (e.g. a dataset name) — see
-  [api-property-editors.md § Common practices](api-property-editors.md#common-practices).
+  [property-editors.md § Common practices](../switch-project/property-editors.md#common-practices).
 - [ ] **Universal.** Keyword-style default values ("Default", "None", "Automatic", …) use the
   matching literal editor (`default`, `none`, `automatic`, …), not a typed string default — 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).
 - [ ] **Universal.** Every property using `askplugin`/`askplugin2` ("Select from library"/"Select
   many from library") has a matching `getLibraryForProperty`/`getLibraryForConnectionProperty`
-  entry point — see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+  entry point — see [entry-points.md § Property UI callbacks](../switch-api/entry-points.md#property-ui-callbacks).
 - [ ] **Apps required / scripts recommended.** Every property's editor chain includes at least one
   editor that doesn't require an add-on Switch module — e.g. never offer `scriptexp` (Scripting
   Module) as the only editor — see
-  [api-property-editors.md § Common practices](api-property-editors.md#common-practices).
+  [property-editors.md § Common practices](../switch-project/property-editors.md#common-practices).
 - [ ] **Universal.** Every property using the `external`/`external2`/… editor has either a
   non-empty dependent `Application` property or a `findExternalEditorPath` entry point — see
-  [api-property-editors.md § Notes](api-property-editors.md#notes).
+  [property-editors.md § Notes](../switch-project/property-editors.md#notes).
 - [ ] **Apps required / scripts recommended.** Every property has a default value unless one
   genuinely isn't possible, in which case the `Tooltip` gives an example value instead — see
-  [api-script-declaration.md](api-script-declaration.md#custom-property-elements-elementfields).
+  [script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields).
 - [ ] **Universal.** Every property/connection field declaring `Validation="Custom"` or `"Standard
   and custom"` has a matching `validateProperties`/`validateConnectionProperties` entry point —
-  see [api-entry-points.md § Property UI callbacks](api-entry-points.md#property-ui-callbacks).
+  see [entry-points.md § Property UI callbacks](../switch-api/entry-points.md#property-ui-callbacks).
 
 ## Entry points
 
 - [ ] **Universal.** `jobArrived` is present when `IncomingConnections="Yes"`; `timerFired` is
   present when `IncomingConnections="No"` (and may additionally be present alongside `jobArrived`)
-  — see [api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+  — see [entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
 - [ ] **Universal.** No empty `jobArrived` or `timerFired` — an entry point that does nothing is
   removed entirely, not left in place — see
-  [api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+  [entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
 
 ## Sending jobs
 
 All **universal** — see
-[api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) and
-[api-script-declaration.md § ConnectionFields](api-script-declaration.md#connectionfields) for full
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) and
+[script-declaration.md § ConnectionFields](../switch-project/script-declaration.md#connectionfields) for full
 detail.
 
 - [ ] If `OutgoingConnections` is not `No`, some `sendTo*()` method is called at least once for
@@ -83,27 +93,27 @@ detail.
 - [ ] **Universal.** An `Error` is logged when a custom
   `validateProperties`/`validateConnectionProperties` check returns `valid: false` for a tag, and
   when `getLibraryForProperty`/`getLibraryForConnectionProperty` would otherwise return an empty
-  list — see [api-logging.md § Message quality](api-logging.md#message-quality).
+  list — see [logging.md § Message quality](../switch-api/logging.md#message-quality).
 - [ ] **Universal.** Log messages are free of grammatical errors and typos — see
-  [api-logging.md § Message quality](api-logging.md#message-quality).
+  [logging.md § Message quality](../switch-api/logging.md#message-quality).
 - [ ] **Universal.** Log messages use `%1`/`%2`/… placeholders with `messageParams`, not string
   concatenation or interpolation of dynamic values — required for correct translation. See
-  [api-logging.md § Placeholders instead of concatenation](api-logging.md#placeholders-instead-of-concatenation),
+  [logging.md § Placeholders instead of concatenation](../switch-api/logging.md#placeholders-instead-of-concatenation),
   which also covers the separate, narrower literal-`%` escaping gotcha.
 - [ ] **Apps required / scripts recommended.** Logging isn't excessive — no `Info`/`Debug` calls
   that don't help a flow operator or support engineer understand what happened — see
-  [api-logging.md § Log volume](api-logging.md#log-volume).
+  [logging.md § Log volume](../switch-api/logging.md#log-volume).
 
 ## Temp files and paths
 
 - [ ] **Universal.** All temporary files and folders are removed by the script before it finishes,
   rather than relying on Switch's executor-refresh cleanup — see
-  [api-job-patterns.md § Temp file cleanup](api-job-patterns.md#temp-file-cleanup).
+  [job-patterns.md § Temp file cleanup](../switch-api/job-patterns.md#temp-file-cleanup).
 - [ ] **Universal.** No Oracle JRE is embedded as an extra file, in a script or an app — see
-  [api-script-structure.md § Script folder files](api-script-structure.md#script-folder-files).
+  [script-structure.md § Script folder files](../switch-project/script-structure.md#script-folder-files).
 - [ ] **Apps required / scripts recommended.** File system path strings are built with Node's
   `path` module, not hardcoded separators or string concatenation — see
-  [api-job-patterns.md § Platform-independent paths](api-job-patterns.md#platform-independent-paths).
+  [job-patterns.md § Platform-independent paths](../switch-api/job-patterns.md#platform-independent-paths).
 
 ---
 
@@ -141,7 +151,7 @@ Unlike the sections above, these are documented in full here rather than deferri
 - [ ] **`ExecutionMode="Concurrent"` wherever the script allows it.** `Serialized` is the default
   and the slower choice; concurrent is preferred for throughput. If you go concurrent, the script
   must synchronise its own access to any shared resource — see
-  [api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes).
+  [execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes).
 - [ ] **`ExecutionGroup` is shared across every app that drives the same non-concurrent third-party
   application**, so Switch can stop them using it simultaneously. If your app is in that situation,
   ask Enfocus which group name to use rather than inventing one.
@@ -153,11 +163,16 @@ Unlike the sections above, these are documented in full here rather than deferri
   what it declares — the declared subcategory only takes effect once Enfocus has signed the app, and
   review may change it.
 - [ ] **`DetailedInfo` is present on every property and every connection**, not just `Tooltip`.
-  Switch Designer generates the app's HTML documentation from these, so an empty `DetailedInfo`
-  produces a blank entry in the shipped docs.
+  Switch Designer can export a *flow's* HTML documentation from every element in it, so an empty
+  `DetailedInfo` produces a blank entry there if a flow builder ever generates one — see
+  [property-documentation.md](../switch-project/property-documentation.md) for what to write in it, and when
+  it's fine to leave blank.
 - [ ] **`Description`, `Compatibility`, `SupportInfo` and `AppDiscovery` are filled in.** These are
   required to create the `.enfpack` at all, and `SupportInfo` must point at *your* support channel,
-  never Enfocus Support.
+  never Enfocus Support — see [app-store-listing.md](app-store-listing.md) for what to write
+  in each.
+- [ ] **The app manual document is prepared**, following Enfocus's `documentation-app_name.docx`
+  template, and uploaded during Appstore review — see [app-manual.md](app-manual.md).
 - [ ] **The declared incoming/outgoing connection topology matches what the code actually does** —
   see [Entry points](#entry-points) and [Sending jobs](#sending-jobs) above.
 - [ ] **Dependent properties have real dependency conditions and values, never left empty**, and the
@@ -179,8 +194,8 @@ Unlike the sections above, these are documented in full here rather than deferri
 ### Localization
 
 - [ ] **Prefer more than one language.** An app is preferably localized beyond English — see
-  [Translation files](api-script-structure.md#script-folder-files) (`<LanguageCode>.ts`) and
-  `SwitchScriptTool --generate-translations` in [api-tooling.md](api-tooling.md).
+  [Translation files](../switch-project/script-structure.md#script-folder-files) (`<LanguageCode>.ts`) and
+  `SwitchScriptTool --generate-translations` in [tooling.md](../switch-project/tooling.md).
 - [ ] **The app's own translations are limited to the six Switch UI languages** (English, French,
   German, Italian, Chinese, Japanese); other languages are not accepted for the app itself. The
   separate Appstore *documentation* may be supplied in additional languages, since it isn't
@@ -190,15 +205,17 @@ Unlike the sections above, these are documented in full here rather than deferri
   user-facing message needs an entry in each shipped language file, and log calls must go through
   that mechanism rather than hardcoding English text that bypasses it. Note that
   `Switch.tr()` extraction is static and silently skips anything that isn't a plain string literal
-  — see [api-switch.md § Translation extraction rules](api-switch.md#translation-extraction-rules).
+  — see [switch.md § Translation extraction rules](../switch-api/switch.md#translation-extraction-rules).
   Check the generated `.ts` files rather than assuming.
 
 ### Icon
 
 - [ ] **32×32 PNG, RGB, transparent background**, attached as the app icon. This is what appears in
   the Elements pane and in flows.
-- [ ] **A separate 200×200 version is supplied to Enfocus** for the Appstore listing — it is not
-  part of the pack.
+- [ ] **A separate icon (at least 200×200, square) is uploaded to the Appstore submission form**
+  for the Appstore listing — it is not part of the pack. See
+  [app-store-submission.md § Icons](app-store-submission.md#icons) for both assets' exact
+  specs and how to derive/verify them from source art.
 
 ### Extra files
 
@@ -214,9 +231,9 @@ Unlike the sections above, these are documented in full here rather than deferri
   validates the app package's signature, and content that changes after signing fails that
   validation, causing Switch to remove the app. Write runtime-mutable data (temp files, caches,
   generated output) outside the app folder — see
-  [api-job-patterns.md § Temp file cleanup](api-job-patterns.md#temp-file-cleanup).
+  [job-patterns.md § Temp file cleanup](../switch-api/job-patterns.md#temp-file-cleanup).
 - [ ] Find bundled files at runtime with `flowElement.getPluginResourcesPath()` — see
-  [api-flow-element.md](api-flow-element.md).
+  [flow-element.md](../switch-api/flow-element.md).
 
 ### Source and review hygiene
 
@@ -224,7 +241,7 @@ Unlike the sections above, these are documented in full here rather than deferri
 - [ ] **No malicious or unrelated payload** — nothing that harms the user's machine or installs
   additional software.
 - [ ] **No Oracle JRE embedded**, in a script or an app, for licensing reasons — see
-  [api-script-structure.md § Script folder files](api-script-structure.md#script-folder-files).
+  [script-structure.md § Script folder files](../switch-project/script-structure.md#script-folder-files).
 - [ ] **Automating a third-party application doesn't breach that application's licence.** Some
   vendors' terms explicitly exclude automation; check before building.
 

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

@@ -0,0 +1,84 @@
+---
+id: app-manual
+category: switch-appstore
+order: 23
+summary: "Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template)"
+triggers:
+  - "Preparing the app manual document for Appstore submission"
+---
+
+# Writing the App Manual
+
+Guidance for the separate Word/PDF document an app creator uploads during Appstore review,
+following Enfocus's `documentation-app_name.docx` template. Enfocus shows it as a downloadable
+document on the app's Appstore detail page — distinct from the
+[listing fields](app-store-listing.md) shown inline on the listing itself, and from
+[Tooltip/DetailedInfo](../switch-project/property-documentation.md), seen only after installing. Follow the
+template's section order below; don't invent your own structure.
+
+**Delivery:** there's no declaration attribute for this content, since it isn't part of the app
+itself. Write it to `./DOCUMENTATION.md` at the project root, using the section headers below. The
+user copies each section into Enfocus's `documentation-app_name.docx` template and uploads the
+result during Appstore review; tell them that's the next step once the file is written.
+
+Same writing-quality bar as [property-documentation.md § Writing quality](../switch-project/property-documentation.md#writing-quality):
+no restated field names, no generic marketing vocabulary, no meta-commentary about the
+implementation, no vague filler, no copy-pasted boilerplate, nothing that won't translate cleanly.
+
+## App name
+
+The declaration's `DisplayName`.
+
+## Description
+
+Reuse [the listing's `Description`](app-store-listing.md#description) — adapt lightly if the
+extra room here helps (e.g. a screenshot the listing field can't carry), but don't rewrite the
+same facts from scratch.
+
+## Compatibility
+
+**Not the same field as the declaration's `Compatibility` attribute** — see the naming trap in
+[app-store-listing.md § Compatibility](app-store-listing.md#compatibility). This section
+is the minimum **Switch** version the app requires, e.g. "Switch 24.10 and higher." There's no
+declaration attribute for it; it's implicit in which SwitchScripter version built the app (see
+[script-structure.md § SwitchScripter and Switch version compatibility](../switch-project/script-structure.md#switchscripter-and-switch-version-compatibility)).
+The same value also goes in the "Switch Version" field on the
+[Appstore App Version submission form](app-store-submission.md#fields-that-reuse-content-youve-already-written)
+— state it explicitly here rather than leaving it for the reader to infer.
+
+## Compatibility third-party applications
+
+Reuse [the listing's `Compatibility`](app-store-listing.md#compatibility) content — the
+third-party application versions this app supports, with links to the vendor's download/version
+page where one exists.
+
+## Application discovery details
+
+Reuse [the listing's `AppDiscovery`](app-store-listing.md#appdiscovery) content. Add a
+screenshot here if the discovery mechanism (or the manual-path property, when auto-detection
+fails) is easier to show than describe.
+
+## Connections
+
+Reuse [the listing's `Connections`](app-store-listing.md#connections) content, expanded with
+whatever detail or screenshots the shorter listing field couldn't carry.
+
+## Properties detailed info
+
+Reuse each property's and connection's [`DetailedInfo`](../switch-project/property-documentation.md#detailedinfo)
+content — but don't limit this section to whatever `DetailedInfo` happens to contain. `DetailedInfo`
+is optional and often left blank; this manual is the far more likely surface to actually be read,
+so write real per-property content here even for properties where `DetailedInfo` was skipped.
+
+For an app bundle (multiple flow elements in one pack), document each flow element separately —
+the template repeats this section per element ("Flow element 1", "Flow element 2", …).
+
+### Flow elements properties
+
+Per flow element, per property: what it controls, and any tip or constraint a user needs to get
+the element working — the same content `DetailedInfo` would hold, written in full regardless of
+whether `DetailedInfo` itself was filled in.
+
+### Outgoing connections properties
+
+Same treatment, for injected connection properties.

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

@@ -0,0 +1,69 @@
+---
+id: app-store-listing
+category: switch-appstore
+order: 22
+summary: "Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`"
+triggers:
+  - "Writing or reviewing the app's Appstore listing text"
+---
+
+# Writing the Appstore Listing Fields
+
+Guidance for the *content* of the declaration's prose fields that appear on the app's Enfocus
+Appstore listing: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, and `Connections`
+— see [script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields) for the
+attribute mechanics.
+
+Audience here is a prospective buyer browsing the Appstore, deciding whether to install the app at
+all — they haven't seen the flow element yet. That's different from
+[property-documentation.md](../switch-project/property-documentation.md) (`Tooltip`/`DetailedInfo`, read only
+after installing) and from [app-manual.md](app-manual.md) (a separate uploaded document).
+This content is also reused directly in the app manual's Description, Compatibility third-party
+applications, Application discovery details, and Connections sections — write it once, here, well.
+
+**Delivery:** write this content directly into the matching top-level attributes in
+`<ScriptID>.xml` (`Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`) —
+there is no separate file. See
+[script-declaration.md § Agent editing policy](../switch-project/script-declaration.md#agent-editing-policy)
+for how to edit the declaration safely.
+
+Same writing-quality bar as [property-documentation.md § Writing quality](../switch-project/property-documentation.md#writing-quality):
+no restated field names, no generic marketing vocabulary, no meta-commentary about the
+implementation, no vague filler, no copy-pasted boilerplate, nothing that won't translate cleanly.
+
+## `Description`
+
+What the app does, who it's for, and the third-party application or service it automates. Lead
+with the concrete task the app performs, not a category label — "Converts incoming PDFs to the
+customer's house color profile using ColorLogic" tells a buyer more than "A color management
+app." A screenshot is worth adding here if it clarifies the app's purpose faster than prose would.
+
+## `Compatibility`
+
+**Naming trap:** despite the name, this is **third-party application** compatibility, not Switch
+version compatibility — Switch has no declaration field for the minimum Switch version an app
+requires (see [app-manual.md § Compatibility](app-manual.md#compatibility) for where that
+goes instead). State which versions of the automated third-party application are supported, e.g.
+"Requires Acrobat Pro DC 2023 or later." Link to the third-party vendor's own download or version
+page if one exists.
+
+## `SupportInfo`
+
+The app creator's own support channel (email or URL) — **never Enfocus Support**, this is
+mandatory per [app-guidelines.md § App-only](app-guidelines.md#top-level-declaration-properties).
+State the channel plainly; this field has no dedicated section in the app manual, so it's the only
+place this information reliably reaches a buyer before they install.
+
+## `AppDiscovery`
+
+How the app locates the third-party application on disk. State the actual mechanism, concretely
+enough that a user who hits a failure knows what to check: which known install paths are searched
+first, and — if auto-detection can fail — which property lets the user point at the install
+location manually.
+
+## `Connections`
+
+A prose overview of the flow element's incoming and outgoing connections: what triggers the
+element, what each outgoing connection carries, and when a job is routed to which one. This is the
+topology summary a flow builder reads before wiring the element into a flow, so describe behavior
+("routes to Error when validation fails"), not just connection names.

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

@@ -0,0 +1,83 @@
+---
+id: app-store-submission
+category: switch-appstore
+order: 24
+summary: "Writing guidance for the Create Appstore App / Create Appstore App Version web forms: Short Description, What's new, Eula, icon specs, and which fields reuse content already written elsewhere"
+triggers:
+  - "Preparing content for the Appstore website submission forms"
+---
+
+# Writing the Appstore Submission Forms
+
+Guidance for the two web forms on the Enfocus Appstore site: **Create Appstore App** (once per
+app) and **Create Appstore App Version** (once per release). These are separate from the
+[listing fields](app-store-listing.md) in the declaration and from the
+[app manual](app-manual.md) — a human fills these forms in directly on the Enfocus website, so
+the agent's job is to prepare the content, not submit it. `Package Password`, `Binary`, and
+`Signed Binary` are manual/security-sensitive steps on the App Version form; leave those to the
+user entirely.
+
+**Delivery:** write the content below to `./README.md` at the project root, labeled by field name,
+for the user to copy into the two forms. If the project already has a `README.md` for other
+purposes, add a clearly separated section rather than overwriting it.
+
+Same writing-quality bar as [property-documentation.md § Writing quality](../switch-project/property-documentation.md#writing-quality).
+
+## Fields that reuse content you've already written
+
+Point the user at the source instead of rewriting these:
+
+| Form field | Source |
+|---|---|
+| Display Name | Declaration `DisplayName` |
+| Internal Identifier | Declaration `Name` |
+| Long Description | [Listing `Description`](app-store-listing.md#description) |
+| Keywords | Declaration `Keywords` — the form must match it exactly, it's checked against the script source |
+| Categories | Declaration `PositionInElementPane`/`SubcategoryInElementPane` — see [app-guidelines.md](app-guidelines.md#top-level-declaration-properties) |
+| Support Website / Support Phone / Support Email | [Listing `SupportInfo`](app-store-listing.md#supportinfo), split across the three fields the form actually has |
+| Third-party Compatibility | [Listing `Compatibility`](app-store-listing.md#compatibility) |
+| Switch Version | The minimum Switch version, same content as [the app manual's Compatibility section](app-manual.md#compatibility) |
+
+## New content
+
+Nothing above covers these — the form is the only place they're written.
+
+### Short Description
+
+Max 500 characters. Distinct from Long Description: this is the search-result and marketing-email
+summary, not a shorter copy of the full description. One or two sentences stating what the app
+does and the third-party dependency, without repeating Display Name.
+
+### What's new
+
+Per-version release notes: what changed in *this* version, for someone deciding whether to update.
+Lead with the effect on the user (new capability, fixed behavior), not the implementation. Skip
+internal refactors with no user-visible effect.
+
+### Eula
+
+**Don't draft this from scratch.** A EULA is a binding legal document — write it only from the app
+creator's existing legal-reviewed template, or leave it for them to supply. If neither exists, tell
+the user this needs their own legal review rather than generating terms.
+
+## Icons
+
+Two separate image assets, both uploaded on the Create Appstore App form:
+
+| Field | Spec | Notes |
+|---|---|---|
+| Switch Icon | 32×32 px recommended (larger is resized down); PNG/GIF/JPG | Must match the `Icon` property already in the script source — use the same file you packaged with the app, don't create a second one |
+| Appstore Icon | At least 200×200 px, square (a non-square image gets transparent padding added); PNG/GIF/JPG, under 100 MB | Used across the whole Appstore site: overview, detail page, search results |
+
+Creating the actual artwork is a design task, not something to improvise without source material —
+if the app creator hasn't supplied a logo or icon source image, say so rather than generating
+placeholder art. Given a source image, verify and derive the two required files with a CLI image
+tool (`sips` on macOS, or ImageMagick):
+
+```bash
+# Verify dimensions and that the file is actually PNG
+sips -g pixelWidth -g pixelHeight -g format icon-source.png
+
+# Resize down to the 32x32 Switch icon (never upscale a smaller source)
+sips -z 32 32 icon-source.png --out switch-icon.png
+```

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

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

package/docs/{switch-api/api-logs-and-dataroot.md → switch-project/logs-and-dataroot.md}

@@ -1,8 +1,17 @@
+---
+id: logs-and-dataroot
+category: switch-project
+order: 19
+summary: "Locating the Application Data Root, querying `ServerLogs.db3` directly"
+triggers:
+  - "Diagnosing or validating a script from its actual log output rather than by reading the code"
+---
+
 # Locating and Querying Switch's Log Database
 
 For diagnosing or validating a script from the outside — reading what the user themselves would see
 in Switch's Message pane — rather than instrumenting the script itself. See
-[api-logging.md](api-logging.md) for how a script produces these messages in the first place.
+[logging.md](../switch-api/logging.md) for how a script produces these messages in the first place.
 
 ## Finding the Application Data Root
 

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

@@ -1,3 +1,12 @@
+---
+id: project-planning
+category: switch-project
+order: 1
+summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+triggers:
+  - "Starting a new script or app, before scaffolding any files"
+---
+
 # Project Planning
 
 A pre-scaffolding checklist for a new script or app. Work through this with the user before
@@ -16,19 +25,19 @@ relevant.
 
 Ask whether this is for private or internal use (a plain `Script`, distributed freely) or intended
 for the Enfocus Appstore (an `App`). See
-[api-script-structure.md § Script vs App](api-script-structure.md#script-vs-app) for what differs.
+[script-structure.md § Script vs App](script-structure.md#script-vs-app) for what differs.
 
 This answer gates several items below:
 
 - **App**: localization, password protection, `Name`-never-changes discipline, `Concurrent`-by-default
   expectation, icon/keywords, and the version-baseline and Appstore-competition checks further down
-  all apply. See [api-app-guidelines.md](api-app-guidelines.md) for the full pre-publish checklist,
+  all apply. See [app-guidelines.md](../switch-appstore/app-guidelines.md) for the full pre-publish checklist,
   most of which is worth designing toward from the start rather than retrofitting later.
 - **Script**: none of the app-only items apply. Keep it simple and don't raise app concerns for a
   plain script.
 
 If App, also ask which languages it must support. English is required; more than one language is
-preferable, see [api-app-guidelines.md § Localization](api-app-guidelines.md#localization).
+preferable, see [app-guidelines.md § Localization](../switch-appstore/app-guidelines.md#localization).
 
 ### 2. What should job processing look like in their flow?
 
@@ -37,15 +46,15 @@ need to wait on an external process or resource, could more than one job at a ti
 shared resource. Don't ask the user to pick entry points or connection types directly. Translate the
 answer into a concrete proposal (which entry points, which `sendTo*()` methods, whether `jobArrived`
 alone is enough or work must be deferred to `timerFired`) using
-[api-entry-points.md](api-entry-points.md) and
-[api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs), and be upfront about
+[entry-points.md](../switch-api/entry-points.md) and
+[job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs), and be upfront about
 limitations and tradeoffs so the user can make an informed choice, rather than silently picking an
 approach.
 
 If the design defers job processing to `timerFired` via global data, say explicitly that a flow
 restart replays every queued job through `jobArrived` again, and the script must recognize and skip
 an already-registered job quickly, or a large backlog is slow to clear, see
-[api-entry-points.md § Job processing](api-entry-points.md#job-processing).
+[entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
 
 ## Evaluate and flag, don't ask upfront
 
@@ -53,7 +62,7 @@ an already-registered job quickly, or a large backlog is slow to clear, see
 
 Switch Server runs on Windows and macOS. Default to writing platform-independent code (the `path`
 module, no hardcoded separators, see
-[api-job-patterns.md § Platform-independent paths](api-job-patterns.md#platform-independent-paths))
+[job-patterns.md § Platform-independent paths](../switch-api/job-patterns.md#platform-independent-paths))
 without asking. Only raise target OS as an explicit question once the script needs OS-specific code,
 bundles a native binary, or ships a platform-specific package build, since only then does the answer
 change anything.
@@ -62,28 +71,28 @@ change anything.
 
 Once Script vs App is answered as App, ask or infer the oldest Switch version the app must support.
 This sets the Node.js baseline (see
-[api-script-structure.md § Node.js version per Switch version](api-script-structure.md#nodejs-version-per-switch-version))
+[script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version))
 and which SwitchScripter build is needed to produce a compatible `.enfpack`. Don't ask this for a
 plain script.
 
 ### Concurrency
 
 Default to `Concurrent` execution; it's the preferred choice for apps per
-[api-app-guidelines.md § Top-level declaration properties](api-app-guidelines.md#top-level-declaration-properties).
+[app-guidelines.md § Top-level declaration properties](../switch-appstore/app-guidelines.md#top-level-declaration-properties).
 Don't ask the user to choose upfront. Only raise `Serialized`, and explain why, when the design has
 an actual reason to need it: a third-party application or shared resource that can't tolerate
 concurrent access, or an API the script drives that isn't safe to call in parallel. See
-[api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes).
+[execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes).
 
 ### Native or binary npm dependencies
 
 A file-based script or app that ends up on the ESM bundling path cannot use native (binary) Node
 addons at all, see
-[api-execution-environment.md § Native (binary) addons are not supported](api-execution-environment.md#native-binary-addons-are-not-supported).
+[execution-environment.md § Native (binary) addons are not supported](../switch-api/execution-environment.md#native-binary-addons-are-not-supported).
 If a planned dependency needs one, for example `sharp` or native `sqlite3` bindings, say so before
 the user commits to that library, and suggest a pure JavaScript alternative or a workaround, such as
 shelling out to an external binary, see
-[api-job-patterns.md § Driving a third-party CLI application](api-job-patterns.md#driving-a-third-party-cli-application),
+[job-patterns.md § Driving a third-party CLI application](../switch-api/job-patterns.md#driving-a-third-party-cli-application),
 where one exists.
 
 ### Appstore competition risk (apps only)
@@ -97,4 +106,4 @@ the relevant module license or contacting Enfocus to check before proceeding.
 ---
 
 This checklist stops at planning. Once these are answered, move to
-[api-script-structure.md](api-script-structure.md) to scaffold the project.
+[script-structure.md](script-structure.md) to scaffold the project.