@enfocussw/switch-scripting-context 25.11.1-beta.2 → 25.11.1-beta.4

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this package are documented here. Format follows
 
 ## [Unreleased]
 
+## [25.11.1-beta.4] - 2026-09-20
+
+### Added
+
+- Guidance in `docs/switch-project/property-editors.md` for a property whose shape varies by a
+  type selector. Declare an enum master and one dependent per shape instead of encoding JSON in a
+  single property, so each shape gets a native editor and most parsing disappears. Includes the
+  two constraints: the master must be static, and a hidden dependent throws when read.
+- A rule in `docs/switch-api/logging.md` against adding a script-level verbosity property. Switch
+  already gates `Debug` behind a preference, so the property duplicates a control the user has and
+  costs a pane row and translated strings.
+
+### Changed
+
+- `init` and `remove` now write to a docs folder named `docs-for-agents` instead of
+  `switch-docs`. Re-running `init` after an upgrade deletes the old folder, drops its gitignore
+  line, and repoints the generated AI config files, so no stale copy of the docs is left for an
+  agent to load. Pass `--docs-dir switch-docs` to keep the old name.
+- The `DetailedInfo` item in `docs/switch-appstore/app-guidelines.md` no longer reads as requiring
+  it on every property and connection. It is optional, matching what the property documentation
+  and app manual guidance already said, and points at the app manual as the surface users read.
+
+### Fixed
+
+- The secret property row in `docs/switch-project/property-editors.md` listed `password` as an
+  editor chain. It is a `Type`, and there is no such editor token, so following the row produced an
+  invalid declaration.
+- The array property row in `docs/switch-project/property-editors.md` claimed the chain always
+  returns a `string[]`, which the modal editor table contradicts. Both files now say the behaviour
+  is unverified and that code should handle a bare string too.
+
+## [25.11.1-beta.3] - 2026-09-17
+
+### Added
+
+- `init` now records the version that produced the docs on the first line of
+  `switch-scripting.md`, as an HTML comment reading `switch-scripting-context <version>`. A tool
+  that installs the docs can read it to tell which version a project has, including a checkout
+  someone else set up. Re-running `init` rewrites the line, and `--dry-run` prints it without
+  writing.
+
 ## [25.11.1-beta.2] - 2026-09-17
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
 
 Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
 
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.2/CHANGELOG.md) (also included in this package) for what's changed between versions.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.4/CHANGELOG.md) (also included in this package) for what's changed between versions.
 
 ## Usage
 
@@ -45,20 +45,25 @@ so the beta line precedes GA and leaves `25.11.0` free for the first published r
 
 ## What it does
 
-1. Copies the Switch API reference docs to `switch-docs/` in your project
+1. Copies the Switch API reference docs to `docs-for-agents/` in your project
 2. Generates AI config files for each tool (see below)
-3. Appends `switch-docs/` to `.gitignore`
+3. Appends `docs-for-agents/` to `.gitignore`
+
+Versions before this one used `switch-docs/` as the folder name. Re-running `init` deletes that
+folder and its `.gitignore` line, so your agents do not find a second, stale copy of the docs. It
+only deletes a `switch-docs/` folder that `init` itself wrote. Pass `--docs-dir switch-docs` to
+stay on the old name.
 
 ### Generated files
 
 | Tool | File | How context is loaded |
 |---|---|---|
-| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import; hub file routes to specific API docs on demand |
+| Claude Code / ClawCode | `CLAUDE.md` | `@docs-for-agents/switch-scripting.md` import; hub file routes to specific API docs on demand |
 | GitHub Copilot | `.github/copilot-instructions.md` | `#file:` reference to hub |
 | GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"`; auto-attaches to every TypeScript file edit |
 | Cursor | `.cursor/rules/switch-scripting.mdc` | Inline key rules + full API file path list |
 | Codex CLI / OpenCode | `AGENTS.md` | Inline key rules + full API file path list |
-| Gemini CLI | `GEMINI.md` | `@switch-docs/switch-scripting.md` import |
+| Gemini CLI | `GEMINI.md` | `@docs-for-agents/switch-scripting.md` import |
 | Windsurf | `.windsurfrules` | Inline key rules + full API file path list |
 | Zed | `.rules` | Inline key rules + full API file path list |
 | Cline | `.clinerules` | Inline key rules + full API file path list |
@@ -84,7 +89,7 @@ A few things this gets you without asking for them by name:
   properties (app path/licence) are off-limits and left to SwitchScripter's GUI instead.
 
 Re-run `init` after upgrading this package so the copied docs and generated config files catch up.
-See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.2/CHANGELOG.md) for what changed.
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.4/CHANGELOG.md) for what changed.
 
 ## Options
 
@@ -94,7 +99,7 @@ npx switch-scripting-context init [options]
   --tools <list>    Tools to configure. Default: all
                     IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline
                     Aliases: opencode (→ codex), clawcode (→ claude)
-  --docs-dir <dir>  Destination folder for docs. Default: switch-docs
+  --docs-dir <dir>  Destination folder for docs. Default: docs-for-agents
   --force           Overwrite existing AI config files instead of merging
   --dry-run         Print what would happen without writing any files
 ```
@@ -124,7 +129,7 @@ To undo `init`, run `remove`. By default it deletes the docs folder, the Switch
 npx switch-scripting-context remove [options]
 
   --tools <list>    Only remove these tools' config. Default: remove everything
-  --docs-dir <dir>  Docs folder to remove. Default: switch-docs
+  --docs-dir <dir>  Docs folder to remove. Default: docs-for-agents
   --dry-run         Print what would happen without writing any files
 ```
 
@@ -143,7 +148,7 @@ npm install --save-dev "https://github.com/enfocus-switch/types-switch-scripting
 
 ## Included docs
 
-The `switch-docs/` folder contains:
+The `docs-for-agents/` folder contains:
 
 - `switch-scripting.md`: master index with execution environment rules and "load when" routing table
 <!-- docs-index:readme begin -->

package/dist/init.d.ts

@@ -31,4 +31,15 @@ export declare function generateZedRules(docsDir: string): string;
 export declare function generateClineRules(docsDir: string): string;
 export declare function buildIdMap(registry: ToolDefinition[]): Map<string, string>;
 export declare function findMarkerRange(content: string): [number, number] | null;
+/** The running package's own version, so a git-clone install stamps what actually ran. */
+export declare function packageVersion(root?: string): string;
+/** The comment init writes as the first line of the copied hub file. */
+export declare function versionStamp(version: string): string;
+/**
+ * Drop the `docsDir/` line init added, together with the comment line directly above it.
+ * The comment and the path are matched as one unit so that a project carrying entries for
+ * two docs folders (one left by an older version, one current) keeps the comment belonging
+ * to the entry that stays.
+ */
+export declare function stripGitignoreEntry(content: string, docsDir: string): string;
 export declare function run(argv?: string[]): Promise<void>;

package/dist/init.js

@@ -42,6 +42,9 @@ exports.generateZedRules = generateZedRules;
 exports.generateClineRules = generateClineRules;
 exports.buildIdMap = buildIdMap;
 exports.findMarkerRange = findMarkerRange;
+exports.packageVersion = packageVersion;
+exports.versionStamp = versionStamp;
+exports.stripGitignoreEntry = stripGitignoreEntry;
 exports.run = run;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -90,6 +93,13 @@ const INLINE_CORE_RULES = `## Core rules
 - After editing \`main.ts\`, transpile with \`SwitchScriptTool --transpile <folder>\` — do not use \`tsc\` directly.
 - Never use a script folder in production — pack with \`SwitchScriptTool --pack\` first; folders are excluded from flow exports.`;
 // ─── Content generators ──────────────────────────────────────────────────────
+// Claude Code and Gemini CLI resolve @file imports themselves, so their generated
+// block is just a pointer to switch-scripting.md; the routing table and key rules
+// living there are the actual instructions. Codex, Windsurf, Zed, and Cline don't
+// reliably follow that import syntax, so their generators (generateInlineBlock)
+// paste INLINE_CORE_RULES and the routing table directly into the generated file
+// instead. Don't collapse these into one shared generator; the split is deliberate,
+// not duplication.
 function generateClaudeMd(docsDir) {
     return `${MARKER_BEGIN}
 ## Switch Scripting (Enfocus Switch)
@@ -365,6 +375,61 @@ function copyDocs(packageRoot, destDir, dryRun) {
     });
     console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
 }
+// ─── Version stamp ───────────────────────────────────────────────────────────
+/** The hub file in the copied docs folder that carries the version stamp. */
+const HUB_FILE = 'switch-scripting.md';
+/** The running package's own version, so a git-clone install stamps what actually ran. */
+function packageVersion(root = packageRoot()) {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+}
+/** The comment init writes as the first line of the copied hub file. */
+function versionStamp(version) {
+    return `<!-- switch-scripting-context ${version} -->`;
+}
+/**
+ * Records which version produced the copied docs, so a consumer can tell what is installed
+ * without having recorded it at install time. Only the copy is stamped: the repo's own
+ * docs/switch-scripting.md is generated output and a stamp there would fight the generator.
+ * copyDocs wipes destDir on every run, so there is never a stale stamp to remove.
+ */
+function stampDocsVersion(packageRoot, destDir, dryRun) {
+    const stamp = versionStamp(packageVersion(packageRoot));
+    const hubPath = path.join(destDir, HUB_FILE);
+    const rel = path.relative(process.cwd(), hubPath);
+    if (dryRun) {
+        console.log(`  [dry-run] ${rel} → first line ${stamp}`);
+        return;
+    }
+    fs.writeFileSync(hubPath, `${stamp}\n${fs.readFileSync(hubPath, 'utf8')}`, 'utf8');
+    console.log(`  ${rel} → stamped ${stamp}`);
+}
+// ─── Legacy docs folder ──────────────────────────────────────────────────────
+/** Docs folder name written by versions before the rename to docs-for-agents. */
+const LEGACY_DOCS_DIR = 'switch-docs';
+/**
+ * Delete the docs folder an older version wrote under its old name.
+ *
+ * init regenerates every AI config block in place, so after an upgrade the configs point at
+ * the new folder and nothing reads the old one. It is gitignored, so nothing surfaces it
+ * either, but an agent grepping the project still finds and loads the stale copy. The folder
+ * is only removed when it holds the hub file init writes, so a folder of the same name that
+ * this tool did not create is left alone.
+ */
+function removeLegacyDocsDir(targetRoot, docsDir, dryRun) {
+    if (docsDir === LEGACY_DOCS_DIR)
+        return;
+    const legacyDir = path.join(targetRoot, LEGACY_DOCS_DIR);
+    if (!fs.existsSync(path.join(legacyDir, HUB_FILE)))
+        return;
+    if (dryRun) {
+        console.log(`  [dry-run] ${LEGACY_DOCS_DIR}/ → deleted (docs folder from an earlier version)`);
+    }
+    else {
+        fs.rmSync(legacyDir, { recursive: true, force: true });
+        console.log(`  ${LEGACY_DOCS_DIR}/ → deleted (docs folder from an earlier version)`);
+    }
+    removeGitignoreEntry(targetRoot, LEGACY_DOCS_DIR, dryRun);
+}
 // ─── .gitignore update ───────────────────────────────────────────────────────
 function updateGitignore(targetRoot, docsDir, dryRun) {
     const gitignorePath = path.join(targetRoot, '.gitignore');
@@ -378,7 +443,10 @@ function updateGitignore(targetRoot, docsDir, dryRun) {
         console.log(`  [dry-run] .gitignore → append ${docsDir}/ entry`);
         return;
     }
-    fs.appendFileSync(gitignorePath, entry, 'utf8');
+    // entry opens with its own blank-line separator, so normalise what the file already
+    // ends with. Without this, appending after an entry that was just removed leaves a
+    // widening gap in the file on every upgrade.
+    fs.writeFileSync(gitignorePath, content.replace(/\n*$/, '\n') + entry, 'utf8');
     console.log(`  .gitignore → appended ${docsDir}/ entry`);
 }
 /** AI config files that init may have created, for all tools or only the given tool ids. */
@@ -442,15 +510,25 @@ function removeAiConfig(filePath, file, docsDir, targetRoot, dryRun) {
         console.log(`  ${rel} → removed Switch section`);
     }
 }
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Drop the `docsDir/` line init added, together with the comment line directly above it.
+ * The comment and the path are matched as one unit so that a project carrying entries for
+ * two docs folders (one left by an older version, one current) keeps the comment belonging
+ * to the entry that stays.
+ */
+function stripGitignoreEntry(content, docsDir) {
+    const pattern = new RegExp(`(\n# switch-scripting-context \\(AI context docs[^\n]*\\))?\n${escapeRegExp(docsDir)}/\n`, 'g');
+    return content.replace(pattern, '\n');
+}
 function removeGitignoreEntry(targetRoot, docsDir, dryRun) {
     const gitignorePath = path.join(targetRoot, '.gitignore');
     if (!fs.existsSync(gitignorePath))
         return;
     const content = fs.readFileSync(gitignorePath, 'utf8');
-    // Remove the comment line and the docsDir/ line added by init
-    const updated = content
-        .replace(/\n# switch-scripting-context \(AI context docs[^\n]*\)\n/g, '\n')
-        .replace(new RegExp(`\n${docsDir}/\n`, 'g'), '\n');
+    const updated = stripGitignoreEntry(content, docsDir);
     if (updated === content)
         return;
     if (dryRun) {
@@ -491,6 +569,7 @@ function remove(options) {
     else {
         console.log(`  ${options.docsDir}/ → not found, skipping`);
     }
+    removeLegacyDocsDir(targetRoot, options.docsDir, options.dryRun);
     // 2. Remove AI config sections / files
     console.log('\nCleaning AI config files...');
     for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir)) {
@@ -510,7 +589,9 @@ function init(options) {
         console.log('\nDry run — no files will be written.\n');
     // 1. Copy docs
     console.log('Copying docs...');
+    removeLegacyDocsDir(targetRoot, options.docsDir, options.dryRun);
     copyDocs(packageRoot, docsDestDir, options.dryRun);
+    stampDocsVersion(packageRoot, docsDestDir, options.dryRun);
     // 2. Generate AI config files
     const toolActions = [];
     for (const toolDef of TOOL_REGISTRY) {
@@ -542,12 +623,12 @@ function parseArgs(argv) {
     let toolsExplicit = false;
     const initOptions = {
         tools: TOOL_REGISTRY.map(t => t.id),
-        docsDir: 'switch-docs',
+        docsDir: 'docs-for-agents',
         force: false,
         dryRun: false,
     };
     const removeOptions = {
-        docsDir: 'switch-docs',
+        docsDir: 'docs-for-agents',
         dryRun: false,
     };
     for (let i = 1; i < args.length; i++) {
@@ -627,7 +708,7 @@ Options (init):
                     IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline
                     Aliases: opencode (→ codex), clawcode (→ claude)
                     Default: all tools
-  --docs-dir <dir>  Destination folder for docs in target project (default: switch-docs)
+  --docs-dir <dir>  Destination folder for docs in target project (default: docs-for-agents)
   --force           Overwrite existing AI config files rather than merging
   --dry-run         Print what would happen without writing any files
   --help            Show this help message
@@ -635,7 +716,7 @@ Options (init):
 Options (remove):
   --tools <list>    Only remove these tools' config; keeps the docs folder and other tools
                     Default: remove everything, same as listing every tool
-  --docs-dir <dir>  Docs folder to remove (default: switch-docs)
+  --docs-dir <dir>  Docs folder to remove (default: docs-for-agents)
   --dry-run         Print what would happen without writing any files
 
 Examples:

package/docs/switch-api/logging.md

@@ -24,6 +24,13 @@ and how often to log is a deliberate choice, not a default.
 | `Info` | Normal, expected checkpoints worth surfacing to a flow operator without them needing debug mode (e.g. "processed 40 records", "output written to X"). |
 | `Debug` | Verbose detail for diagnosing execution. Many users leave debug logging enabled in production to self-diagnose issues and to help app developers and Enfocus Support — leave meaningful checkpoints in, but trim noisy or no-longer-useful debug logs before shipping. **`Debug` messages only reach the log database if the Switch preference "Log debug messages" is turned on** (off by default) — see [logs-and-dataroot.md](../switch-project/logs-and-dataroot.md#retention-and-the-debug-level-gate). |
 
+## Don't add a verbosity property
+
+Switch already has the switch: `Debug` messages only reach the log database when the preference
+"Log debug messages" is on. A script-level "log detail" or "verbose logging" property duplicates a
+control the user already has, adds a row to the property pane, and (for an app) adds strings to
+translate. Put verbose detail behind `LogLevel.Debug` and let the preference govern it.
+
 ## Logging in loops
 
 Don't categorically avoid logging inside loops — per-item logs can matter (e.g. a per-job error).

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

@@ -162,11 +162,15 @@ Unlike the sections above, these are documented in full here rather than deferri
   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
+- [ ] **`DetailedInfo` is written wherever it adds something a `Tooltip` can't carry** — not
+  mechanically on every property. It is optional: 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, which is a reason to fill it in where the property warrants
+  it, not a reason to pad out every trivial one. See
   [property-documentation.md](../switch-project/property-documentation.md) for what to write in it, and when
-  it's fine to leave blank.
+  it's fine to leave blank. The [app manual](app-manual.md#flow-elements-properties) is the surface
+  users are far more likely to read, and it needs real per-property content regardless of what
+  `DetailedInfo` holds.
 - [ ] **`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

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

@@ -158,9 +158,9 @@ offer it as the property's only editor — pair it with a module-free option (e.
 
 | Property kind | Recommended `Editor` chain | Why |
 |---|---|---|
-| Secret (password, token, API key) | `password` only | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. |
+| Secret (password, token, API key) | `inline` only, with `Type="password"` | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. `password` is a `Type`, not an editor token — there is no `password` entry in the [modal editor](#modal-editors) list, so `Editor="password"` is wrong. |
 | Scalar job-specific value (job ID, copy count, company name, date, etc.) | `inline` (`Type` matching the value) + `sltextwithvar` + `scriptexp` | Hard-coded default, plus dynamic substitution and full expression evaluation. |
-| Array/list job-specific value | `stringlist` + `mltextwithvar` + `scriptexp` | One item per line; keeps both the hard-coded and dynamic paths returning a `string[]`. |
+| Array/list job-specific value | `stringlist` + `mltextwithvar` + `scriptexp` | One item per line. **Caveat:** the intent is that every path returns a `string[]`, but the [modal editor table](#modal-editors) lists `mltextwithvar` as returning a single string, and which one holds for this chain is unverified. Handle both — split on newlines when a bare string comes back. |
 | Structured blob text (XML/JSON/HTML, email body) | `description` + `mltextwithvar` + `scriptexp` | Free multi-line text suits a single blob of content better than a line-per-item list. |
 | Boolean used as a `Dependency` master | `inline` only | Other properties' visibility depends on a value known at design time. |
 | Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
@@ -174,6 +174,50 @@ offer it as the property's only editor — pair it with a module-free option (e.
 combined with `sltextwithvar`/`scriptexp` too, but this is uncommon in practice and not covered by a
 dedicated row above.
 
+### A property whose shape varies by a type selector
+
+When what a property must hold depends on another property's value — a map for one type, an
+ordered list for another, a pair of labelled strings for a third — don't reach for one property
+holding JSON or a hand-rolled line format. Declare an enum master and one dependent per shape, each
+with the editor that natively fits it, and read only the dependent the master currently shows.
+
+The shapes then need no parsing at all in the common cases, and the property pane shows one
+type-appropriate editor with a label that explains itself instead of a text box whose format lives
+in the documentation:
+
+```xml
+<!-- master: enum, inline only, so the value is known at flow-configuration time -->
+<QType UserDefined="true" Type="enum:(not used);List;Ordered;Pair" Editor="inline" Subtype="inline"
+       LocalizedTagName="Type" Tooltip="" DetailedInfo="" Validation="Standard"
+       Default="(not used)">(not used)</QType>
+
+<!-- one dependent per shape; each is hidden unless its condition holds -->
+<QList UserDefined="true" Type="stringlist" Editor="stringlist" Subtype="stringlist"
+       Dependency="QType" DependencyCondition="Equals" Dependencyvalue="List"
+       LocalizedTagName="Items" Tooltip="" DetailedInfo="" Validation="Standard"></QList>
+<QLow  UserDefined="true" Type="string" Editor="description" Subtype=""
+       Dependency="QType" DependencyCondition="Equals" Dependencyvalue="Pair"
+       LocalizedTagName="What a low value means" Tooltip="" DetailedInfo=""
+       Validation="Standard" Default=""></QLow>
+```
+
+Adding `(not used)` to the master's items makes it double as the group's on/off switch, so the
+group needs no separate boolean.
+
+Two constraints come with the pattern:
+
+- The master must be an enum or a boolean with `inline` only, per the rows above. A dynamic master
+  makes the visible set differ per job, which the dependents' own editors cannot account for.
+- Reading a hidden dependent throws `"Invalid tag: <tag>"`. Check the master's value, or call
+  `hasProperty(tag)`, before every read — see
+  [script-declaration.md § Dependency](script-declaration.md#custom-property-elements-elementfields).
+  This bites hardest in a loop over jobs or connections, where the throw repeats on every
+  invocation.
+
+A shape the master cannot enumerate, or one that must vary per job, is the case this pattern does
+not cover; that is where a single `description` property holding a structured blob is the honest
+answer.
+
 ---
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.1-beta.2",
+  "version": "25.11.1-beta.4",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",