@enfocussw/switch-scripting-context 0.1.0

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-project/debugging.md

@@ -0,0 +1,61 @@
+---
+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.
+
+## Constraints
+
+- Only works with script folders and non-password-protected packages (see [tooling.md § Script folder vs script package](tooling.md#script-folder-vs-script-package))
+- Only one script can be in debug mode at a time
+- Execution mode is forced to Serialized while debug is enabled (see [execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes))
+- Only these four entry points can be debugged: `jobArrived`, `timerFired`, `httpRequestTriggeredAsync`, `findExternalEditorPath` (signatures in [entry-points.md](../switch-api/entry-points.md))
+- `console.log` output only appears while a debug session is attached (see [logging.md](../switch-api/logging.md))
+
+## Enabling debug mode in Switch Designer
+
+In the Script element properties, once a script folder or package is selected, three extra properties appear:
+
+| Property | Value |
+|---|---|
+| Enable debug mode | Yes |
+| Port | 9229 (default) |
+| Debug entry points | Select from the supported entry points above |
+
+## Attaching VS Code
+
+**Script folder:** Open the script folder in VS Code and press F5. The `.vscode/launch.json` created by `SwitchScriptTool --create` (see [tooling.md § Commands](tooling.md#commands)) is pre-configured for attach mode.
+
+**Package (no `launch.json`):** Create `launch.json` manually:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach",
+      "port": 9229,
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}
+```
+
+Use the port number set in the Script element properties.
+
+After attaching, VS Code stops in internal Switch code first — press F5 once more to reach the script entry point. Set breakpoints anywhere in the entry point being debugged.
+
+## Critical warning
+
+**Disable debug mode in Switch Designer when the debug session is finished.**
+
+If left enabled, the flow hangs silently — `jobArrived` leaves jobs stuck in the input folder, other entry points hang with no visible error or indication.

package/docs/switch-project/logs-and-dataroot.md

@@ -0,0 +1,80 @@
+---
+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
+[logging.md](../switch-api/logging.md) for how a script produces these messages in the first place.
+
+## Finding the Application Data Root
+
+Switch's application data (including logs) lives under a per-installation "Application Data Root"
+folder, which is configurable and does not always sit at its default location. Resolve it in order:
+
+1. Read the `SettingsFolder` value for this Switch Server installation:
+   - **macOS:** `defaults read "com.enfocus.Switch Server" SettingsFolder`, or read the plist directly
+     at `~/Library/Preferences/com.enfocus.Switch Server.plist`.
+   - **Windows:** registry key `HKEY_CURRENT_USER\Software\Enfocus\Switch Server`, value
+     `SettingsFolder`.
+2. That value is a folder path. Inside it, open `settingsNew.xml`.
+3. In `settingsNew.xml`, find the `<UserPreference QSettingsKey="ApplicationData/ApplicationDataRoot">`
+   element — its text content is the actual configured data root path.
+
+Default data root if never changed:
+- **macOS:** `~/Library/Application Support/Enfocus/Switch Server`
+- **Windows:** `%APPDATA%\Enfocus\Switch Server`
+
+Don't assume the default — always resolve it via `SettingsFolder` → `settingsNew.xml`, since it can
+be moved to an arbitrary location (via the Application Data Root Tool).
+
+## The log database
+
+`<data root>/logs/ServerLogs.db3` is a SQLite database and is not itself independently configurable
+— it's always at this fixed path under the data root. It can be queried directly and read-only with
+any SQLite client (e.g. `sqlite3 ServerLogs.db3 "SELECT ..."`) while Switch is running.
+
+Relevant columns on the `logmessages` table:
+
+| Column | Meaning |
+|---|---|
+| `itemtime` | ISO-8601 timestamp of the log entry |
+| `type` | Log level: `debug`, `info`, `warning`, `error`, `assert` |
+| `module` | The flow element's type/display name |
+| `flow` | The flow name |
+| `element` | The flow element instance's name in that flow |
+| `operation` | The message template, with unresolved `%1`–`%9` placeholders |
+| `arg1`–`arg9` | Substitution values for the placeholders in `operation` |
+| `ticket`, `file` | Job identifier / filename, when the message relates to a specific job |
+
+The message text is stored **unresolved** — reconstruct the human-readable message yourself by
+replacing each `%N` in `operation` with the corresponding `argN`. To find a specific script's log
+output, filter on `flow` and `element` (matching the script's flow element name in the canvas) and
+order by `itemtime`.
+
+Example: find recent messages for a specific flow element, most recent first —
+
+```sql
+SELECT itemtime, type, operation, arg1, arg2, arg3
+FROM logmessages
+WHERE flow = 'MyFlow' AND element = 'MyScriptElement'
+ORDER BY itemtime DESC
+LIMIT 50;
+```
+
+## Retention and the debug-level gate
+
+- Log messages are pruned after `Logging/KeepLogMessagesForHours` (12 hours by default,
+  `settingsNew.xml`) — don't expect old entries to still be present.
+- `LogLevel.Debug` messages from `job.log()`/`flowElement.log()` only reach `ServerLogs.db3` at all
+  if the Switch preference `Logging/LogDebugMessages` ("Log debug messages") is enabled — it is
+  **off by default** in a typical install and is meant to be turned on when actively debugging. A
+  script's `Debug`-level output can be completely absent from the log database even though the
+  script correctly calls `job.log(LogLevel.Debug, ...)`; check this preference before concluding a
+  script isn't logging.

package/docs/switch-project/node-versions.md

@@ -0,0 +1,87 @@
+---
+id: node-versions
+category: switch-project
+order: 26
+summary: "How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion`"
+triggers:
+  - "Working out which Node.js version a script or app will run on, or what `SwitchVersion` in manifest.xml does"
+---
+
+# Node.js version per Switch version
+
+
+The Switch Server running the script picks its Node.js version by looking up `SwitchVersion` from
+`manifest.xml` in a fixed table that ships with each Switch release:
+
+| Switch version | `SwitchVersion` | Node.js used |
+|---|---|---|
+| Switch 2020 Spring | `20.0` | 12 |
+| Switch 2020 Fall | `20.1` | 12 |
+| Switch 2021 Spring | `21.0` | 14 |
+| Switch 2021 Fall | `21.1` | 16 |
+| Switch 2022 Spring | `22.0` | 16 |
+| Switch 2022 Fall | `22.1` | 16 |
+| Switch 2023 Fall | `23.1` | 18 |
+| Switch 2024 Spring | `24.0` | 18 |
+| Switch 2024 Fall | `24.1` | 20 |
+| Switch 25.11 | `25.11` | 20 |
+| Switch 26.11 | `26.11` | 24 |
+
+Switch 26.11 bundles Node.js 12.22.12, 14.21.3, 16.20.2, 18.20.8, 20.20.0, and 24.13.0.
+
+`SwitchVersion` controls the Node.js version only. Which scripting API methods exist depends on the
+Switch version the script runs on, see [api-versions.md](../switch-api/api-versions.md).
+
+## What writes `SwitchVersion`
+
+`SwitchVersion` is the version of whichever tool last wrote the manifest. It is not a setting the
+author picks:
+
+- `SwitchScriptTool --create` writes the tool's own version into the new script folder.
+- `SwitchScriptTool --pack` writes the tool's own version into the packed `.sscript`, whatever the
+  script folder's manifest says. The script folder's manifest itself is left unchanged. With
+  SwitchScriptTool 26.11, a folder whose manifest says `21.0` packs to a `.sscript` whose manifest
+  says `26.11`, which moves the script from Node.js 14 to Node.js 24. This was verified with a
+  pre-release SwitchScriptTool build.
+- SwitchScripter writes its own version on every save. Opening a script with a different
+  `SwitchVersion` shows a warning that saving updates the script to the current Node.js version.
+
+**Gotcha:** a script folder tested directly in Switch and the `.sscript` packed from it can run on
+different Node.js versions. A folder created with an older SwitchScriptTool keeps that tool's
+version, but packing it with a newer SwitchScriptTool stamps the newer one. Test the packed
+`.sscript`, not only the folder, before shipping it.
+
+To target an older Node.js version, pack the script with the SwitchScriptTool of a Switch release
+whose row in the table gives that version. For example, a script packed with SwitchScriptTool 25.11
+gets `SwitchVersion` `25.11` and runs on Node.js 20, in Switch 26.11 too. Apps work the same way
+with SwitchScripter, except that there is no SwitchScripter for Switch 25.11. An app that
+needs Node.js 20 is built with the Switch 2024 Fall SwitchScripter (`SwitchVersion` `24.1`), see
+[script-structure.md § SwitchScripter and Switch version compatibility](script-structure.md#switchscripter-and-switch-version-compatibility).
+Editing `SwitchVersion` by hand doesn't last, because `--pack` and SwitchScripter overwrite it.
+
+## Values missing from the table
+
+Behavior of the Switch 26.11 Server:
+
+- No `SwitchVersion` element: treated as `20.1`, so Node.js 12.
+- Lower than the first entry: Node.js 12.
+- Higher than the last entry, for example a package built by a newer tool than the Switch it runs
+  on: the newest Node.js that Switch bundles. The Server logs a debug message that the script
+  "might not be compatible with the current Switch version" and runs it anyway.
+- **Known issue:** a value that isn't an exact entry but falls numerically between the first and
+  last entries matches no Node.js version, for example `25.1` instead of `25.11`, `24.10` instead of
+  `24.1`, or `23.0`. The Server then fails to build the path to a Node.js binary, so no executor
+  process starts for the script. This was confirmed by running the Switch 26.11 lookup code with
+  these values, not by running such a script in Switch, so the exact symptom in Switch hasn't been
+  checked. A value such as `26.3` works today only because it's higher than the last entry, and it
+  will break once a later release adds an entry above it. Never hand-edit `SwitchVersion`. If you
+  must, copy a value exactly as the table above spells it.
+
+## Other effects of `SwitchVersion`
+
+- npm dependencies that are ES modules are bundled with esbuild before execution only when
+  `SwitchVersion` is `24.0` or higher.
+- A script expression has no manifest. It always runs on the newest Node.js the running Switch
+  bundles.
+
+> **Mac (Apple Silicon):** For scripts whose `SwitchVersion` is `21.1` (Switch 2021 Fall) or later, Switch runs the native ARM build of Node.js on Apple Silicon. Scripts with an earlier `SwitchVersion` run under Rosetta, because the bundled Node.js 12 and 14 are Intel-only builds. If a script bundles platform-specific binaries, ship both Intel and ARM variants.

package/docs/switch-project/project-planning.md

@@ -0,0 +1,149 @@
+---
+id: project-planning
+category: switch-project
+order: 1
+summary: "Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
+triggers:
+  - "Starting a new script or app, before scaffolding any files, or working in a script folder that is already scaffolded where Script vs App has not been settled"
+---
+
+# Project Planning
+
+A planning checklist for a new script or app. Work through this with the user before
+creating any files.
+
+A script folder that already exists (scaffolded by the user, SwitchScripter, or `SwitchScriptTool
+--create`) does not skip the checklist. The manifest's `ScriptPackageType` is always `Script` in a
+scaffolded folder, so it does not answer item 1. Ask Script or App anyway, and run the other
+checks against the code that exists. The goal is to make a few decisions deliberately up front, because retrofitting
+them after code exists is expensive: password protection and localization for an app, path handling
+for a second target OS, synchronizing shared-resource access for concurrency, or restructuring entry
+points around a job-processing approach chosen too casually.
+
+Two items below are direct questions for the user. The rest are not questions to ask upfront; they
+are checks the agent runs against what's actually being built, raised only when they become
+relevant.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Ask the user directly
+  - 1. Script or App?
+  - 2. What should job processing look like in their flow?
+- Evaluate and flag, don't ask upfront
+  - One script folder or several
+  - Target OS
+  - Switch version baseline (apps only)
+  - Concurrency
+  - Native or binary npm dependencies
+  - Appstore competition risk (apps only)
+<!-- docs-index:contents end -->
+
+## Ask the user directly
+
+### 1. Script or App?
+
+Ask whether this is for private or internal use (a plain `Script`, distributed freely) or intended
+for the Enfocus Appstore (an `App`). See
+[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 [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 [app-guidelines.md § Localization](../switch-appstore/app-guidelines.md#localization).
+
+### 2. What should job processing look like in their flow?
+
+Ask about job handling at a functional level: what should happen when a job arrives, does anything
+need to wait on an external process or resource, could more than one job at a time contend for a
+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
+[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
+[entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
+
+## Evaluate and flag, don't ask upfront
+
+### One script folder or several
+
+One script folder produces one flow element. Once the job-processing design from question 2 is
+clear, check whether it needs more than one flow element: distinct steps a flow builder should
+place and configure as separate elements, or several related apps meant to ship as an app bundle.
+Most designs need one, so don't ask about this upfront.
+
+If the design needs several, propose the split before creating any files: the Script ID and
+purpose of each script folder and, for apps, whether they form an app bundle. Wait for the user to
+confirm. Then lay them out and create them as described in
+[script-structure.md § Several script folders side by side](script-structure.md#several-script-folders-side-by-side).
+
+### Target OS
+
+Switch Server runs on Windows and macOS. Default to writing platform-independent code (the `path`
+module, no hardcoded separators, see
+[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.
+
+### Switch version baseline (apps only)
+
+Once Script vs App is answered as App, ask or infer the oldest Switch version the app must support.
+This sets two separate limits:
+
+- Which SwitchScripter build is needed to produce a compatible `.enfpack`, and so which Node.js
+  version the app runs on (see
+  [node-versions.md](node-versions.md)).
+  Write code for that Node.js version.
+- Which scripting API methods the code may call. Methods follow the Switch version the app runs on,
+  so check every call against [api-versions.md](../switch-api/api-versions.md) for the oldest
+  supported version.
+
+Don't ask this for a plain script. Assume it runs on the Switch version whose SwitchScriptTool packs
+it (`SwitchScriptTool --version`), unless the user mentions an older Switch Server.
+
+### Concurrency
+
+Default to `Concurrent` execution; it's the preferred choice for apps per
+[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
+[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
+[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
+[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)
+
+An app whose core functionality duplicates an existing Switch module without requiring that module
+risks Appstore rejection. For example, an app that performs database CRUD operations without
+requiring the Database Module competes directly with it. If the planned app looks like it falls into
+this category, say so before significant effort is spent, and suggest either gating the app behind
+the relevant module license or contacting Enfocus to check before proceeding.
+
+---
+
+This checklist stops at planning. Once these are answered, move to
+[script-structure.md](script-structure.md) to scaffold the project.

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

@@ -0,0 +1,75 @@
+---
+id: property-documentation
+category: switch-project
+order: 21
+summary: "Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections"
+triggers:
+  - "Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo`"
+---
+
+# 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).