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

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

@@ -1,7 +1,7 @@
 # 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 +20,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 +84,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 +142,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 +154,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 +185,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 +196,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 +222,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 +232,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,75 @@
+# 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,60 @@
+# 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,74 @@
+# 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-logs-and-dataroot.md → switch-project/logs-and-dataroot.md}

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

@@ -16,19 +16,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 +37,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 +53,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 +62,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 +97,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.

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

@@ -0,0 +1,66 @@
+# Writing Property and Connection Documentation
+
+Guidance for the *content* of `Tooltip` and `DetailedInfo` on properties and connections — see
+[script-declaration.md](script-declaration.md#custom-property-elements-elementfields) for
+the attribute mechanics (when each is required, what breaks if omitted). This page covers what to
+actually write in them.
+
+Both attributes are read only inside Switch Designer, by someone who has already added the flow
+element to a flow. Compare with [app-store-listing.md](../switch-appstore/app-store-listing.md), read by
+someone deciding whether to install the app at all, and [app-manual.md](../switch-appstore/app-manual.md), a
+separate uploaded document.
+
+**Delivery:** write this content directly into the `Tooltip`/`DetailedInfo` attributes in
+`<ScriptID>.xml` — there is no separate file. See
+[script-declaration.md § Agent editing policy](script-declaration.md#agent-editing-policy)
+for how to edit the declaration safely.
+
+## Tooltip
+
+The one-line hint shown in the Properties pane. This is the field that matters most here — it's
+always visible to whoever is configuring the property, connection, or the app's own icon, with no
+extra click required.
+
+- Add information the property name doesn't already give: units, valid range, format, or an
+  example value. A tooltip that just restates the label ("Output folder: the output folder to
+  use") wastes the one line a user reliably reads.
+- If no sensible default is possible, put an example value in the tooltip — see the `Default`
+  guideline in [script-declaration.md](script-declaration.md#custom-property-elements-elementfields).
+- Sentence-style capitalization, no trailing period, one line. Match the style already used in
+  declarations: `Tooltip="Select the output folder"`.
+- Skip it only when the property is genuinely self-explanatory from its name alone, with no
+  constraints worth stating (e.g. "Number of copies" with no min/max).
+
+## DetailedInfo
+
+Feeds the HTML documentation Switch Designer can export for a whole *flow* — not something
+specific to this app, it's compiled from every element the flow builder happens to have placed in
+that flow. Real, but low priority in practice: it's an opt-in export most flow builders never
+generate, and plenty of shipped apps leave it blank. Don't treat an empty `DetailedInfo` as a
+defect to pad out.
+
+Fill it in when the tooltip's one line genuinely isn't enough — an interaction with another
+property, an edge case worth flagging, or why a setting matters, not a restatement of the tooltip
+in longer sentences. A trivial property with `DetailedInfo=""` is expected and fine.
+
+If you do write `DetailedInfo`, don't rely on it being the only place that content exists — the
+property's fuller description belongs in [app-manual.md](../switch-appstore/app-manual.md#properties-detailed-info)
+regardless, since that document is far more likely to actually be read.
+
+## Writing quality
+
+Applies to both fields, and is the same bar [app-store-listing.md](../switch-appstore/app-store-listing.md)
+and [app-manual.md](../switch-appstore/app-manual.md) hold their content to:
+
+- **Don't restate the field name.** A tooltip on "Output folder" that says "The output folder"
+  adds nothing a user didn't already know.
+- **No generic AI/marketing vocabulary** — powerful, seamless, robust, intuitive, and similar
+  words that could describe any property in any app. Say the specific thing this one does.
+- **No meta-commentary about the implementation.** Write what the user sees or does, not how the
+  script is coded internally ("this property is passed to the internal handler").
+- **No vague filler.** "Set this to an appropriate value" tells a user nothing; a concrete unit,
+  range, or example does.
+- **No copy-pasted boilerplate across properties.** Identical tooltip text reused on unrelated
+  properties signals nobody thought about the individual property.
+- **Keep it translatable.** Idioms and culture-specific references don't translate cleanly into
+  the six Switch languages — see [switch.md § Translation extraction rules](../switch-api/switch.md#translation-extraction-rules).