@aryacode/dsh-engineering 0.6.0 → 0.8.0

package/vendor/ftview/lib/schema.js

@@ -0,0 +1,156 @@
+/**
+ * Validate display XML against the installed FactoryTalk View schema.
+ *
+ * The vendor ships `Gfx-ME*.xsd` with Studio. Rather than re-implement an XSD
+ * engine, this module asks .NET (through PowerShell) to validate in process,
+ * which is exact and needs no third-party package. When the schema or the host
+ * is unavailable the caller gets a clear `schema_unavailable` result instead of
+ * a silent pass.
+ *
+ * @module dsh-engineering-ftview/schema
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where Studio installs its display schemas. */
+const SCHEMA_ROOTS = [
+    'C:/Program Files (x86)/Rockwell Software/RSView Enterprise/Schemas',
+    'C:/Program Files/Rockwell Software/RSView Enterprise/Schemas',
+];
+/** Coverage note shared by every schema-dependent operation. */
+export const SCHEMA_COVERAGE = {
+    complete: false,
+    unverified: [
+        'sequence order and occurrence counts are enforced by Studio, not by this check',
+        'Studio import and runtime behaviour',
+        'semantic intent of the logic behind a display',
+    ],
+};
+/** The schema directory, or undefined when Studio is not installed here. */
+export function schemaDirectory() {
+    const override = process.env.FTVIEW_SCHEMA_DIR;
+    if (override !== undefined && override !== '')
+        return existsSync(override) ? override : undefined;
+    return SCHEMA_ROOTS.find(root => existsSync(root));
+}
+/** Every installed schema version, newest last. */
+export function schemaVersions() {
+    const directory = schemaDirectory();
+    if (directory === undefined)
+        return [];
+    const version = (name) => Number.parseInt(name.replace(/\D+/gu, ''), 10);
+    return readdirSync(directory)
+        .filter(name => /^Gfx-ME\d+\.xsd$/iu.test(name))
+        .sort((left, right) => version(left) - version(right));
+}
+/** The declared schema of one display, from `xsi:noNamespaceSchemaLocation`. */
+export function declaredSchema(xml) {
+    const match = /xsi:noNamespaceSchemaLocation\s*=\s*"([^"]+)"/u.exec(xml);
+    return match?.[1];
+}
+/**
+ * Pick the schema file for one document.
+ *
+ * A display names its schema; if that file is not installed, the newest
+ * installed schema is used and the caller is told which one ran.
+ *
+ * @param xml - Display XML, used only for its declared schema.
+ * @returns Absolute schema path and its file name, or undefined.
+ */
+export function schemaFor(xml) {
+    const directory = schemaDirectory();
+    if (directory === undefined)
+        return undefined;
+    const declared = declaredSchema(xml);
+    if (declared !== undefined && existsSync(join(directory, declared)))
+        return { path: join(directory, declared), name: declared };
+    const versions = schemaVersions();
+    if (versions.length === 0)
+        return undefined;
+    const newest = versions[versions.length - 1];
+    return { path: join(directory, newest), name: newest };
+}
+/** PowerShell that validates a batch of XML strings against one schema. */
+const VALIDATOR = `
+$ErrorActionPreference = 'Stop'
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$schemas = New-Object System.Xml.Schema.XmlSchemaSet
+$null = $schemas.Add('', [string]$payload.schema)
+$results = New-Object System.Collections.ArrayList
+foreach ($item in $payload.items) {
+  $messages = New-Object 'System.Collections.Generic.List[string]'
+  $settings = New-Object System.Xml.XmlReaderSettings
+  $settings.ValidationType = [System.Xml.ValidationType]::Schema
+  $settings.Schemas = $schemas
+  $settings.ValidationFlags = $settings.ValidationFlags -bor [System.Xml.Schema.XmlSchemaValidationFlags]::ReportValidationWarnings
+  $handler = [System.Xml.Schema.ValidationEventHandler]{ param($sender, $eventArgs) $messages.Add("$($eventArgs.Severity): $($eventArgs.Message)") }
+  $settings.add_ValidationEventHandler($handler)
+  $reader = [System.Xml.XmlReader]::Create((New-Object System.IO.StringReader([string]$item.xml)), $settings)
+  try { while ($reader.Read()) { } } catch { $messages.Add("error: $($_.Exception.Message)") } finally { $reader.Dispose() }
+  [void]$results.Add([pscustomobject]@{ file = [string]$item.file; messages = @($messages) })
+}
+$results | ConvertTo-Json -Depth 4 -Compress
+`;
+/**
+ * Validate one batch of display documents against the installed schema.
+ *
+ * @param documents - Documents to check; an empty list runs nothing.
+ * @param executable - PowerShell to use; defaults to `powershell.exe`.
+ * @returns Findings, whether validation ran, and the schema used.
+ */
+export async function validateSchema(documents, executable = 'powershell.exe') {
+    if (documents.length === 0)
+        return { findings: [], ran: true };
+    // Only Studio documents declare a schema. A hand-made <display> file is not
+    // one, and validating it against Gfx-ME would report a root element the
+    // fixture never claimed to be. Such files are skipped, with a reason.
+    const declared = documents.filter(document => declaredSchema(document.xml) !== undefined);
+    if (declared.length === 0) {
+        return {
+            findings: [],
+            ran: false,
+            unavailable: 'None of the changed documents declares xsi:noNamespaceSchemaLocation, so there is no vendor schema to validate against. Studio exports and authored displays always declare one.',
+        };
+    }
+    const first = declared[0];
+    const schema = schemaFor(first.xml);
+    if (schema === undefined) {
+        return {
+            findings: [],
+            ran: false,
+            unavailable: 'No Gfx-ME*.xsd schema is installed on this host. Install FactoryTalk View Studio, or set FTVIEW_SCHEMA_DIR to the folder that holds Gfx-ME*.xsd.',
+        };
+    }
+    const payload = JSON.stringify({ schema: schema.path, items: declared });
+    const encoded = Buffer.from(VALIDATOR, 'utf16le').toString('base64');
+    const output = await runPowerShell(executable, ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], payload);
+    if (output.code !== 0) {
+        return {
+            findings: [],
+            ran: false,
+            schema: schema.name,
+            unavailable: `The schema validator did not run: ${output.stderr.trim() || `exit ${output.code}`}`,
+        };
+    }
+    const parsed = JSON.parse(output.stdout);
+    const findings = [];
+    for (const result of Array.isArray(parsed) ? parsed : [parsed]) {
+        for (const message of result.messages ?? []) {
+            findings.push({ file: result.file, message, error: message.startsWith('Error') || message.startsWith('error:') });
+        }
+    }
+    return { findings, ran: true, schema: schema.name };
+}
+/** Run one process with stdin and collect its output. */
+function runPowerShell(executable, args, stdin) {
+    return new Promise(resolvePromise => {
+        const child = spawn(executable, args, { windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+        child.stderr?.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+        child.on('error', error => resolvePromise({ code: -1, stdout, stderr: stderr || error.message }));
+        child.on('close', code => resolvePromise({ code: code ?? -1, stdout, stderr }));
+        child.stdin?.end(stdin, 'utf8');
+    });
+}

package/vendor/ftview/lib/vendor-tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tools that reach the installed ME engine.
+ *
+ * These are the only entry points that talk to Studio's world: listing the
+ * applications it knows and exporting one to a folder. Both are read-only with
+ * respect to the project.
+ *
+ * @module dsh-engineering-ftview/vendor-tools
+ */
+import { type FsService, type ToolDefinition } from './core.ts';
+/**
+ * The vendor tools.
+ *
+ * @param fs - Filesystem provider used to resolve the destination folder.
+ * @returns Tool definitions.
+ */
+export declare function vendorTools(fs: FsService): readonly ToolDefinition[];

package/vendor/ftview/lib/vendor-tools.js

@@ -0,0 +1,74 @@
+/**
+ * Tools that reach the installed ME engine.
+ *
+ * These are the only entry points that talk to Studio's world: listing the
+ * applications it knows and exporting one to a folder. Both are read-only with
+ * respect to the project.
+ *
+ * @module dsh-engineering-ftview/vendor-tools
+ */
+import { existsSync } from 'node:fs';
+import { EngineeringError, object, optionalString, requiredString, string, success, tool } from "./core.js";
+import { exportApplication, listApplications } from "./vendor.js";
+/** What a vendor call cannot prove. */
+const VENDOR_COVERAGE = {
+    complete: false,
+    unverified: [
+        'the exported XML is a snapshot of the saved application, not of a running terminal',
+        'display compile and download to a PanelView terminal',
+        'Studio import behaviour',
+    ],
+};
+/**
+ * The vendor tools.
+ *
+ * @param fs - Filesystem provider used to resolve the destination folder.
+ * @returns Tool definitions.
+ */
+export function vendorTools(fs) {
+    return [
+        tool({
+            name: 'ftview_apps',
+            description: 'List the FactoryTalk View ME applications installed on this host, through the vendor export server. Requires FactoryTalk View ME on the machine.',
+            parameters: object({
+                filter: string('Case-insensitive substring matched against the application name.'),
+            }, []),
+            async run(args) {
+                const filter = (optionalString(args, 'filter') ?? '').toLowerCase();
+                const listed = await listApplications();
+                if (listed.error !== undefined) {
+                    throw new EngineeringError('VENDOR_UNAVAILABLE', listed.error, 'Install FactoryTalk View ME Studio on this host, or work from an existing export folder.');
+                }
+                const apps = (listed.value ?? []).filter(app => filter === '' || app.name.toLowerCase().includes(filter));
+                return success(`${apps.length} ME application(s)${filter === '' ? '' : ` matching ${JSON.stringify(filter)}`} on this host.`, { total: apps.length, apps }, [{ tool: 'ftview_export', args: { application: apps[0]?.name ?? 'NAME', output_root: 'C:/Exports/NAME' }, why: 'Export one application to a folder this surface can read.' }], VENDOR_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_export',
+            description: 'Export one installed ME application (displays, global objects, tags) to a NEW folder through the vendor export server. The application is not modified.',
+            parameters: object({
+                application: string('Application name as ftview_apps lists it.'),
+                output_root: string('New folder for the export. It must not exist.'),
+            }, ['application', 'output_root']),
+            async run(args, exec) {
+                const application = requiredString(args, 'application');
+                const requested = requiredString(args, 'output_root');
+                const destination = await fs.resolve(requested, {
+                    ...(exec.cwd === undefined ? {} : { cwd: exec.cwd }),
+                    ...(exec.signal === undefined ? {} : { signal: exec.signal }),
+                });
+                if (existsSync(destination)) {
+                    throw new EngineeringError('OUTPUT_EXISTS', `A file or folder already exists at ${requested}.`, 'Pass a new output_root; export never merges into an existing folder.');
+                }
+                const exported = await exportApplication(application, destination);
+                if (exported.error !== undefined) {
+                    throw new EngineeringError('VENDOR_EXPORT_FAILED', exported.error, 'Check that the application is not open in Studio, then retry with a new output_root.');
+                }
+                const files = exported.value ?? [];
+                const displays = files.filter(file => /\/Displays\/.+\.xml$/iu.test(file) && !/batchimport/iu.test(file));
+                const manifests = files.filter(file => /batchimport/iu.test(file));
+                return success(`Exported ${application}: ${files.length} file(s), ${displays.length} display(s)${manifests.length === 0 ? '' : `, ${manifests.length} import manifest(s)`}.`, { application, output_root: destination, files, display_count: displays.length, manifests }, [{ tool: 'ftview_open', args: { root: destination }, why: 'Open the fresh export and author against it.' }], VENDOR_COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/ftview/lib/vendor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Drive the installed FactoryTalk View ME engine.
+ *
+ * Studio ships two scriptable COM servers that matter here: `MEExportSvr`
+ * (list applications, export displays) and `AppMgrServer` (backup and restore).
+ * The export server runs out of process and works from a 64-bit host; the
+ * application manager is a 32-bit in-process server, so it is reached through
+ * the 32-bit PowerShell. Nothing here edits a project: export reads, backup
+ * copies.
+ *
+ * @module dsh-engineering-ftview/vendor
+ */
+/** CLSID of the ME export server (`MEExport.exe`). */
+export declare const EXPORT_CLSID = "9d882577-aa92-466b-a749-6d6b5093b623";
+/** CLSID of the application manager (`ApplicationManagerServer.dll`). */
+export declare const APP_MANAGER_CLSID = "4fead81a-cd72-42da-b659-f1a41499f0f9";
+/** One installed ME application. */
+export interface MeApplication {
+    /** Application name as Studio stores it. */
+    readonly name: string;
+    /** Target platform when the engine reports one. */
+    readonly platform?: string;
+    /** Version string when the engine reports one. */
+    readonly version?: string;
+}
+/** Result of one vendor call. */
+export interface VendorResult<T> {
+    /** Parsed value on success. */
+    readonly value?: T;
+    /** Human-readable failure. */
+    readonly error?: string;
+}
+/**
+ * List every ME application the engine knows.
+ *
+ * @returns Applications, or the reason the engine could not be reached.
+ */
+export declare function listApplications(): Promise<VendorResult<readonly MeApplication[]>>;
+/**
+ * Export one application's displays and globals into a new folder.
+ *
+ * @param application - Application name as listed.
+ * @param destination - Folder to create and fill.
+ * @returns Files written, relative to the destination.
+ */
+export declare function exportApplication(application: string, destination: string): Promise<VendorResult<readonly string[]>>;
+/**
+ * Back one application up to a zip.
+ *
+ * @param application - Application name.
+ * @param zipPath - Destination zip; must not exist.
+ * @returns The zip path on success.
+ */
+export declare function backupApplication(application: string, zipPath: string): Promise<VendorResult<string>>;
+/** Size of one file, for reports. */
+export declare function fileSize(path: string): number;

package/vendor/ftview/lib/vendor.js

@@ -0,0 +1,143 @@
+/**
+ * Drive the installed FactoryTalk View ME engine.
+ *
+ * Studio ships two scriptable COM servers that matter here: `MEExportSvr`
+ * (list applications, export displays) and `AppMgrServer` (backup and restore).
+ * The export server runs out of process and works from a 64-bit host; the
+ * application manager is a 32-bit in-process server, so it is reached through
+ * the 32-bit PowerShell. Nothing here edits a project: export reads, backup
+ * copies.
+ *
+ * @module dsh-engineering-ftview/vendor
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** CLSID of the ME export server (`MEExport.exe`). */
+export const EXPORT_CLSID = '9d882577-aa92-466b-a749-6d6b5093b623';
+/** CLSID of the application manager (`ApplicationManagerServer.dll`). */
+export const APP_MANAGER_CLSID = '4fead81a-cd72-42da-b659-f1a41499f0f9';
+/** Where the 32-bit PowerShell lives on this host. */
+function powershell32() {
+    const path = join(process.env.WINDIR ?? 'C:/Windows', 'SysWOW64/WindowsPowerShell/v1.0/powershell.exe');
+    return existsSync(path) ? path : 'powershell.exe';
+}
+/** Run a PowerShell script with a JSON payload on stdin. */
+function runPowerShell(executable, script, payload) {
+    const encoded = Buffer.from(script, 'utf16le').toString('base64');
+    return new Promise(resolvePromise => {
+        const child = spawn(executable, ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], { windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+        child.stderr?.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+        child.on('error', error => resolvePromise({ code: -1, stdout, stderr: stderr || error.message }));
+        child.on('close', code => resolvePromise({ code: code ?? -1, stdout, stderr }));
+        child.stdin?.end(JSON.stringify(payload), 'utf8');
+    });
+}
+/** Script that lists applications through the export server. */
+const LIST_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$p = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$t = [Type]::GetTypeFromCLSID([guid]$p.clsid)
+$o = [Activator]::CreateInstance($t)
+$names = @($o.GetMEAppNames())
+$apps = @()
+foreach ($name in $names) {
+  $platform = $null; $version = $null
+  try { $info = @($o.GetAppInfo([string]$name)); if ($info.Count -gt 0) { $platform = [string]$info[0] }; if ($info.Count -gt 1) { $version = [string]$info[1] } } catch { }
+  $apps += [pscustomobject]@{ name = [string]$name; platform = $platform; version = $version }
+}
+[pscustomobject]@{ apps = $apps } | ConvertTo-Json -Depth 4 -Compress
+`;
+/** Script that exports one application's displays. */
+const EXPORT_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$p = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$t = [Type]::GetTypeFromCLSID([guid]$p.clsid)
+$o = [Activator]::CreateInstance($t)
+$o.LoadMEApp([string]$p.app)
+try { $o.ExportAll([string]$p.dest) } finally { $o.UnloadMEApp() }
+[pscustomobject]@{ ok = $true } | ConvertTo-Json -Compress
+`;
+/** Script that backs one application up to a zip through the application manager. */
+const BACKUP_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$p = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$t = [Type]::GetTypeFromCLSID([guid]$p.clsid)
+$o = [Activator]::CreateInstance($t)
+$o.BackupLocal([string]$p.app, [string]$p.zip, '', 'ME')
+[pscustomobject]@{ ok = $true } | ConvertTo-Json -Compress
+`;
+/**
+ * List every ME application the engine knows.
+ *
+ * @returns Applications, or the reason the engine could not be reached.
+ */
+export async function listApplications() {
+    const result = await runPowerShell('powershell.exe', LIST_SCRIPT, { clsid: EXPORT_CLSID });
+    if (result.code !== 0)
+        return { error: `The ME export server is unavailable: ${result.stderr.trim() || `exit ${result.code}`}` };
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return { value: parsed.apps ?? [] };
+    }
+    catch {
+        return { error: 'The ME export server returned an unreadable answer.' };
+    }
+}
+/**
+ * Export one application's displays and globals into a new folder.
+ *
+ * @param application - Application name as listed.
+ * @param destination - Folder to create and fill.
+ * @returns Files written, relative to the destination.
+ */
+export async function exportApplication(application, destination) {
+    if (existsSync(destination))
+        return { error: `A file or folder already exists at ${destination}. Export into a new folder.` };
+    const result = await runPowerShell('powershell.exe', EXPORT_SCRIPT, { clsid: EXPORT_CLSID, app: application, dest: destination });
+    if (result.code !== 0)
+        return { error: `Export failed: ${result.stderr.trim() || `exit ${result.code}`}` };
+    if (!existsSync(destination))
+        return { error: 'The engine reported success but wrote no folder.' };
+    const files = [];
+    const walk = (directory, prefix) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(join(directory, entry.name), relative);
+            else
+                files.push(relative);
+        }
+    };
+    walk(destination, '');
+    return { value: files.sort() };
+}
+/**
+ * Back one application up to a zip.
+ *
+ * @param application - Application name.
+ * @param zipPath - Destination zip; must not exist.
+ * @returns The zip path on success.
+ */
+export async function backupApplication(application, zipPath) {
+    if (existsSync(zipPath))
+        return { error: `A file already exists at ${zipPath}.` };
+    const result = await runPowerShell(powershell32(), BACKUP_SCRIPT, { clsid: APP_MANAGER_CLSID, app: application, zip: zipPath });
+    if (result.code !== 0)
+        return { error: `Backup failed: ${result.stderr.trim() || `exit ${result.code}`}` };
+    if (!existsSync(zipPath))
+        return { error: 'The application manager reported success but wrote no zip.' };
+    return { value: zipPath };
+}
+/** Size of one file, for reports. */
+export function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/vendor/l5x/SKILL.md

@@ -56,12 +56,12 @@ this is a backup on request ("back up this project"). Build it as a copy plus
 
 ## Live reads
 
-The `l5x-live` entry reads declared scalar tags straight from a controller over EtherNet/IP, without Studio 5000, FactoryTalk Linx or the SDK. It may be disabled; if `poll_live_tags` is unavailable, say live reads are not enabled rather than trying another tool.
+`l5x-live` reads declared scalar tags over EtherNet/IP with no Studio, FactoryTalk Linx or SDK. If `poll_live_tags` is unavailable, say live reads are not enabled here.
 
-- `poll_live_tags` takes an explicit IPv4 address, a CPU slot and 1 to 16 declared scalar tags (`BOOL`, `INT`, `DINT`, `REAL`), and returns timestamped sweeps, quality and the controller identity.
+- `poll_live_tags` takes an explicit IPv4 address, a CPU slot and 1 to 16 declared scalars, and returns timestamped sweeps, quality and controller identity.
 - `start_plc_trend` samples the same way as a session-owned job the chart can follow; stop it through the job controls.
 - These are read-only. Never write controller data, force tags, toggle bits or edit online.
-- Report `live_logic_matches_export: "unverified"`: the read proves a value at a moment, not that the controller runs the exported logic, and sequential reads can miss transitions.
+- Report `live_logic_matches_export: "unverified"`: a read proves a value at a moment, not that the controller runs the export.
 
 ## Reporting
 
@@ -81,18 +81,38 @@ The `l5x-live` entry reads declared scalar tags straight from a controller over
 The `l5x-studio` entry adds offline SDK work; it may be disabled. Call `studio_sdk_status` before using it.
 
 - `export_acd_to_l5x` writes one new full L5X from an ACD. No controller contact.
-- `verify_offline_l5x` imports a full L5X into a new offline ACD and builds it. Build needs project revision 37 or later; `probe: true` attempts a lower revision and reports the SDK error. A Studio-exported L5X builds; an L5X produced by `export_acd_to_l5x` may be refused by the SDK as "no changes".
-- `build_acd_from_draft` imports one changed RLL or ST routine into a new ACD copy, builds it and exports it. The baseline must be an L5X exported from that ACD in this chat, and neither file may change afterwards.
+- `verify_offline_l5x` imports a full L5X into a new offline ACD and builds it. Build needs project revision 37+; `probe: true` tries a lower one and reports the SDK error. An L5X from `export_acd_to_l5x` may be refused as "no changes".
+- `build_acd_from_draft` imports one changed RLL or ST routine into a new ACD copy, builds and exports it. The baseline must be an L5X exported from that ACD in this chat; neither file may change.
 - `studio_review_evidence` checks program, routine and rung or line names and verbatim quotes before you report findings.
-- `controller_approval_status` reports whether this session can ask a human. `capture_controller_snapshot`, `change_controller_mode` and `download_project` each require per-call human approval of the exact controller, route and target, and proceed only on `allowed-once`; `download_project` accepts only a `verification_id` from a passed build in this chat.
+- `controller_approval_status` says whether this session can ask a human. `capture_controller_snapshot`, `change_controller_mode` and `download_project` need per-call approval of the exact target and proceed only on `allowed-once`; `download_project` takes a `verification_id` from a passed build in this chat.
 - `go_online`, `read_controller_mode` and `read_live_tag` are read-only and need no approval. Never write controller data, force tags, toggle bits or edit online.
 
 ## Editing
 
 Editing uses the `draft_*` family. It may be disabled in this profile; if a draft tool is unavailable, say editing is not enabled here rather than trying another tool.
 
-- One operation per call: `draft_rung`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member`, `draft_udt_description`. Each returns the draft id and the operation count.
+- One operation per call: `draft_rung`, `draft_rung_comment`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member`, `draft_udt_description`.
 - `draft_validate` prepares the accumulated draft against the project and returns its hash, diff summary and check findings. Read the findings before applying.
 - `draft_apply` writes the draft to ONE new `.L5X` path. It never overwrites an existing file.
 - After applying, reopen the written file with `open_project` to review it.
 - Drafts belong to this chat. Another chat starts with none, and an applied draft is cleared.
+
+## Generate
+
+Write ladder through the composer, not by inventing NeutralText.
+
+- `list_instructions` gives the mnemonic, category and operand slots with their kinds; read it before composing.
+- `compose_rung` builds one rung from a tree (`spec_json`) or a pattern (`start_stop_latch`, `fault_latch`, `ton_delay`, `interlock`), resolves every operand, type-checks each slot and parses its own output; anything unknown or mistyped is refused before staging.
+- Pass `program`, `routine`, `mode` and `rung` to stage it (plus `comment`); without them it returns text only.
+- `fault_latch` stages two rungs at `rung` and `rung + 1`; rung numbers are not renumbered, so pick free ones.
+
+## Documentation
+
+`document_project` writes a handover bundle into a NEW folder and never touches the export:
+
+- `PROJECT.md` — controller, revision, tasks, programs, counts;
+- `io.md` / `io.csv` — modules and module-data tags;
+- `tags.csv` and `tags-studio.csv` — every declared tag, and the `Tag Name,Description` shape Studio imports;
+- `rungs/<program>.md` — each rung's number, comment, NeutralText, instructions and resolved tags.
+
+The bundle is structure and citations, not prose: write the narrative yourself and use `draft_rung_comment` / `draft_tag_description` when it belongs in the project. No C&E, FAT/SAT or runtime proof.

package/vendor/l5x/lib/engine/change-set.d.ts

@@ -5,6 +5,7 @@ type Operation = {
     readonly routine: string;
     readonly rung: number;
     readonly text: string;
+    readonly comment?: string;
 } | {
     readonly operation: 'delete_rung';
     readonly program: string;
@@ -17,6 +18,13 @@ type Operation = {
     readonly rung: number;
     readonly text: string;
     readonly before_rung?: number;
+    readonly comment?: string;
+} | {
+    readonly operation: 'set_rung_comment';
+    readonly program: string;
+    readonly routine: string;
+    readonly rung: number;
+    readonly comment: string;
 } | {
     readonly operation: 'replace_st';
     readonly program: string;
@@ -59,7 +67,7 @@ type Operation = {
     readonly description: string;
 };
 /** Compact contract returned with validation errors and embedded in tool descriptions. */
-export declare const CHANGE_SET_HELP = "Operations (each also needs \"operation\"):\nreplace_rung {program,routine,rung,text}\ninsert_rung {program,routine,rung,text,before_rung?}\ndelete_rung {program,routine,rung}\nreplace_st {program,routine,code}\nadd_routine {program,name,language:\"RLL\"|\"ST\",code}\nadd_tag {scope,name,data_type,description,value? scalar, dimensions? \"4 2\", external_access? \"Read/Write\"|\"Read Only\"|\"None\"}\nset_tag_description {scope,name,description}\nadd_udt_member {udt,name,data_type,description}\nset_udt_description {udt,description}\nset_udt_member_description {udt,member,description}\nIdentifiers are at most 40 characters. Example: {\"version\":1,\"operations\":[{\"operation\":\"add_tag\",\"scope\":\"controller\",\"name\":\"SP_Start\",\"data_type\":\"REAL\",\"value\":80,\"description\":\"Start threshold\"}]}";
+export declare const CHANGE_SET_HELP = "Operations (each also needs \"operation\"):\nreplace_rung {program,routine,rung,text,comment?}\ninsert_rung {program,routine,rung,text,before_rung?,comment?}\ndelete_rung {program,routine,rung}\nset_rung_comment {program,routine,rung,comment}\nreplace_st {program,routine,code}\nadd_routine {program,name,language:\"RLL\"|\"ST\",code}\nadd_tag {scope,name,data_type,description,value? scalar, dimensions? \"4 2\", external_access? \"Read/Write\"|\"Read Only\"|\"None\"}\nset_tag_description {scope,name,description}\nadd_udt_member {udt,name,data_type,description}\nset_udt_description {udt,description}\nset_udt_member_description {udt,member,description}\nIdentifiers are at most 40 characters. Example: {\"version\":1,\"operations\":[{\"operation\":\"add_tag\",\"scope\":\"controller\",\"name\":\"SP_Start\",\"data_type\":\"REAL\",\"value\":80,\"description\":\"Start threshold\"}]}";
 /** Limits are resolved by the plugin's configuration before tools call this module. */
 export interface ChangeSetLimits {
     readonly operations: number;

package/vendor/l5x/lib/engine/change-set.js

@@ -9,12 +9,13 @@ import { uniqueRegion, xmlRegions } from "./xml-regions.js";
 /** Scalar types the plugin can create with a literal initial value. */
 const SCALAR_TYPES = new Set(['BOOL', 'SINT', 'INT', 'DINT', 'LINT', 'USINT', 'UINT', 'UDINT', 'ULINT', 'REAL', 'LREAL']);
 /** Operation names accepted by a version-1 change set. */
-const SUPPORTED_OPERATIONS = ['replace_rung', 'insert_rung', 'delete_rung', 'replace_st', 'add_routine', 'add_tag', 'set_tag_description', 'add_udt_member', 'set_udt_description', 'set_udt_member_description'];
+const SUPPORTED_OPERATIONS = ['replace_rung', 'insert_rung', 'delete_rung', 'set_rung_comment', 'replace_st', 'add_routine', 'add_tag', 'set_tag_description', 'add_udt_member', 'set_udt_description', 'set_udt_member_description'];
 /** Compact contract returned with validation errors and embedded in tool descriptions. */
 export const CHANGE_SET_HELP = `Operations (each also needs "operation"):
-replace_rung {program,routine,rung,text}
-insert_rung {program,routine,rung,text,before_rung?}
+replace_rung {program,routine,rung,text,comment?}
+insert_rung {program,routine,rung,text,before_rung?,comment?}
 delete_rung {program,routine,rung}
+set_rung_comment {program,routine,rung,comment}
 replace_st {program,routine,code}
 add_routine {program,name,language:"RLL"|"ST",code}
 add_tag {scope,name,data_type,description,value? scalar, dimensions? "4 2", external_access? "Read/Write"|"Read Only"|"None"}
@@ -104,17 +105,21 @@ function parseOne(value, declaredTypes) {
         case 'replace_rung':
         case 'insert_rung':
         case 'delete_rung': {
-            fields(row, row.operation === 'delete_rung' ? ['operation', 'program', 'routine', 'rung'] : row.operation === 'insert_rung' ? ['operation', 'program', 'routine', 'rung', 'text', 'before_rung'] : ['operation', 'program', 'routine', 'rung', 'text']);
+            fields(row, row.operation === 'delete_rung' ? ['operation', 'program', 'routine', 'rung'] : row.operation === 'insert_rung' ? ['operation', 'program', 'routine', 'rung', 'text', 'before_rung', 'comment'] : ['operation', 'program', 'routine', 'rung', 'text', 'comment']);
             const selected = { program: identifier(row, 'program'), routine: identifier(row, 'routine'), rung: integer(row, 'rung') };
             if (row.operation === 'delete_rung')
                 return { operation: row.operation, ...selected };
             const source = text(row, 'text');
             if (parseLadder(source).issues.length > 0)
                 throw new EngineeringError('INVALID_LADDER', 'Rung contains malformed or unsupported NeutralText structure');
+            const comment = row.comment === undefined ? {} : { comment: text(row, 'comment') };
             if (row.operation === 'replace_rung')
-                return { operation: row.operation, ...selected, text: source };
-            return { operation: row.operation, ...selected, text: source, ...(row.before_rung === undefined ? {} : { before_rung: integer(row, 'before_rung') }) };
+                return { operation: row.operation, ...selected, text: source, ...comment };
+            return { operation: row.operation, ...selected, text: source, ...comment, ...(row.before_rung === undefined ? {} : { before_rung: integer(row, 'before_rung') }) };
         }
+        case 'set_rung_comment':
+            fields(row, ['operation', 'program', 'routine', 'rung', 'comment']);
+            return { operation: row.operation, program: identifier(row, 'program'), routine: identifier(row, 'routine'), rung: integer(row, 'rung'), comment: text(row, 'comment') };
         case 'replace_st':
             fields(row, ['operation', 'program', 'routine', 'code']);
             return { operation: row.operation, program: identifier(row, 'program'), routine: identifier(row, 'routine'), code: text(row, 'code') };
@@ -314,7 +319,7 @@ function applyOperation(xml, operation, context) {
     if (operation.operation === 'insert_rung') {
         if (targets.length !== 0)
             throw new EngineeringError('NAME_COLLISION', 'Rung number already exists; no automatic renumbering is performed');
-        const newRung = `<Rung Number="${operation.rung}" Type="N"><Text>${cdata(operation.text)}</Text></Rung>`;
+        const newRung = `<Rung Number="${operation.rung}" Type="N">${commentXml(operation.comment)}<Text>${cdata(operation.text)}</Text></Rung>`;
         if (operation.before_rung === undefined)
             return insert(xml, content, newRung);
         const before = rungs.filter(rung => Number(rung.attributes.Number) === operation.before_rung);
@@ -327,9 +332,29 @@ function applyOperation(xml, operation, context) {
     const target = targets[0];
     if (operation.operation === 'delete_rung')
         return replace(xml, target.start, target.end, '');
+    if (operation.operation === 'set_rung_comment') {
+        return replace(xml, target.start, target.end, rungWith(target, retainedText(xml, target), operation.comment));
+    }
+    if (operation.comment !== undefined) {
+        return replace(xml, target.start, target.end, rungWith(target, `<Text>${cdata(operation.text)}</Text>`, operation.comment));
+    }
     const contentText = uniqueRegion(target.children, 'Text');
     return replace(xml, contentText.start, contentText.end, `<Text>${cdata(operation.text)}</Text>`);
 }
+/** A comment element, or nothing when the comment is cleared. */
+function commentXml(comment) {
+    return comment === undefined || comment === '' ? '' : `<Comment>${cdata(comment)}</Comment>`;
+}
+/** The rung's existing `<Text>` element, verbatim, for a comment-only edit. */
+function retainedText(xml, rung) {
+    const text = rung.children.find(child => child.kind === 'Text');
+    return text === undefined ? '<Text><![CDATA[]]></Text>' : xml.slice(text.start, text.end);
+}
+/** Rebuild one rung element with a comment and a text element. */
+function rungWith(rung, text, comment) {
+    const type = rung.attributes.Type ?? 'N';
+    return `<Rung Number="${rung.attributes.Number}" Type="${type}">${commentXml(comment)}${text}</Rung>`;
+}
 /** Every type name a change may reference: scalars plus declared types. */
 function declaredTypeNames(project) {
     const names = new Set([...SCALAR_TYPES].map(name => name.toLowerCase()));