@aryacode/dsh-engineering 0.4.7 → 0.4.21

package/entries/optix.js

@@ -0,0 +1,105 @@
+/**
+ * The FactoryTalk Optix product row.
+ *
+ * The Optix engine ships prebuilt. This entry owns the row's configuration so
+ * the Plugins page can render it, resolves the volatile references the settings
+ * page writes, and hands the prebuilt plugin a plain options object.
+ *
+ * Authoring ships on by default. The prebuilt plugin registers the tools, and
+ * each capability can be switched off from the row's config form.
+ */
+import z from '@deepseek-ai/schemastery'
+import { dirname, join } from 'node:path'
+import * as optix from '../vendor/optix/lib/index.js'
+import { flag, list, text } from './config.js'
+
+export const name = 'engineering-optix'
+export const inject = ['tools']
+
+export const Config = z.object({
+  bridgeUrls: z.array(z.string()).default(['http://127.0.0.1:8768']).volatile().description(
+    'Loopback origins of the Studio bridge. One per entry; the bridge runs inside FactoryTalk Optix Studio.',
+  ),
+  bridgeToken: z.string().default('').volatile().description(
+    'Bearer token configured on the Studio bridge, if it requires one.',
+  ),
+  allowWrites: z.boolean().default(true).volatile().description(
+    'Live authoring through optix_edit and optix_action. Dry-run validation works without it.',
+  ),
+  allowDestructive: z.boolean().default(true).volatile().description(
+    'Delete, move, reorder, retype, replace and convert operations.',
+  ),
+  allowInvoke: z.boolean().default(true).volatile().description(
+    'Invoke exported methods on a session-safe bridge build.',
+  ),
+  preview: z.boolean().default(true).volatile().description(
+    'Register the direct-CDP preview and screenshot tools. Needs the emulator browser open.',
+  ),
+  cdpUrl: z.string().default('http://127.0.0.1:9223').volatile().description(
+    'Chromium DevTools endpoint used only when preview is on.',
+  ),
+  previewUrl: z.string().default('http://127.0.0.1:8081/').volatile().description(
+    'Already-open emulator tab, matched by exact origin, path and query.',
+  ),
+  allowPreviewInput: z.boolean().default(true).volatile().description(
+    'Pointer and keyboard input into the emulator preview. Input can change runtime values.',
+  ),
+  ocrExecutable: z.string().default('').volatile().description(
+    'Full path to tesseract.exe for optix_ocr. Leave empty to keep OCR unregistered.',
+  ),
+  ocrLanguage: z.string().default('eng').volatile().description(
+    'Tesseract language code or + separated list, for example eng or eng+deu.',
+  ),
+  ocrTessdataDirectory: z.string().default('').volatile().description(
+    'Folder holding the .traineddata files. Empty derives tessdata beside tesseract.exe.',
+  ),
+  requestTimeoutMs: z.natural().min(1).max(2147483647).default(20000),
+  maxResponseBytes: z.natural().min(1).default(2000000),
+  maxBatchOps: z.natural().min(1).default(40),
+  maxMapNodes: z.natural().min(1).default(800),
+  maxMapDepth: z.natural().min(1).default(8),
+  maxPreviewPixels: z.natural().min(1).default(8000000),
+})
+
+/**
+ * Mount the Optix surface with resolved, plain options.
+ * @param ctx - plugin context.
+ * @param config - the Studio bridge, authoring gates and preview settings.
+ */
+export function apply(ctx, config = {}) {
+  const options = () => {
+    const ocrExecutable = text(config.ocrExecutable)
+    return {
+      bridgeUrls: list(config.bridgeUrls),
+      bridgeToken: text(config.bridgeToken),
+      allowWrites: flag(config.allowWrites),
+      allowDestructive: flag(config.allowDestructive),
+      allowInvoke: flag(config.allowInvoke),
+      preview: flag(config.preview),
+      cdpUrl: text(config.cdpUrl) || 'http://127.0.0.1:9223',
+      previewUrl: text(config.previewUrl) || 'http://127.0.0.1:8081/',
+      allowPreviewInput: flag(config.allowPreviewInput),
+      ocr: ocrExecutable === '' ? null : {
+        executable: ocrExecutable,
+        language: text(config.ocrLanguage, 'eng'),
+        tessdataDirectory: text(config.ocrTessdataDirectory) || join(dirname(ocrExecutable), 'tessdata'),
+      },
+      requestTimeoutMs: config.requestTimeoutMs ?? 20000,
+      maxResponseBytes: config.maxResponseBytes ?? 2000000,
+      maxBatchOps: config.maxBatchOps ?? 40,
+      maxMapNodes: config.maxMapNodes ?? 800,
+      maxMapDepth: config.maxMapDepth ?? 8,
+      maxPreviewPixels: config.maxPreviewPixels ?? 8000000,
+    }
+  }
+  let mounted
+  // 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())
+  }
+  sync()
+  ctx.on('loader/volatile-update', sync)
+}

package/lib/client.js

@@ -1,9 +1,10 @@
 /**
- * The engineering bundle's one browser half: the ladder viewer and the
- * FactoryTalk View ME display preview inside a single module registration.
+ * The engineering bundle's one browser half: the ladder viewer, the
+ * FactoryTalk View ME display preview and the product-row settings pages inside
+ * a single module registration.
  *
  * Generated by scripts/build-client.mjs from the committed face bundles
- * (packages/viewer/lib/client.js, packages/ftview-viewer/lib/client.js).
+ * (packages/viewer/lib/client.js, packages/ftview-viewer/lib/client.js, scripts/faces/settings.js).
  * Do not edit: change a face in its own package and rebuild.
  *
  * The package name is the registration id because the shell keys a client
@@ -3425,23 +3426,351 @@ window.__ModuleLoader__.load({
       apply,
     }
   
+    })()
+    const settings = (() => {
+
+    const React = require('react')
+    const { Button, Checkbox } = require('@deepseek-ai/dsh-client-ui-primitives')
+
+    const intro = {
+      margin: 0,
+      color: 'var(--dsw-alias-text-secondary, #6b7280)',
+      fontSize: '13px',
+      lineHeight: '1.6',
+    }
+    const hint = {
+      color: 'var(--dsw-alias-text-secondary, #6b7280)',
+      fontSize: '12px',
+      lineHeight: '1.5',
+    }
+
+    /**
+     * Render one row's boolean switches, staged until Save.
+     *
+     * The Plugins page snapshots the form once when it opens the row page and
+     * does not subscribe to it, so a form that is still loading at that moment
+     * would stay "Loading configuration…" forever. Read the live controller
+     * from the client `configForms` service instead: its `get` starts the one
+     * describe fetch, and subscribing makes the switches appear when it settles.
+     *
+     * @param props - the slot owner's `view`, plus this entry's `spec` and the
+     *   client `configForms` service.
+     * @returns the row's configuration page, its summary, or a status line.
+     */
+    function RowConfig(props) {
+      const { form, spec, view } = props
+      const [draft, setDraft] = React.useState(null)
+      const [saving, setSaving] = React.useState(false)
+      const [notice, setNotice] = React.useState('')
+
+      // Resolve the service lazily: it is provided by the Settings page's own
+      // client half, which may load after this bundle's face.
+      const configForms = typeof props.configForms === 'function' ? props.configForms() : props.configForms
+      const live = configForms === undefined ? undefined : configForms.get(spec.id)
+      const subscribe = React.useCallback(
+        listener => (live === undefined ? () => {} : live.subscribe(listener)),
+        [live],
+      )
+      const snapshot = React.useCallback(
+        () => (live === undefined ? form?.state : live.getSnapshot()),
+        [live, form],
+      )
+      const state = React.useSyncExternalStore(subscribe, snapshot)
+      const value = state === undefined ? undefined : state.value
+
+      if (view === 'summary') return React.createElement('span', null, spec.summary)
+      if (state === undefined) {
+        return React.createElement('p', { style: intro }, 'This row does not expose its configuration to the Plugins page.')
+      }
+      if (value === undefined) {
+        return React.createElement('p', { style: intro },
+          state.status === 'unavailable'
+            ? 'This row has no configuration to change.'
+            : 'Loading configuration…')
+      }
+
+      const current = draft === null ? value : draft
+      const isText = field => field.type === 'text'
+      const isList = field => field.type === 'list'
+      const listText = input => (Array.isArray(input) ? input.join(', ') : String(input ?? ''))
+      const splitList = input => String(input ?? '').split(',').map(item => item.trim()).filter(Boolean)
+      const same = (field, left, right) => (isText(field) || isList(field)
+        ? listText(left) === listText(right)
+        : Boolean(left) === Boolean(right))
+      const dirty = spec.fields.some(field => !same(field, current[field.key], value[field.key]))
+      const writable = state.writable === true
+      const setField = (key, next) => {
+        setDraft({ ...current, [key]: next })
+        setNotice('')
+      }
+      const save = async () => {
+        if (saving || !dirty) return
+        setSaving(true)
+        setNotice('')
+        try {
+          const ops = spec.fields.map(field => ({
+            op: 'set',
+            path: [field.key],
+            value: isText(field) ? String(current[field.key] ?? '') : isList(field) ? (Array.isArray(current[field.key]) ? current[field.key] : splitList(current[field.key])) : Boolean(current[field.key]),
+          }))
+          const owner = live === undefined ? form : live
+          const accepted = await owner.mutate(ops, state.revision)
+          if (accepted) {
+            setDraft(null)
+            setNotice('Saved.')
+          } else {
+            setNotice('The Host refused the change.')
+          }
+        } catch (error) {
+          setNotice(error instanceof Error ? error.message : String(error))
+        }
+        setSaving(false)
+      }
+
+      return React.createElement('div', { style: { display: 'grid', gap: '18px' } },
+        React.createElement('p', { style: intro }, spec.intro),
+        React.createElement('div', { style: { display: 'grid', gap: '14px' } },
+          spec.fields.map(field => React.createElement('div', {
+            key: field.key,
+            style: { display: 'grid', gap: '3px' },
+          },
+          isText(field) || isList(field)
+            ? React.createElement('label', { style: { display: 'grid', gap: '5px' } },
+              React.createElement('span', { style: { fontSize: '13px', fontWeight: 600 } }, field.label),
+              React.createElement('input', {
+                type: 'text',
+                value: listText(current[field.key]),
+                disabled: !writable || saving,
+                onChange: event => { setField(field.key, event.target.value) },
+                placeholder: field.placeholder ?? '',
+                style: {
+                  padding: '7px 10px',
+                  borderRadius: '8px',
+                  border: '1px solid var(--dsw-alias-border, #d4d4d8)',
+                  background: 'transparent',
+                  color: 'inherit',
+                  fontSize: '13px',
+                  fontFamily: 'inherit',
+                },
+              }))
+            : React.createElement(Checkbox, {
+              checked: Boolean(current[field.key]),
+              onChange: next => { setField(field.key, next) },
+              label: field.label,
+              disabled: !writable || saving,
+            }),
+          React.createElement('span', { style: { ...hint, marginLeft: isText(field) || isList(field) ? '0' : '26px' } }, field.description)))),
+        React.createElement('div', { style: { display: 'flex', gap: '10px', alignItems: 'center', flexWrap: 'wrap' } },
+          React.createElement(Button, {
+            variant: 'primary',
+            disabled: !writable || saving || !dirty,
+            onClick: save,
+          }, saving ? 'Saving…' : 'Save changes'),
+          dirty
+            ? React.createElement(Button, {
+              variant: 'ghost',
+              disabled: saving,
+              onClick: () => { setDraft(null); setNotice('') },
+            }, 'Discard')
+            : null,
+          notice === '' ? null : React.createElement('span', { style: hint }, notice),
+          writable ? null : React.createElement('span', { style: hint }, 'This profile does not accept configuration writes.')))
+    }
+
+    const L5X = {
+      id: 'l5x',
+      summary: 'L5X editing, Studio 5000 SDK access and live EtherNet/IP reads are on by default; turn off what this machine does not use.',
+      intro: 'The read surface is always on. Each switch below adds tool schemas to every request, so turn off what you do not use.',
+      fields: [
+        {
+          key: 'editing',
+          label: 'Editing — nine draft tools',
+          description: 'Stages changes against a project copy; applying writes a new .L5X and leaves the open export untouched.',
+        },
+        {
+          key: 'studio',
+          label: 'Studio 5000 SDK and supervised controller',
+          description: 'Needs Studio 5000 with the Logix Designer SDK service installed; upload, mode change and download are approval-gated.',
+        },
+        {
+          key: 'live',
+          label: 'Live EtherNet/IP',
+          description: 'Controller identity, tag polling, batch reads up to 64 tags, wall clock, LAN discovery and a bounded trend.',
+        },
+        {
+          key: 'allowWrites',
+          label: 'Allow the two live writes',
+          description: 'Tag value and controller clock. Each write still needs human approval for that exact operation, and only applies while live is on.',
+        },
+      ],
+    }
+
+    const FTVIEW = {
+      id: 'ftview',
+      summary: 'FactoryTalk View ME edits and the Studio handoff are on by default; turn them off to keep a read-only profile.',
+      intro: 'The read surface and guidance stay on. Edits and the Studio handoff are on by default because the schemas are small.',
+      fields: [
+        {
+          key: 'edit',
+          label: 'FactoryTalk View ME edits',
+          description: 'Display, HMI tag and structural edits against an exported project.',
+        },
+        {
+          key: 'studio',
+          label: 'Studio handoff',
+          description: 'Opens the project in FactoryTalk View Studio ME for the parts the agent should not change itself.',
+        },
+      ],
+    }
+
+    const MWI = {
+      id: 'mwi',
+      summary: 'MotionWorks IEC edits are on by default; session, reads and verification are always on.',
+      intro: 'Session, reads and verification stay on. Set the workspace once so the tools find the projects; turn editing off only for a read-only profile.',
+      fields: [
+        {
+          key: 'workspace',
+          type: 'text',
+          label: 'Workspace root',
+          placeholder: 'C:\\Users\\you\\Documents\\Projects',
+          description: 'Absolute folder that contains the MotionWorks projects. Leave empty to use the session directory or the mwi.workspace marker in the profile.',
+        },
+        {
+          key: 'edit',
+          label: 'Editing — seven staged tools',
+          description: 'Code, declarations, structure, blocks and POU package imports/exports. Needs MotionWorks IEC 3 Pro installed.',
+        },
+      ],
+    }
+
+    const OPTIX = {
+      id: 'optix',
+      summary: 'FactoryTalk Optix reads and authoring are on by default; turn off what this machine does not use.',
+      intro: 'The Studio bridge runs inside FactoryTalk Optix Studio. Reads work once a project with the bridge is open; turn off the authoring surfaces this machine does not use.',
+      fields: [
+        {
+          key: 'bridgeUrls',
+          type: 'list',
+          label: 'Studio bridge origins',
+          placeholder: 'http://127.0.0.1:8768',
+          description: 'Loopback origins, comma separated. The bridge listens inside Optix Studio; the default is port 8768.',
+        },
+        {
+          key: 'bridgeToken',
+          type: 'text',
+          label: 'Bridge token',
+          placeholder: 'Only if the bridge requires one',
+          description: 'Bearer token sent to the Studio bridge. Leave empty when the bridge has no token.',
+        },
+        {
+          key: 'allowWrites',
+          label: 'Live authoring — optix_edit and optix_action',
+          description: 'Applies typed edits to the live Studio model. Dry-run validation works without it; a successful edit does not save Studio.',
+        },
+        {
+          key: 'allowDestructive',
+          label: 'Allow destructive operations',
+          description: 'Delete, move, reorder, retype, replace and convert. Requires live authoring.',
+        },
+        {
+          key: 'allowInvoke',
+          label: 'Invoke exported methods',
+          description: 'Needs a session-safe bridge build; the packaged templates ship bridge 1.0.7, which cannot invoke.',
+        },
+        {
+          key: 'preview',
+          label: 'Emulator preview and screenshots',
+          description: 'Registers optix_preview, optix_screenshot and (when configured) optix_ocr. Needs the emulator browser open with CDP enabled.',
+        },
+        {
+          key: 'cdpUrl',
+          type: 'text',
+          label: 'Chromium CDP endpoint',
+          placeholder: 'http://127.0.0.1:9223',
+          description: 'Used only when the emulator preview is on.',
+        },
+        {
+          key: 'previewUrl',
+          type: 'text',
+          label: 'Emulator preview URL',
+          placeholder: 'http://127.0.0.1:8081/',
+          description: 'Already-open emulator tab, matched by exact origin, path and query.',
+        },
+        {
+          key: 'allowPreviewInput',
+          label: 'Allow preview pointer and keyboard input',
+          description: 'Input can change runtime values in the emulator. It ships on; turn it off when a test must not move the emulator.',
+        },
+        {
+          key: 'ocrExecutable',
+          type: 'text',
+          label: 'OCR — Tesseract executable',
+          placeholder: 'C:\\Program Files\\Tesseract-OCR\\tesseract.exe',
+          description: 'Full path to tesseract.exe. Leave empty to keep optix_ocr unregistered; preview is still required.',
+        },
+        {
+          key: 'ocrLanguage',
+          type: 'text',
+          label: 'OCR language',
+          placeholder: 'eng',
+          description: 'Tesseract language code, or a + separated list such as eng+deu. The matching .traineddata files must exist.',
+        },
+        {
+          key: 'ocrTessdataDirectory',
+          type: 'text',
+          label: 'OCR tessdata folder',
+          placeholder: 'C:\\Program Files\\Tesseract-OCR\\tessdata',
+          description: 'Folder holding the .traineddata files. Empty uses tessdata beside the executable.',
+        },
+      ],
+    }
+
+    /**
+     * Register the four row configuration pages.
+     * @param ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      const configForms = () => {
+        try {
+          return ctx.get('configForms')
+        } catch {
+          return undefined
+        }
+      }
+      const register = (rowId, spec) => {
+        ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+          name: 'plugins.row.config',
+          key: '@aryacode/dsh-engineering#' + rowId,
+          inject: () => ({ spec, configForms }),
+        }, RowConfig))
+      }
+      register('l5x', L5X)
+      register('ftview', FTVIEW)
+      register('mwi', MWI)
+      register('optix', OPTIX)
+    }
+
+    return { inject: ['slots'], apply }
+  
     })()
 
     if (
       typeof ladder.apply !== 'function' ||
-      typeof ftview.apply !== 'function'
+      typeof ftview.apply !== 'function' ||
+      typeof settings.apply !== 'function'
     ) {
       throw new Error("@aryacode/dsh-engineering" + ': a merged client face exports no apply()')
     }
 
-    // The declared services are the union of both faces': one Cordis plugin
+    // The declared services are the union of every face's: one Cordis plugin
     // cannot inject less than its parts need. CJS shape (exports.apply /
     // exports.inject) is the loader's contract for a registered factory.
     return {
-      inject: [...new Set([...ladder.inject, ...ftview.inject])],
+      inject: [...new Set([...ladder.inject, ...ftview.inject, ...settings.inject])],
       apply: (ctx) => {
         ladder.apply(ctx)
         ftview.apply(ctx)
+        settings.apply(ctx)
       },
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.4.7",
+  "version": "0.4.21",
   "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,6 +55,14 @@
       ]
     }
   },
+  "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",
@@ -79,7 +87,7 @@
     "./l5x": "./entries/l5x.js",
     "./ftview": "./entries/ftview.js",
     "./mwi": "./entries/mwi.js",
-    "./optix": "./vendor/optix/lib/index.js",
+    "./optix": "./entries/optix.js",
     "./l5x/read": "./vendor/l5x/lib/index.js",
     "./l5x/skill": "./vendor/l5x/lib/skill.js",
     "./l5x/editing": "./vendor/l5x/lib/editing.js",
@@ -94,12 +102,5 @@
     "./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",
-    "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"
   }
-}
+}

package/vendor/ftview/SKILL.md

@@ -13,6 +13,23 @@ A staged edit is written to a NEW export folder; the source is never modified. T
 a manual import for a human; it does not drive Studio, contact a terminal, or decode MER or MED
 databases.
 
+## Backups
+
+Every engineering product backs up into the same tree, so a backup means one place whichever surface
+you are in:
+
+```
+<workspace>/backups/<product>/<subject>/<UTC stamp>/
+    backup-manifest.json      every copied file: relative path + SHA-256
+    <the copy>
+```
+
+FactoryTalk View is the `ftview` product: the copy is the whole export folder (display XML plus the tag
+CSV), one stamp per backup. `ftview_apply` already writes a new folder, so this is a backup on request
+("back up this export"). Build it as a copy plus `backup-manifest.json` listing every file's relative
+path and SHA-256. `<workspace>/_backups` and `<workspace>/backups/<project>/…` are older layouts: never
+write there, and leave what is there alone.
+
 ## Start
 
 1. Call `ftview_open` with the export folder. Keep the returned `view_id`.

package/vendor/l5x/SKILL.md

@@ -10,6 +10,23 @@ whenToUse: Use when the user asks about a Studio 5000 L5X export, Logix tags, ro
 
 This surface reads and drafts. A draft writes only a new L5X file: it never overwrites the source, imports into Studio, connects to a controller, changes mode, or writes runtime data.
 
+## Backups
+
+Every engineering product backs up into the same tree, so a backup means one place whichever surface
+you are in:
+
+```
+<workspace>/backups/<product>/<subject>/<UTC stamp>/
+    backup-manifest.json      every copied file: relative path + SHA-256
+    <the copy>
+```
+
+Studio 5000 is the `l5x` product: the copy holds the `.ACD` being worked on, or the `.L5X` export when
+that is the source of truth, one stamp per backup. Drafts and SDK builds already write new files, so
+this is a backup on request ("back up this project"). Build it as a copy plus
+`backup-manifest.json` listing every file's relative path and SHA-256. `<workspace>/_backups` and
+`<workspace>/backups/<project>/…` are older layouts: never write there, and leave what is there alone.
+
 ## Start
 
 1. Call `open_project` with the export path. Keep the returned `project_id`.

package/vendor/l5x/studio-bridge/NuGet.Config

@@ -1 +1 @@
-<configuration><packageSources><clear/><add key="LocalRockwellSdk" value="C:\Users\Public\Documents\Studio 5000\Logix Designer SDK\dotnet"/><add key="nuget.org" value="https://api.nuget.org/v3/index.json"/></packageSources></configuration>
+<configuration><packageSources><clear/><add key="LocalRockwellSdk" value="C:\Users\Public\Documents\Studio 5000\Logix Designer SDK\dotnet"/><add key="nuget.org" value="https://api.nuget.org/v3/index.json"/></packageSources></configuration>

package/vendor/mwi/README.md

@@ -1,21 +1,26 @@
 # dsh-engineering-mwi
 
-MotionWorks IEC 3 Pro tools, redesigned for the `dsh-engineering` bundle. The product works on a
-**staged copy** of a workspace project and drives the running IDE through the existing 32-bit COM
-bridge; the tool surface is new.
+MotionWorks IEC 3 Pro tools, redesigned for the `dsh-engineering` bundle. The product edits the
+**real workspace project**: `mw_project_open` writes one complete hash-verified backup under
+`<workspace>/backups/motionworks/<project>/<stamp>/` first, then drives the running IDE through the
+existing 32-bit COM bridge. A project the IDE already has open is attached (backup recorded) instead of
+reloaded, so unsaved editor changes survive. `mw_project_stage` remains as an optional sandbox.
 
-This package is **not mounted yet**. The legacy `dsh-tool-motionworks-iec` remains the shipped
-surface until the redesign flips in Phase 5. The migration design and phase order are in
-[docs/port/mwi.md](../../docs/port/mwi.md).
+`<workspace>/backups/<product>/<subject>/<stamp>/` is the one tree every engineering product writes
+under, so a backup is one place whichever surface the user is in. MotionWorks is the product whose
+backup is also a contract: the shipped bridge (`Get-DirectIdentity`) and the read-only engine
+(`assert_direct_attached`) refuse a real project unless an identity record names a copy in that tree,
+with a manifest whose SHA-256 matches. Records written before 0.4.21 that point at
+`.motionworks/attached/backups` stay valid.
 
-## Rows and progress
+## Rows
 
 | Row | Default | Tools | Status |
 |---|---|---|---|
 | `mwi-session` | on | 7 | implemented and live-verified |
 | `mwi-read` | on | 7 | implemented and live-verified |
-| `mwi-verify` | on | 3 | next |
-| `mwi-edit` | off | 7 | planned |
+| `mwi-verify` | on | 3 | implemented and live-verified |
+| `mwi-edit` | on | 7 | implemented; direct-edit path live-verified |
 | `mwi-skill` | on | the `motionworks-iec` guidance | implemented |
 
 Read tools: `mw_project_overview`, `mw_list`, `mw_get`, `mw_search`, `mw_references`, `mw_review`, `mw_help`.
@@ -23,16 +28,34 @@ Read tools: `mw_project_overview`, `mw_list`, `mw_get`, `mw_search`, `mw_referen
 Session tools: `mw_project_find`, `mw_ide_status`, `mw_project_stage`, `mw_project_open`,
 `mw_ide_start`, `mw_worksheet_open`, `mw_project_close`.
 
+Edit tools: `mw_edit_code`, `mw_edit_variables`, `mw_edit_structure`, `mw_insert_block`,
+`mw_transfer_pou`, `mw_validate`, `mw_apply`.
+
 ## Live evidence
 
-Verified against MotionWorks IEC 3 Pro 1.19 on 2026-10-23 with a copy of a real project in a temporary
-workspace:
+Verified against MotionWorks IEC 3 Pro 1.19 with a copy of a real project in a temporary workspace:
+
+1. `open` writes `backups/motionworks/<project>/<stamp>/` with `backup-manifest.json` and
+   `.motionworks/attached/records/<id>.json`, verified before the IDE is asked to open anything, and
+   reuses that backup on later attaches.
+2. A project already open in the IDE is attached without an `OpenProject` call: `mw_project_open`
+   reports `already_open` and the verified backup path.
+3. `start` launches the IDE on the real `.mwt`; `status` reports it open.
+4. `worksheet` opens `Global_Variables` and verifies the active editor and unchanged modified state.
+5. `edit` tools write through the native IDE API; `apply` saves the project in place, and an edit
+   refused for a missing backup takes one before retrying.
+6. `close` reports `closed: true`, and the next status reports the IDE not running.
+
+The staged flow (`stage` then `open` the copy) still works when a sandbox is wanted.
+
+## What the guarded read proves
+
+`mw_get` for a POU returns the `text_body_sha256` of the exact body it returns. Passing it to
+`mw_edit_code` is optional: when it is omitted, the tool hashes the current saved body itself, so the
+documented read-then-edit flow works either way.
 
-1. `stage` copied the project, bound the wrapper to the staged directory and wrote its identity.
-2. `start` launched the IDE and answered the trial prompt (`posted_bm_click`).
-3. `status` reported the staged project open, `in_stage: true`.
-4. `worksheet` opened `Global_Variables` and verified the active editor and unchanged modified state.
-5. `close` reported `closed: true`, and the next status reported the IDE not running.
+The identity check confirms the manifest digest and that every recorded member exists. Per-file hashes
+are recorded for a restore and for the copy-time check; they are not recomputed on every guarded call.
 
 ## Structure
 
@@ -41,8 +64,8 @@ SKILL.md          the redesigned guidance
 bridge/           the 32-bit PowerShell COM bridge
 code/             the Python engine (wrapper binding, saved-model reads, validation)
 src/core/         params, result, errors, tool, bridge, PowerShell transport, code engine
-src/session/      workspace, stage, runtime
-src/tools/        session row (read/verify/edit rows next)
+src/session/      workspace, stage, backup, runtime
+src/tools/        session, read, verify and edit rows
 test/             contract tests and the live fixtures
 ```