@enfocussw/switch-scripting-context 25.11.0-beta.8 → 25.11.1-beta.0

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

@@ -0,0 +1,258 @@
+---
+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 [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.
+
+Items fall into three tiers, marked on each one:
+
+- **Universal** — a correctness rule for every script, app or not. Violating it is a bug, not a
+  style choice.
+- **Apps required / scripts recommended** — mandatory for Appstore review; worth following in a
+  plain `Script` too, but not enforced there.
+- **Apps only** — doesn't apply to a plain `Script` package at all.
+
+---
+
+## Properties
+
+- [ ] **Apps required / scripts recommended.** Every property name (`LocalizedTagName`) is 30
+  characters or fewer and uses sentence-style capitalization ("Customer name", not "Customer
+  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
+  [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
+  [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
+  [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 [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
+  [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
+  [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
+  [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 [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 [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
+  [entry-points.md § Job processing](../switch-api/entry-points.md#job-processing).
+
+## Sending jobs
+
+All **universal** — see
+[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
+  any job actually routed (a purely timer/event-driven script that never touches a job is a
+  legitimate exception).
+- [ ] If `OutgoingConnections="Unlimited"`, `job.sendToSingle()` is never used.
+- [ ] `ConnectionType="Move"` never uses `job.sendToData()`/`job.sendToLog()`.
+- [ ] `ConnectionType="TrafficLight"` uses only `job.sendToData()`/`job.sendToLog()`; `sendToData`
+  is used when a Data Success/Warning/Error connection is enabled, `sendToLog` when the
+  corresponding Log connection is enabled.
+- [ ] An unused Success/Warning/Error connection is omitted from `ConnectionFields` entirely, not
+  left declared but unrouted.
+- [ ] A job with no output calls `job.sendToNull()`.
+- [ ] `job.fail()`/`flowElement.failProcess()` is used for genuine processing errors; an error
+  `TrafficLight` connection isn't used as a substitute for `fail()`.
+
+## Logging
+
+- [ ] **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 [logging.md § Message quality](../switch-api/logging.md#message-quality).
+- [ ] **Universal.** Log messages are free of grammatical errors and typos — see
+  [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
+  [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
+  [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
+  [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
+  [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
+  [job-patterns.md § Platform-independent paths](../switch-api/job-patterns.md#platform-independent-paths).
+
+---
+
+## App-only
+
+The following apply only to `ScriptPackageType="App"`, not to a plain `Script` package at all.
+Unlike the sections above, these are documented in full here rather than deferring elsewhere.
+
+### Identity and versioning
+
+- [ ] **`Name` (Script ID) matches `[A-Za-z0-9_-]+`** — letters, digits, hyphens and underscores
+  only, no spaces. It must also be globally unique across the Appstore; Enfocus checks for clashes
+  at review and may require a change. Pick something unlikely to collide.
+- [ ] **`Name` never changes across versions.** It is what identifies the app in an existing
+  customer flow, so changing it breaks the upgrade path. `DisplayName` *can* change freely between
+  versions without breaking upgrades — so keep any third-party application version number out of
+  `Name`, and preferably out of `DisplayName` too, or every application release forces a rename.
+- [ ] **`Version` is only incremented once the previous version was actually published.** If a
+  submission is rejected, resubmit under the *same* version number rather than bumping. Minor
+  versions are allowed to one level (`1.1`, `1.10`, `1.34`); leading zeros are not (`1.01` is
+  invalid).
+- [ ] **Every app in an app bundle carries the same version**, including the master app entry.
+- [ ] **The pack ID always starts with `com.enfocus.`**, generated from the script ID, regardless
+  of the company name and domain set in SwitchScripter preferences. To keep it stable when
+  updating, open the existing `.enfpack` (not the `.sscript`) before re-packing — SwitchScripter
+  remembers the pack ID from the pack it opened.
+
+### Top-level declaration properties
+
+- [ ] **App-level `Tooltip` is filled in** — this is the tooltip on the icon in the Elements pane,
+  separate from the per-property tooltips above.
+- [ ] **`Keywords` is populated and matches the keywords on the app's Appstore detail page.** Words
+  already in `DisplayName` are implicitly searchable and don't need repeating. Matching is
+  case-insensitive.
+- [ ] **`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
+  [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.
+- [ ] **`PerformanceTuning="Yes"` only with a concrete reason.** It exposes `IdleAfterJob` (and
+  `NumberOfSlots`) to the user; don't surface those knobs by default.
+- [ ] **At most three categories, and `SubcategoryInElementPane` is filled in.** New categories need
+  Enfocus Product Management approval, and an app listed in more than three needs additional
+  approval. Note that an unsigned app always loads under the **Custom** subcategory regardless of
+  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 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 — 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
+  script does not read a dependent property's value when its master isn't set to the value that
+  makes it relevant.
+
+### Password protection
+
+- [ ] **The app is password protected with a non-trivial password** (8+ characters, mixed case,
+  digits, symbols). Enfocus checks the password strength at review.
+- [ ] **Don't lose the password.** For a Node.js app, Switch runs an obfuscated copy of the code
+  produced at save time and never needs the original source, so the protection is genuinely
+  one-way: Enfocus cannot recover a Node.js script's source if the author forgets the password.
+  (For legacy JavaScript/VBScript a bypass mechanism exists internally at Enfocus, so that
+  protection is weaker — another reason to be on Node.js.)
+- [ ] Note that a published Node.js app ships only the obfuscated code, re-protected with a random
+  password Enfocus generates during review — not the password you set.
+
+### Localization
+
+- [ ] **Prefer more than one language.** An app is preferably localized beyond English — see
+  [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
+  generated through the SDK.
+- [ ] **Translations must be complete, and logging must go through the translation mechanism.** A
+  partially-translated app (some strings translated, others not) is not acceptable — every
+  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 [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 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
+
+- [ ] **macOS Mach-O binaries in extra files (`Resources/`) must be universal.** Any bundled macOS
+  application, framework bundle, executable, or dynamic library must include both `x86_64` and
+  `arm64` architectures. Relying on Rosetta 2 costs performance and isn't a long-term option.
+- [ ] **macOS Mach-O binaries in extra files must be signed and notarized.** An unsigned or
+  incorrectly signed executable or dynamic library will fail Appstore review. At minimum, sign with
+  hardened runtime enabled and a secure timestamp; verify with `codesign -dv <file>` and check the
+  output contains a `Timestamp` line and the `runtime` flag on the `CodeDirectory` line.
+- [ ] **Extra files must not change at runtime.** Don't place files the script might modify or
+  regenerate at runtime — license files included — inside the app's own package folder. Switch
+  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
+  [job-patterns.md § Temp file cleanup](../switch-api/job-patterns.md#temp-file-cleanup).
+- [ ] Find bundled files at runtime with `flowElement.getPluginResourcesPath()` — see
+  [flow-element.md](../switch-api/flow-element.md).
+
+### Source and review hygiene
+
+- [ ] **Comments in the source are in English**, so Enfocus reviewers can read them.
+- [ ] **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
+  [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.
+
+### What review does and doesn't cover
+
+Enfocus verifies that the app loads correctly and becomes available as a flow element, and checks
+the items above. It does **not** test that the app works — functional correctness, error handling,
+code structure and naming are the app creator's responsibility, though good practice in all of them
+is assumed. Items marked as rejection-triggers in the SDK's own checklist are the identity,
+password, icon, signing and architecture ones above.
+
+Budget roughly **10 business days** for a review. An unsigned app only loads in Switch on the
+machine that created it, which is what makes local testing possible before submission; once signed
+it loads anywhere. Apps require Switch 13.1 or later.

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

@@ -0,0 +1,117 @@
+---
+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
+creating any files. 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.
+
+## 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
+
+### 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
+  [script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)).
+  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.