@aryacode/dsh-engineering 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.7.0] - 2026-10-27
+
+### Added
+
+- **Ladder generation that cannot emit invalid NeutralText.** Three pieces:
+  - `list_instructions` — the instruction catalog the composer validates: mnemonic, category, summary
+    and operand slots with their kinds (BOOL, NUMBER, TIMER, …), filterable. 41 instructions, covering
+    every mnemonic the Laminator project uses (45 distinct across 860 rungs).
+  - `compose_rung` — builds one rung from a structure tree (`spec_json`) or a named pattern
+    (`start_stop_latch`, `fault_latch`, `ton_delay`, `interlock`), resolves every operand against the
+    export (including unqualified program tags and aliases), type-checks each slot, emits the export's
+    own bracket style, and re-parses its output with the same parser `draft_rung` uses. Unknown
+    instructions name the nearest catalog entries; a wrong operand count, a non-BOOL contact, a
+    non-numeric value slot, an undeclared tag or an undeclared AOI is refused before anything is staged.
+    Passing `program`, `routine`, `mode` and `rung` stages the rung in the draft; `fault_latch` stages
+    its two rungs consecutively.
+- **Rung comments are read and written.** The model read the `Comment` **attribute** only, so a real
+  Studio export's 572 child `<Comment>` elements were invisible. `decodeRung` now supports both shapes,
+  `draft_rung` accepts a `comment`, and `draft_rung_comment` sets or clears one on an existing rung.
+  CDATA terminators in a comment round-trip through the existing escaping.
+- **Documentation dimension.** `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`,
+  `tags.csv` and `tags-studio.csv` (the `Tag Name,Description` shape Studio's Tags and Comments import
+  expects), and `rungs/<program>.md` with each rung's number, comment, NeutralText, instructions and
+  resolved tags. Filters: `include`, `programs`, `routines`, `rungs_per_file`.
+
+### Documentation
+
+- `packages/l5x/SKILL.md`: a Generate section (catalog → compose → validate → apply) and a
+  Documentation section (bundle contents, the comment round trip, what the bundle cannot prove).
+- README: 89 tools, L5X 44, and the 0.7.0 milestone.
+
+## [0.6.0] - 2026-10-27
+
+### Added
+
+- **FactoryTalk Optix NetLogic reference.** The bundle vendors a pinned snapshot of Rockwell's
+  [NetLogic cheat sheet](https://github.com/FactoryTalk-Optix/NetLogic_CheatSheet) (51 pages, commit
+  `5e652541`) and exposes it as one tool instead of dumping C# into the prompt:
+  `optix_netlogic` with no arguments returns the contents, a `query` ranks pages by title, topic and
+  symbol before body text, and a `slug` returns that page verbatim. Every page result carries its
+  `risk` (`normal`, `advanced` or `unsupported`, with the repository's own Advanced section marked
+  unsupported), the upstream commit, a source URL and the upstream disclaimer that the snippets may use
+  non-public APIs and must not be used in production as-is.
+- **A FactoryTalk Optix skill.** The row previously had tools and no guidance; `factorytalk-optix` now
+  names the surface, the NetLogic reader and its risk rule, and the report-before-claiming boundary.
+- The `optix` row gains a `netlogic` switch (on by default). Off removes one tool and the guidance
+  without touching the prebuilt engine.
+- `scripts/sync-netlogic.mjs` is the only writer of the snapshot: it pins a commit, copies
+  `pages/*.md`, and generates `index.json` plus `SOURCE.json` (commit, page count, risk counts).
+  `pnpm netlogic:sync` refreshes it; `test/netlogic.spec.mjs` fails when the index and the pages drift.
+
 ## [0.5.0] - 2026-10-27
 
 Commissioned against the Laminator fixtures: a real Studio 5000 ACD exported to a 5.4 MB L5X, a

package/README.md

@@ -4,7 +4,7 @@
 MotionWorks IEC and FactoryTalk Optix sit behind a single install, one row per surface. A row is the
 switch: disable it and that plugin unloads, so its tool schemas leave the request.
 
-`@aryacode/dsh-engineering` · 84 tools · 5 rows · 4 products · MIT
+`@aryacode/dsh-engineering` · 89 tools · 5 rows · 4 products · MIT
 
 ---
 
@@ -36,18 +36,18 @@ bundle.
 
 | Product | Tools | Default | Needs |
 |---|---|---|---|
-| **Studio 5000 L5X** | 40 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
+| **Studio 5000 L5X** | 44 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
 | **FactoryTalk View ME** | 14 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
 | **MotionWorks IEC** | 24 | all on | MotionWorks IEC 3 Pro installed; verified against 1.19 |
-| **FactoryTalk Optix** | 9 (3 need preview) | all on | Optix Studio installed; Tesseract for OCR |
+| **FactoryTalk Optix** | 10 (3 need preview) | all on | Optix Studio installed; Tesseract for OCR |
 
 Tool groups, by product:
 
-- **L5X** — 11 read (`open_project` … `compare_projects`), 9 staged drafts (`draft_*`), 6 Logix
+- **L5X** — 13 read (`open_project` … `document_project`), 11 staged drafts (`draft_*`, `compose_rung`), 6 Logix
   Designer SDK, 7 supervised controller, 7 live EtherNet/IP (2 reads, 2 identity/discovery, 1 batch read, 2 approval-gated writes)
 - **FactoryTalk View** — 6 read, 5 staged edits, 3 Studio handoff
 - **MotionWorks IEC** — 7 session, 7 saved-project reads, 3 verify, 7 direct edits
-- **Optix** — 6 tools, unlinked to a skill until one exists
+- **Optix** — 10 tools, linked to the `factorytalk-optix` guidance; `optix_netlogic` reads the pinned NetLogic cheat-sheet snapshot, and the 9 bridge tools need Studio
 
 ## Switches
 
@@ -62,7 +62,7 @@ down:
 | `ftview` | FactoryTalk View ME read, guidance and edits; optionally the Studio handoff | `edit` (on), `studio` (on) |
 | `mwi` | MotionWorks IEC session, reads, verify, guidance and the edits | `workspace` (empty), `edit` (on) |
 | `viewers` | ladder + ME display previews | — |
-| `optix` | FactoryTalk Optix Studio authoring | `bridgeUrls` (8768), `bridgeToken` (empty), `allowWrites` (on), `allowDestructive` (on), `allowInvoke` (on), `preview` (on), `allowPreviewInput` (on), `cdpUrl`, `previewUrl`, `ocrExecutable` (empty), `ocrLanguage` (`eng`), `ocrTessdataDirectory` (empty) |
+| `optix` | FactoryTalk Optix Studio authoring and the NetLogic reader | `bridgeUrls` (8768), `bridgeToken` (empty), `allowWrites` (on), `allowDestructive` (on), `allowInvoke` (on), `preview` (on), `allowPreviewInput` (on), `cdpUrl`, `previewUrl`, `ocrExecutable` (empty), `ocrLanguage` (`eng`), `ocrTessdataDirectory` (empty), `netlogic` (on) |
 
 **Why the row list collapsed.** The Plugins page lists a bundle's rows flat and skips `cordis:group`
 containers (`plugin-manager/src/index.ts`: *"Group rows are containers … their children carry the
@@ -112,7 +112,7 @@ the lean profile is the one that turns them off.
 - FBD/SFC semantics are not exercised
 - FactoryTalk View Studio work is a **manual handoff**: the bundle plans the import and preflights
   changed files, it does not import
-- Optix has no skill yet; its tools follow the `optix` row config and the Studio bridge
+- Optix is linked to a skill now: the `factorytalk-optix` guidance plus the NetLogic reader; the bridge tools still follow the `optix` row config and the Studio bridge
 
 **Not in this repository** — CAD mounts as an independent plugin.
 
@@ -120,6 +120,7 @@ the lean profile is the one that turns them off.
 
 | Version | What landed |
 |---|---|
+| **0.7.0** | Ladder generation that cannot emit invalid NeutralText: an instruction catalog, a pattern/tree composer that resolves and type-checks every operand, rung comments read and written, and a documentation bundle (`document_project`) with the Studio tags-and-comments CSV |
 | **0.5.0** | Commissioned on real files: FactoryTalk View reads genuine Studio exports (`<gfx>` displays, comma CSVs, UTF-16) instead of reporting zero; L5X alias resolution cuts 315 false "unresolved reference" findings to 16 on a 1279-tag project; `add_tag` no longer demands a value; a locked ACD exports from a copy |
 | **0.4.17** | MotionWorks edits the real project again: the pre-edit backup is written where the bridge and engine verify it, an already-open project is attached instead of reloaded, and `mw_get` returns the body hash the edit takes |
 | **0.4.15** | Every tool surface ships on by default; the row Configure pages switch them off |
@@ -175,7 +176,7 @@ even when the implementation behind a row is replaced.
 | `ftview` | `dsh-engineering-ftview` | `edit` on · `studio` on |
 | `mwi` | `dsh-engineering-mwi` | `edit` on |
 | `viewers` | `@aryacode/dsh-engineering` (its own client face: ladder + ME display previews) | — |
-| `optix` | `@aryacode/dsh-engineering/optix` (wraps the prebuilt `@aryacode/dsh-tool-ft-optix`) | `allowWrites` on · `allowDestructive` on · `allowInvoke` on · `preview` on |
+| `optix` | `@aryacode/dsh-engineering/optix` (wraps the prebuilt `@aryacode/dsh-tool-ft-optix`) | `allowWrites` on · `allowDestructive` on · `allowInvoke` on · `preview` on · `netlogic` on |
 
 ## Safety
 

package/cordis.patch.yml

@@ -9,7 +9,7 @@
 #   l5x    → editing, studio, live, allowWrites   (all on by default)
 #   ftview → edit, studio                          (both on by default)
 #   mwi    → edit                                  (on by default)
-#   optix  → authoring, destructive, invoke, preview (all on by default)
+#   optix  → authoring, destructive, invoke, preview, netlogic (all on by default)
 #
 # Every surface ships on so a fresh install can use the full plugin. Turn one
 # off from the row's Configure page when the profile is read-only or the request

package/entries/netlogic.js

@@ -0,0 +1,266 @@
+/**
+ * FactoryTalk Optix NetLogic retrieval.
+ *
+ * The vendor repository (FactoryTalk-Optix/NetLogic_CheatSheet) is vendored as a
+ * pinned snapshot by `scripts/sync-netlogic.mjs`. This entry exposes it as one tool
+ * so a model can pull the page it needs instead of every page at once: the table of
+ * contents costs a few hundred tokens, a page a few thousand.
+ *
+ * Every answer carries the page's risk flag and the upstream disclaimer. The
+ * repository itself says the snippets may use non-public APIs, may break a project
+ * and are not for production as-is; this module must not outrank that.
+ *
+ * @module dsh-engineering/entries/netlogic
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Plugin name in a composition. */
+export const name = 'engineering-optix-netlogic'
+
+/** The tool needs the registry; the skill is registered when the host offers it. */
+export const inject = ['tools']
+
+/** Registration metadata, kept here so a test can assert it without the file. */
+export const SKILL = {
+  name: 'factorytalk-optix',
+  description: 'FactoryTalk Optix Studio engineering: inspect and author the loaded project through the Studio bridge, validate expressions, take preview screenshots, read NetLogic C# snippets from the pinned cheat-sheet snapshot, and start from a template.',
+  whenToUse: 'The user asks about FactoryTalk Optix — project structure, nodes, variables, aliases, expressions, NetLogic C#, alarms, trends, recipes, OPC UA, or the emulator preview. Route FactoryTalk View ME elsewhere.',
+}
+
+/** The upstream statement every page result repeats. */
+export const DISCLAIMER = 'Reference only. The upstream repository states these snippets may use non-public APIs, may break a project, and must not be used in production as-is; adapt and test them in your own project.'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const DATA_DIRS = [
+  join(HERE, '..', 'vendor', 'optix', 'netlogic'),
+  join(HERE, '..', 'packages', 'optix', 'netlogic'),
+]
+const SKILL_PATHS = [
+  join(HERE, '..', 'vendor', 'optix', 'SKILL.md'),
+  join(HERE, '..', 'packages', 'optix', 'SKILL.md'),
+]
+
+const RISKS = new Set(['normal', 'advanced', 'unsupported'])
+
+/** The first existing path from a candidate list. */
+function first(candidates) {
+  for (const candidate of candidates) if (existsSync(candidate)) return candidate
+  return undefined
+}
+
+/** The vendored snapshot directory, or undefined when it was not shipped. */
+export function dataDirectory() {
+  return first(DATA_DIRS)
+}
+
+/** Cached index and source pin; the snapshot is immutable for a process. */
+let cachedSnapshot
+function snapshot() {
+  if (cachedSnapshot === undefined) cachedSnapshot = loadSnapshot()
+  return cachedSnapshot
+}
+
+/** Cached page text, keyed by slug. */
+const pageCache = new Map()
+
+/** Read the generated index and source pin. */
+export function loadSnapshot() {
+  const directory = dataDirectory()
+  if (directory === undefined) throw new Error('The NetLogic snapshot is missing; run `pnpm netlogic:sync` before packing.')
+  const index = JSON.parse(readFileSync(join(directory, 'index.json'), 'utf8'))
+  const source = JSON.parse(readFileSync(join(directory, 'SOURCE.json'), 'utf8'))
+  if (!Array.isArray(index) || index.length === 0) throw new Error('The NetLogic index is empty; run `pnpm netlogic:sync`.')
+  for (const row of index) {
+    if (typeof row?.slug !== 'string' || !/^[a-z0-9][a-z0-9-]*$/u.test(row.slug)) throw new Error(`The NetLogic index has an invalid slug: ${String(row?.slug)}`)
+    if (!RISKS.has(row.risk)) throw new Error(`The NetLogic index has an invalid risk for ${row.slug}: ${String(row.risk)}`)
+  }
+  return { directory, index, source }
+}
+
+/** Read one page's markdown, refusing anything outside the snapshot. */
+export function pageOf(slug) {
+  if (typeof slug !== 'string' || !/^[a-z0-9][a-z0-9-]*$/u.test(slug)) {
+    throw Object.assign(new Error(`"${String(slug)}" is not a page slug.`), { code: 'INVALID_ARGUMENT' })
+  }
+  const cached = pageCache.get(slug)
+  if (cached !== undefined) return cached
+  const { directory } = snapshot()
+  const path = join(directory, 'pages', `${slug}.md`)
+  if (!existsSync(path)) throw Object.assign(new Error(`No page named "${slug}".`), { code: 'COMPONENT_NOT_FOUND' })
+  const markdown = readFileSync(path, 'utf8')
+  pageCache.set(slug, markdown)
+  return markdown
+}
+
+/** Score one page against a query; higher is better, zero means no hit. */
+function scoreOf(row, query) {
+  const needle = query.toLowerCase()
+  if (row.slug === needle) return 100
+  if (row.title.toLowerCase() === needle) return 90
+  if (row.symbols.some(symbol => symbol.toLowerCase() === needle)) return 80
+  if (row.slug.includes(needle)) return 60
+  if (row.title.toLowerCase().includes(needle)) return 55
+  if (row.topics.some(topic => topic === needle)) return 45
+  if (row.symbols.some(symbol => symbol.toLowerCase().startsWith(needle))) return 35
+  return 0
+}
+
+/** Rank pages by metadata, then by body text for the remainder. */
+export function search(index, query, limit = 8) {
+  const scored = index.map(row => ({ row, score: scoreOf(row, query) })).filter(hit => hit.score > 0)
+  if (scored.length < limit) {
+    const seen = new Set(scored.map(hit => hit.row.slug))
+    for (const row of index) {
+      if (seen.has(row.slug)) continue
+      const body = pageOf(row.slug)
+      if (body.toLowerCase().includes(query.toLowerCase())) scored.push({ row, score: 20 })
+    }
+  }
+  return scored
+    .sort((left, right) => right.score - left.score || left.row.title.localeCompare(right.row.title))
+    .slice(0, limit)
+    .map(hit => ({ slug: hit.row.slug, title: hit.row.title, section: hit.row.section, risk: hit.row.risk, score: hit.score }))
+}
+
+/** The coverage every answer carries. */
+const COVERAGE = {
+  complete: false,
+  unverified: [
+    'C# compiles against the installed Optix version',
+    'the snippet is safe for this project',
+    'runtime behaviour in the emulator or on the panel',
+  ],
+}
+
+/**
+ * Answer one call.
+ *
+ * @param args - `slug` for one page, `query` to search, or neither for the contents.
+ * @returns The tool envelope.
+ */
+export function answer(args = {}) {
+  const { index, source } = snapshot()
+  const slug = typeof args.slug === 'string' && args.slug.trim() !== '' ? args.slug.trim() : undefined
+  if (slug !== undefined) {
+    const markdown = pageOf(slug)
+    const row = index.find(entry => entry.slug === slug)
+    return {
+      summary: `Read ${row.title} (${row.risk}) from ${source.repository}@${source.commit.slice(0, 8)}.`,
+      data: {
+        slug,
+        title: row.title,
+        section: row.section,
+        risk: row.risk,
+        commit: source.commit,
+        source_url: `https://github.com/${source.repository}/blob/${source.commit}/pages/${slug}.md`,
+        code_blocks: Math.floor((markdown.match(/^```/gmu) ?? []).length / 2),
+        disclaimer: DISCLAIMER,
+        markdown,
+      },
+      next: [{ tool: 'optix_edit', why: 'Apply the adapted snippet through the Studio bridge, then validate.' }],
+      coverage: COVERAGE,
+    }
+  }
+  const query = typeof args.query === 'string' && args.query.trim() !== '' ? args.query.trim() : undefined
+  if (query === undefined) {
+    return {
+      summary: `${index.length} NetLogic pages from ${source.repository}@${source.commit.slice(0, 8)}.`,
+      data: {
+        commit: source.commit,
+        disclaimer: DISCLAIMER,
+        pages: index.map(row => ({ slug: row.slug, title: row.title, section: row.section, risk: row.risk })),
+      },
+      next: [{ tool: 'optix_netlogic', args: { query: 'sessions' }, why: 'Read the page for a topic before writing NetLogic.' }],
+      coverage: COVERAGE,
+    }
+  }
+  const requested = typeof args.limit === 'number' && Number.isInteger(args.limit) ? args.limit : 8
+  const limit = Math.min(Math.max(requested, 1), 20)
+  const hits = search(index, query, limit)
+  return {
+    summary: hits.length === 0
+      ? `No NetLogic page matches "${query}".`
+      : `${hits.length} NetLogic page(s) match "${query}".`,
+    data: { commit: source.commit, query, hits, ...(hits.length === 0 ? { suggestion: 'Call optix_netlogic with no arguments for the contents, then pass one slug.' } : {}) },
+    next: hits.length === 0
+      ? [{ tool: 'optix_netlogic', why: 'List the contents and pick a slug.' }]
+      : [{ tool: 'optix_netlogic', args: { slug: hits[0].slug }, why: 'Read the best-matching page.' }],
+    coverage: COVERAGE,
+  }
+}
+
+/** The failure envelope every engineering tool returns. */
+function failure(error) {
+  const code = typeof error?.code === 'string' ? error.code : 'INTERNAL'
+  return {
+    error: {
+      code,
+      message: error instanceof Error ? error.message : String(error),
+      fix: code === 'COMPONENT_NOT_FOUND'
+        ? 'Call optix_netlogic with no arguments for the available slugs.'
+        : 'Correct the argument and retry; the snapshot is local and needs no network.',
+      candidates: [],
+    },
+  }
+}
+
+/** The tool definition this entry registers. */
+export const definition = {
+  name: 'optix_netlogic',
+  description: 'Read the pinned FactoryTalk Optix NetLogic cheat-sheet snapshot: return the contents with no arguments, ranked pages for a query, or one page in full for a slug. Every page result carries its risk flag, the upstream commit and the upstream disclaimer.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Topic, method or symbol to search for, for example "sessions", "PeriodicTask" or "alarm".' },
+      slug: { type: 'string', description: 'Exact page slug from the contents, for example "netlogic-lifecycle".' },
+      limit: { type: 'integer', description: 'Most search hits to return; defaults to 8, maximum 20.', minimum: 1, maximum: 20 },
+    },
+    additionalProperties: false,
+    required: [],
+  },
+  output: {
+    schema: { type: 'object', additionalProperties: true },
+    render(_args, value) {
+      return [{ type: 'text', text: JSON.stringify(value, undefined, 2) }]
+    },
+  },
+  async execute(args) {
+    try {
+      return answer(args ?? {})
+    } catch (error) {
+      return failure(error)
+    }
+  },
+}
+
+/**
+ * Register the retrieval tool and, when the host offers it, the Optix skill.
+ *
+ * @param ctx - Plugin context with the tool registry and an optional skills service.
+ */
+export function apply(ctx) {
+  ctx.tools.register(definition)
+  const skillPath = first(SKILL_PATHS)
+  const skills = typeof ctx.get === 'function' ? ctx.get('skills') : undefined
+  if (skillPath === undefined || skills === undefined || typeof skills.register !== 'function') {
+    try {
+      ctx.logger?.warn?.('optix-netlogic: the skill was not registered; the tool is available.')
+    } catch {
+      // A logger that refuses must not turn a missing skill into a crash.
+    }
+    return
+  }
+  const raw = readFileSync(skillPath, 'utf8')
+  const content = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '')
+  skills.register({
+    ...SKILL,
+    content,
+    path: skillPath,
+    source: 'custom',
+    provider: '@aryacode/dsh-engineering',
+    invocation: { modelInvocable: true, userInvocable: true },
+  })
+}

package/entries/optix.js

@@ -11,6 +11,7 @@
 import z from '@deepseek-ai/schemastery'
 import { dirname, join } from 'node:path'
 import * as optix from '../vendor/optix/lib/index.js'
+import * as netlogic from './netlogic.js'
 import { flag, list, text } from './config.js'
 
 export const name = 'engineering-optix'
@@ -53,6 +54,9 @@ export const Config = z.object({
   ocrTessdataDirectory: z.string().default('').volatile().description(
     'Folder holding the .traineddata files. Empty derives tessdata beside tesseract.exe.',
   ),
+  netlogic: z.boolean().default(true).volatile().description(
+    'Register the pinned NetLogic cheat-sheet reader (optix_netlogic) and the FactoryTalk Optix skill. Off removes one tool and its guidance.',
+  ),
   requestTimeoutMs: z.natural().min(1).max(2147483647).default(20000),
   maxResponseBytes: z.natural().min(1).default(2000000),
   maxBatchOps: z.natural().min(1).default(40),
@@ -93,12 +97,21 @@ export function apply(ctx, config = {}) {
     }
   }
   let mounted
+  let netlogicMounted
   // Volatile-only config changes are committed into the live references and
   // emit `loader/volatile-update` instead of re-running apply(). The prebuilt
   // plugin reads its options once, so remount it to pick up a switch change.
   const sync = () => {
     if (mounted !== undefined) void mounted.dispose()
     mounted = ctx.plugin(optix, options())
+    // The NetLogic reader is this repository's own entry: it is a separate plugin
+    // so the row's `netlogic` switch can drop one tool and its guidance without
+    // touching the prebuilt engine.
+    if (netlogicMounted !== undefined) {
+      void netlogicMounted.dispose()
+      netlogicMounted = undefined
+    }
+    if (flag(config.netlogic)) netlogicMounted = ctx.plugin(netlogic)
   }
   sync()
   ctx.on('loader/volatile-update', sync)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",
@@ -55,14 +55,6 @@
       ]
     }
   },
-  "scripts": {
-    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs",
-    "docs:tools": "tsx scripts/gen-tool-reference.ts",
-    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
-    "build:client": "node scripts/build-client.mjs",
-    "assemble": "node scripts/assemble.mjs",
-    "prepack": "node scripts/build-client.mjs && node scripts/assemble.mjs"
-  },
   "dependencies": {
     "fast-xml-parser": "5.11.1",
     "fast-xml-validator": "1.4.2",
@@ -102,5 +94,13 @@
     "./mwi/skill": "./vendor/mwi/lib/skill.js",
     "./mwi/verify": "./vendor/mwi/lib/verify.js",
     "./mwi/edit": "./vendor/mwi/lib/edit.js"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs test/netlogic.spec.mjs",
+    "docs:tools": "tsx scripts/gen-tool-reference.ts",
+    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
+    "netlogic:sync": "node scripts/sync-netlogic.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "assemble": "node scripts/assemble.mjs"
   }
-}
+}

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;