sylo-codesys 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeti-Trix <131923258+Yeti-Trix@users.noreply.github.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# sylo-codesys
+
+Drive a **live, open CODESYS V3.5 project** from Sylo chat — create POUs, write
+Structured Text, compile, read/write PLC variables — with changes appearing in
+the CODESYS IDE in real time.
+
+This package does **not** speak MCP and does **not** spawn CODESYS. It is the
+skill + a setup/diagnostic tool. The actual CODESYS tools come from the external
+[`codesys-mcp-sp21-plus`](https://github.com/phobicdotno/Codesys-MCP-SP21-plus)
+stdio MCP server, surfaced into Pi by the **`pi-mcp-adapter`** package once you
+add a `codesys` server to a workspace `.mcp.json`.
+
+## Requirements
+
+- **CODESYS V3.5 SP19 / SP21 / SP22** installed (Windows).
+- **Node.js 18+** (for the MCP server).
+- The **`pi-mcp-adapter`** package enabled in Sylo → Capability manager.
+- The global npm package `codesys-mcp-sp21-plus`:
+  ```bash
+  npm install -g codesys-mcp-sp21-plus
+  ```
+
+## Setup
+
+1. Enable **sylo-codesys** in Sylo → Capability manager → Sylo optional packages.
+2. Enable **pi-mcp-adapter** (separate package) if it isn't already.
+3. In Sylo chat, ask the agent to call **`codesys_setup_check`**. It detects your
+   CODESYS install, verifies the npm package, checks for a `codesys` server in
+   your `.mcp.json`, confirms the `mcp` adapter is live, and prints a
+   ready-to-paste, augmented `.mcp.json` snippet.
+4. Paste that snippet into your workspace `.mcp.json` (merge into the existing
+   `mcpServers` object). The recommended entry looks like:
+
+   ```json
+   {
+     "mcpServers": {
+       "codesys": {
+         "command": "codesys-mcp-sp21-plus",
+         "args": [
+           "--codesys-path", "C:\\Program Files\\CODESYS 3.5.22.30\\CODESYS\\Common\\CODESYS.exe",
+           "--codesys-profile", "CODESYS V3.5 SP22 Patch 3",
+           "--mode", "persistent",
+           "--no-auto-launch",
+           "--auto-mirror"
+         ],
+         "lifecycle": "lazy-keep-alive",
+         "requestTimeoutMs": 180000,
+         "directTools": ["get_codesys_status", "get_project_info", "get_all_pou_code", "create_pou", "set_pou_code", "create_method", "create_property", "create_dut", "create_gvl", "create_folder", "delete_object", "rename_object", "save_project", "compile_project", "get_compile_messages", "add_library", "list_project_libraries", "connect_to_device", "read_variable", "write_variable", "start_stop_application", "get_application_state", "mirror_export", "shutdown_codesys"],
+         "approveTools": ["delete_object", "write_variable", "force_variables", "unforce_variables", "download_to_device", "reset_application", "shutdown_codesys", "remove_library"]
+       }
+     }
+   }
+   ```
+   Get the exact `--codesys-path` / `--codesys-profile` strings with
+   `codesys-mcp-sp21-plus --print-config` (the setup tool does this for you).
+
+5. Restart the broker so `pi-mcp-adapter` re-reads `.mcp.json`.
+6. In chat, ask the agent to drive CODESYS (e.g. "create a POU `FB_Motor` in
+   Application and compile"). The first tool call launches CODESYS (persistent,
+   UI visible); with `lazy-keep-alive` it stays resident across turns.
+
+## How it works
+
+```
+Sylo agent (LLM)
+   │  calls codesys_create_pou, codesys_compile_project, …  (directTools)
+   │  or mcp({ tool: "create_pou", args })                   (proxy, other tools)
+   ▼
+pi-mcp-adapter  (Pi extension; spawns + owns the MCP server stdio process)
+   ▼
+codesys-mcp-sp21-plus   (Node, stdio MCP server)
+   │  file-based IPC: writes command .py → watcher polls → result
+   ▼
+CODESYS.exe             (persistent, --runscript=watcher.py, UI visible)
+   ▼
+open .project           (live; operator watches changes in the IDE)
+```
+
+## Notes
+
+- Modifying tools (`set_pou_code`, `create_pou`, …) **auto-save** the project.
+  **Ctrl+Z in the IDE does not recover `set_pou_code` edits.** With
+  `--auto-mirror`, each change re-runs `mirror_export` to a `.st` mirror on disk
+  — commit that mirror to git for real undo.
+- `connect_to_device` may pop a "Device User Login" modal in the IDE. Pre-set
+  `CODESYS_DEVICE_USER` / `CODESYS_DEVICE_PASSWORD` in the server `env` block to
+  suppress it.
+- MCP-server compatibility & docs: see the
+  [codesys-mcp-sp21-plus README](https://github.com/phobicdotno/Codesys-MCP-SP21-plus#readme)
+  and [ARCHITECTURE.md](https://github.com/phobicdotno/Codesys-MCP-SP21-plus/blob/main/ARCHITECTURE.md).

package/extensions/index.ts

@@ -0,0 +1,387 @@
+/**
+ * sylo-codesys — setup + diagnostics for the CODESYS MCP bridge.
+ *
+ * IMPORTANT: this package does NOT speak MCP itself and does NOT spawn CODESYS.
+ * The actual CODESYS tools come from the `codesys-mcp-sp21-plus` stdio MCP
+ * server, surfaced into Pi through the **pi-mcp-adapter** package (enabled
+ * separately in the Capability manager) once the operator adds a `codesys`
+ * server entry to a workspace `.mcp.json`.
+ *
+ * The single tool registered here, `codesys_setup_check`, validates that wiring:
+ *   - detects the installed CODESYS V3.5.x under C:\Program Files,
+ *   - checks the global `codesys-mcp-sp21-plus` npm package (and runs
+ *     `--print-config` to read the exact codesys-path / codesys-profile),
+ *   - inspects the workspace `.mcp.json` (+ ~/.pi/agent/mcp.json) for a codesys
+ *     server entry and reports its key fields,
+ *   - confirms the `mcp` adapter tool (pi-mcp-adapter) is live, and
+ *   - emits a ready-to-paste, *augmented* `.mcp.json` snippet: a curated
+ *     ~24-tool directTools surface, destructive-op approval gating, and a
+ *     lazy-keep-alive lifecycle that keeps the CODESYS instance resident across
+ *     turns while launching it lazily on first use.
+ *
+ * It is read-only with respect to operator config — it never writes the
+ * `.mcp.json` (operator-owned config; the host does not silently enable MCP
+ * servers). The operator (or the agent via `write`) pastes the snippet.
+ */
+import { execFile } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+const execFileAsync = promisify(execFile)
+
+type ToolContentBlock = { type: 'text'; text: string }
+
+function toolText(text: string): { content: ToolContentBlock[]; details: unknown } {
+  return { content: [{ type: 'text', text }], details: {} }
+}
+
+/** Strip // line + block comments and trailing commas so a JSONC .mcp.json parses. */
+function parseJsoncLoose(raw: string): unknown {
+  const attempt = (s: string): unknown => {
+    try {
+      return JSON.parse(s)
+    } catch {
+      return null
+    }
+  }
+  const direct = attempt(raw)
+  if (direct !== null) return direct
+  const stripped = raw
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split('\n')
+    .map((line) => {
+      const i = line.indexOf('//')
+      return i === -1 ? line : line.slice(0, i)
+    })
+    .join('\n')
+    .replace(/,(\s*[}\]])/g, '$1')
+  return attempt(stripped)
+}
+
+interface CodesysInstall {
+  path: string
+  folder: string
+}
+
+function detectCodesysInstalls(): CodesysInstall[] {
+  const out: CodesysInstall[] = []
+  const progFiles = 'C:\\Program Files'
+  try {
+    if (!existsSync(progFiles)) return out
+    for (const folder of readdirSync(progFiles)) {
+      if (!/^CODESYS 3\.5\./i.test(folder)) continue
+      const exe = join(progFiles, folder, 'CODESYS', 'Common', 'CODESYS.exe')
+      if (existsSync(exe)) out.push({ path: exe, folder })
+    }
+  } catch {
+    /* ignore FS errors — this is best-effort detection */
+  }
+  return out
+}
+
+interface ServerEntry {
+  command?: string
+  args?: string[]
+  lifecycle?: string
+  directTools?: unknown
+  approveTools?: unknown
+  [k: string]: unknown
+}
+
+function readMcpJson(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, 'utf8')
+    const v = parseJsoncLoose(raw)
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+function findCodesysServers(obj: Record<string, unknown>): Record<string, ServerEntry> | null {
+  const servers = obj.mcpServers
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return null
+  const map = servers as Record<string, ServerEntry>
+  const keys = Object.keys(map).filter((k) => /codesys/i.test(k))
+  if (keys.length === 0) return null
+  const out: Record<string, ServerEntry> = {}
+  for (const k of keys) out[k] = map[k]!
+  return out
+}
+
+function argAfter(args: string[] | undefined, flag: string): string | undefined {
+  if (!args) return undefined
+  const i = args.indexOf(flag)
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined
+}
+
+/** Curated first-class tool surface (original MCP tool names). */
+const CURATED_DIRECT_TOOLS = [
+  'get_codesys_status',
+  'get_project_info',
+  'get_all_pou_code',
+  'create_pou',
+  'set_pou_code',
+  'create_method',
+  'create_property',
+  'create_dut',
+  'create_gvl',
+  'create_folder',
+  'delete_object',
+  'rename_object',
+  'save_project',
+  'compile_project',
+  'get_compile_messages',
+  'add_library',
+  'list_project_libraries',
+  'connect_to_device',
+  'read_variable',
+  'write_variable',
+  'start_stop_application',
+  'get_application_state',
+  'mirror_export',
+  'shutdown_codesys',
+]
+
+/** Tools that must be confirmed before running (destructive / online forces). */
+const APPROVE_TOOLS = [
+  'delete_object',
+  'write_variable',
+  'force_variables',
+  'unforce_variables',
+  'download_to_device',
+  'reset_application',
+  'shutdown_codesys',
+  'remove_library',
+]
+
+function buildAugmentedEntry(codesysPath: string, profile: string): Record<string, unknown> {
+  return {
+    command: 'codesys-mcp-sp21-plus',
+    args: [
+      '--codesys-path',
+      codesysPath,
+      '--codesys-profile',
+      profile,
+      '--mode',
+      'persistent',
+      '--no-auto-launch',
+      '--auto-mirror',
+    ],
+    lifecycle: 'lazy-keep-alive',
+    requestTimeoutMs: 180000,
+    directTools: CURATED_DIRECT_TOOLS,
+    approveTools: APPROVE_TOOLS,
+  }
+}
+
+function extractPathProfileFromPrintConfig(raw: string): {
+  path?: string
+  profile?: string
+} {
+  const v = parseJsoncLoose(raw) as { mcpServers?: Record<string, ServerEntry> } | null
+  if (!v?.mcpServers) return {}
+  const keys = Object.keys(v.mcpServers)
+  // Prefer an SP22 entry; fall back to the first.
+  const pick = keys.find((k) => /sp22/i.test(k)) ?? keys[0]
+  if (!pick) return {}
+  const entry = v.mcpServers[pick]!
+  return {
+    path: argAfter(entry.args, '--codesys-path'),
+    profile: argAfter(entry.args, '--codesys-profile'),
+  }
+}
+
+async function runPrintConfig(): Promise<{ ok: boolean; raw?: string; error?: string }> {
+  try {
+    const { stdout } = await execFileAsync('codesys-mcp-sp21-plus', ['--print-config'], {
+      windowsHide: true,
+      timeout: 15_000,
+    })
+    return { ok: true, raw: stdout }
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException
+    if (e.code === 'ENOENT') return { ok: false, error: 'not-installed' }
+    return { ok: false, error: e.message ?? String(err) }
+  }
+}
+
+export default function piSyloCodesysExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'codesys_setup_check',
+    label: 'CODESYS MCP setup check',
+    description:
+      'Validate the CODESYS MCP bridge wiring for this Sylo: detect the CODESYS V3.5 install, ' +
+      'check the global `codesys-mcp-sp21-plus` npm package, inspect the workspace `.mcp.json` for a ' +
+      'codesys server entry, confirm the `mcp` adapter tool (pi-mcp-adapter) is live, and emit a ' +
+      'ready-to-paste augmented `.mcp.json` snippet (curated directTools + destructive-op approval ' +
+      'gating + lazy-keep-alive lifecycle). The CODESYS tools themselves come from the MCP server via ' +
+      'pi-mcp-adapter (directTools + the `mcp` proxy), NOT from this tool. Run once after enabling the ' +
+      'sylo-codesys package and whenever the wiring changes.',
+    parameters: Type.Object({
+      mcp_json_path: Type.Optional(
+        Type.String({
+          description:
+            'Path to the `.mcp.json` to inspect (defaults to <cwd>/.mcp.json). ' +
+            'Also checks ~/.pi/agent/mcp.json.',
+        }),
+      ),
+      print_config: Type.Optional(
+        Type.Boolean({
+          description:
+            'Run `codesys-mcp-sp21-plus --print-config` to read the exact CODESYS path/profile ' +
+            '(default true; needs the package installed).',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const lines: string[] = []
+      const wantPrint = params.print_config !== false
+
+      // 1. CODESYS install detection
+      lines.push('=== CODESYS install ===')
+      const installs = detectCodesysInstalls()
+      if (installs.length === 0) {
+        lines.push('  No CODESYS 3.5.x install found under C:\\Program Files.')
+      } else {
+        for (const i of installs) lines.push(`  ${i.folder}  ->  ${i.path}`)
+      }
+
+      // 2. codesys-mcp-sp21-plus package + --print-config
+      lines.push('')
+      lines.push('=== codesys-mcp-sp21-plus (npm) ===')
+      let detectedPath: string | undefined
+      let detectedProfile: string | undefined
+      let packageInstalled = false
+      if (wantPrint) {
+        const pc = await runPrintConfig()
+        if (pc.ok && pc.raw) {
+          packageInstalled = true
+          const ex = extractPathProfileFromPrintConfig(pc.raw)
+          detectedPath = ex.path
+          detectedProfile = ex.profile
+          lines.push('  Installed. `--print-config` OK.')
+          if (detectedPath) lines.push(`  path:    ${detectedPath}`)
+          if (detectedProfile) lines.push(`  profile: ${detectedProfile}`)
+        } else if (pc.error === 'not-installed') {
+          lines.push('  NOT installed / not on PATH. Install with:')
+          lines.push('    npm install -g codesys-mcp-sp21-plus')
+        } else {
+          lines.push(`  \`--print-config\` failed: ${pc.error}`)
+        }
+      } else {
+        lines.push('  (print_config=false — skipped)')
+      }
+      if (!detectedPath && installs.length > 0) {
+        detectedPath = installs[0]!.path
+        lines.push(`  (using filesystem-scanned path for the snippet: ${detectedPath})`)
+      }
+      if (!detectedProfile) {
+        lines.push(
+          '  profile: UNKNOWN — run `codesys-mcp-sp21-plus --print-config` to get the exact string.',
+        )
+      }
+
+      // 3. .mcp.json inspection
+      lines.push('')
+      lines.push('=== .mcp.json ===')
+      const cwd = process.cwd()
+      const candidates = [
+        {
+          label: 'workspace',
+          path: (params.mcp_json_path ?? '').trim() || join(cwd, '.mcp.json'),
+        },
+        { label: 'user-global', path: join(homedir(), '.pi', 'agent', 'mcp.json') },
+      ]
+      let foundCodesysEntry = false
+      for (const c of candidates) {
+        const obj = readMcpJson(c.path)
+        if (!obj) {
+          lines.push(`  ${c.label}: (none)  ${c.path}`)
+          continue
+        }
+        lines.push(`  ${c.label}: ${c.path}`)
+        const codesys = findCodesysServers(obj)
+        if (codesys) {
+          foundCodesysEntry = true
+          for (const [k, e] of Object.entries(codesys)) {
+            const cp = argAfter(e.args, '--codesys-path')
+            const cf = argAfter(e.args, '--codesys-profile')
+            const mode = argAfter(e.args, '--mode')
+            const lifecycle = typeof e.lifecycle === 'string' ? e.lifecycle : '(unset)'
+            const dt = Array.isArray(e.directTools) ? e.directTools.length : 0
+            lines.push(`    server "${k}":`)
+            lines.push(`      command:    ${e.command ?? '?'}`)
+            if (cp) lines.push(`      codesys-path:    ${cp}`)
+            if (cf) lines.push(`      codesys-profile: ${cf}`)
+            if (mode) lines.push(`      mode:           ${mode}`)
+            lines.push(`      lifecycle: ${lifecycle}, directTools: ${dt}`)
+          }
+        } else {
+          lines.push('    (no codesys* server entry — add one using the snippet below)')
+        }
+      }
+
+      // 4. pi-mcp-adapter live?
+      lines.push('')
+      lines.push('=== pi-mcp-adapter ===')
+      let mcpTool = false
+      try {
+        mcpTool = pi.getAllTools().some((t) => t.name === 'mcp')
+      } catch {
+        /* getAllTools not available yet — treat as unknown */
+      }
+      if (mcpTool) {
+        lines.push('  `mcp` tool is registered — pi-mcp-adapter is enabled.')
+      } else {
+        lines.push(
+          '  `mcp` tool NOT registered — enable the pi-mcp-adapter package in the Capability manager, then restart the broker.',
+        )
+      }
+      if (mcpTool && !foundCodesysEntry) {
+        lines.push(
+          '  (adapter is live but no codesys server is configured — paste the snippet below into a .mcp.json.)',
+        )
+      }
+
+      // 5. Ready-to-paste snippet
+      if (detectedPath && detectedProfile) {
+        lines.push('')
+        lines.push('=== Augmented .mcp.json snippet (merge into your .mcp.json) ===')
+        const entry = buildAugmentedEntry(detectedPath, detectedProfile)
+        lines.push(JSON.stringify({ mcpServers: { codesys: entry } }, null, 2))
+        lines.push('')
+        lines.push('Notes:')
+        lines.push(
+          '  - directTools promote a ~24-tool curated surface as first-class Pi tools named codesys_<tool> ' +
+            '(codesys_create_pou, codesys_set_pou_code, codesys_compile_project, ...).',
+        )
+        lines.push(
+          '  - approveTools require confirmation before destructive/online ops (delete_object, write_variable, force_variables, download_to_device, ...).',
+        )
+        lines.push(
+          '  - lazy-keep-alive: CODESYS spawns on the first tool call and stays resident across turns; ' +
+            '--no-auto-launch keeps it from starting at broker boot.',
+        )
+        lines.push(
+          '  - --auto-mirror re-runs mirror_export after each change so the .st mirror stays in sync for undo ' +
+            '(Ctrl+Z in the IDE does NOT recover set_pou_code edits).',
+        )
+        lines.push('  - After editing .mcp.json, restart the broker so pi-mcp-adapter re-reads it.')
+      } else if (!packageInstalled) {
+        lines.push('')
+        lines.push(
+          'Next: `npm install -g codesys-mcp-sp21-plus`, then re-run codesys_setup_check to get the exact .mcp.json snippet.',
+        )
+      }
+
+      return toolText(lines.join('\n'))
+    },
+  })
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "sylo-codesys",
+  "version": "0.1.0",
+  "description": "Drive a live, open CODESYS V3.5 project from chat via the codesys-mcp-sp21-plus MCP server, bridged through pi-mcp-adapter. Skill + setup/diagnostic tool. No host MCP client.",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills/codesys"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
+  "license": "MIT"
+}

package/skills/codesys/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: codesys
+description: Drive a live, open CODESYS V3.5 project from chat — create POUs, write Structured Text, compile, read/write PLC variables — via the codesys-mcp-sp21-plus MCP server bridged through pi-mcp-adapter.
+metadata:
+  sylo:
+    category: automation
+    icon: cpu
+---
+
+# CODESYS — live project via MCP
+
+You drive a **live, open CODESYS V3.5 project** from chat. Every change is
+applied to the project the operator has open and appears in the CODESYS IDE in
+real time. It is the standalone CODESYS chat experience for live projects.
+
+## How this is wired (the part you cannot see)
+
+These CODESYS tools are **not** built into Sylo. They come from the external
+`codesys-mcp-sp21-plus` stdio MCP server, surfaced into Pi by the
+**pi-mcp-adapter** package once a `codesys` server is configured in a
+workspace `.mcp.json`. If the wiring is missing or broken, your tool calls will
+fail — fix the wiring, don't keep retrying blindly.
+
+**Run `codesys_setup_check` first** whenever CODESYS is the task or a call
+fails. It reports: is CODESYS installed? is `codesys-mcp-sp21-plus` on PATH? is
+there a `codesys` server in `.mcp.json`? is the `mcp` adapter tool live? It also
+emits a ready-to-paste `.mcp.json` snippet. Tell the operator the gaps and the
+exact fix (install command / enable pi-mcp-adapter / paste snippet / restart
+broker).
+
+## Two ways to call the tools
+
+1. **Direct tools** (if `directTools` is configured in `.mcp.json`): a curated
+   ~24-tool surface is registered as first-class Pi tools named `codesys_<mcp_name>`:
+   `codesys_get_codesys_status`, `codesys_get_project_info`, `codesys_get_all_pou_code`,
+   `codesys_create_pou`, `codesys_set_pou_code`, `codesys_create_method`,
+   `codesys_create_property`, `codesys_create_dut`, `codesys_create_gvl`,
+   `codesys_create_folder`, `codesys_delete_object`, `codesys_rename_object`,
+   `codesys_save_project`, `codesys_compile_project`, `codesys_get_compile_messages`,
+   `codesys_add_library`, `codesys_list_project_libraries`, `codesys_connect_to_device`,
+   `codesys_read_variable`, `codesys_write_variable`, `codesys_start_stop_application`,
+   `codesys_get_application_state`, `codesys_mirror_export`, `codesys_shutdown_codesys`.
+   Prefer these when they fit — no search round-trip.
+
+2. **The `mcp` proxy** for everything else (the other ~78 tools, plus resources).
+   Discover → describe → call:
+   ```
+   mcp({ search: "symbol config" })          // find candidate tools
+   mcp({ describe: "create_symbol_config" })  // read the schema
+   mcp({ tool: "create_symbol_config", args: { projectFilePath: "C:/p.project", ... } })
+   ```
+   **Project structure is an MCP resource, not a tool**: read it via the proxy
+   with the resource URI `codesys://project/{+project_path}/structure` (the
+   adapter exposes resources as tools when `exposeResources` is on). For a plain
+   project-info read, use the `codesys_get_project_info` direct tool.
+
+## `projectFilePath` is required on every tool
+
+Every CODESYS tool takes `projectFilePath` (absolute path to the open `.project`
+file, forward or back slashes both work). **Determine it before calling:**
+- Ask the operator which `.project` they have open, or
+- Look in the workspace for `*.project`, or
+- Run `codesys_setup_check` (it lists the detected CODESYS install but not the
+  project — the project path still comes from the operator/workspace).
+
+The server's `ensure_project_open` helper opens the project if it isn't already
+open, so passing the correct path is sufficient.
+
+## Discipline
+
+- **Inspect before editing.** Call `codesys_get_project_info` + `codesys_get_all_pou_code`
+  (or the structure resource) to understand the project. Don't edit blind.
+- **Always compile after authoring.** After `create_pou` / `set_pou_code` /
+  `create_method` / `create_dut` / `create_gvl` / `add_library` / `rename_object`,
+  call `codesys_compile_project` and **report errors/warnings to the operator
+  before declaring success.** Use `codesys_get_compile_messages` for detail.
+  These modifying tools **auto-save** the project on success.
+- **Confirm destructive ops.** `delete_object`, `write_variable` (forces),
+  `download_to_device`, `reset_application`, `shutdown_codesys`, `remove_library`
+  are approval-gated (the operator clicks to confirm). Still announce intent in
+  chat first — e.g. "I'm about to delete `Application/OldPou` — confirm?"
+- **Undo caveat.** `set_pou_code` writes the live binary; **Ctrl+Z in the IDE
+  does NOT recover it.** With `--auto-mirror` configured, each change re-runs
+  `mirror_export` to a `.st` mirror on disk — commit that mirror to git for
+  real undo. Call `codesys_mirror_export` to refresh it on demand.
+
+## Online / runtime
+
+- `codesys_connect_to_device` may pop a **"Device User Login" modal in the
+  CODESYS IDE** that the agent cannot see or dismiss. **Announce this to the
+  operator before calling** and tell them to be ready to click. To suppress it,
+  set `CODESYS_DEVICE_USER` / `CODESYS_DEVICE_PASSWORD` in the `codesys` server
+  `env` block of `.mcp.json`.
+- Read/write variables require an online connection first (`codesys_connect_to_device`).
+- `codesys_get_application_state` returns run / stop / exception + logged-in status.
+
+## Lifecycle
+
+The first tool call launches CODESYS **persistent (UI visible)**; with the
+recommended `lazy-keep-alive` lifecycle the instance stays resident across turns
+so subsequent calls are fast (cold launch + watcher ready can take 60s+). To stop
+CODESYS from chat, call `codesys_shutdown_codesys` (it relaunches on the next
+tool call). If the operator already has CODESYS open with the project, the
+bridge uses that instance.
+
+## ⚠️ UI lock — CODESYS scripting engine is single-threaded
+
+**While the MCP bridge is active, the operator has limited ability to interact
+with the CODESYS IDE.** The bridge runs a watcher script inside CODESYS's
+scripting engine, which is single-threaded. The watcher loop (`system.delay()`
+polling) blocks new commands — direct double-click navigation and menu actions
+are locked.
+
+**Workaround:** right-clicking still works (it's a raw Win32 event that
+bypasses CODESYS's `StartLengthyOperation` gate). After right-clicking on an
+object, double-clicking to open it works. This is not a bug — it's a side
+effect of `system.delay()` pumping the Win32 message loop while
+`StartLengthyOperation()` blocks CODESYS-level commands. See the [CODESYS
+scripting docs on `system.delay`](https://product-help.se.com/docs/Machine+Expert/V1.1/en/ScriptEngine/topics/system.htm).
+
+**What works vs. what's blocked in the agent's instance:**
+- ✅ Right-click (raw Win32 event bypasses the gate)
+- ✅ Open a POU via right-click → double-click
+- ❌ Scroll the editor (CODESYS editor command — blocked)
+- ❌ Menu bar, typing, editing (blocked)
+
+You can open a POU and see the top of the code, but **you cannot scroll to
+read further down.** For reading long routines, use the second read-only
+instance (below) or ask the agent to dump the code to chat.
+
+This is a fundamental limitation of the CODESYS scripting engine, not a bug in
+the MCP server.
+
+### Recommended workflow: second read-only CODESYS instance
+
+The cleanest workflow uses **two CODESYS instances** — one for the agent
+(MCP bridge), one for the operator (read-only inspection):
+
+1. **Agent's instance** — launched by the MCP server, runs the watcher script,
+   UI is locked. This is where tool calls create POUs, write ST, compile, etc.
+2. **Operator's instance** — a second CODESYS window opened separately (e.g.
+   launch CODESYS manually, File → Open Project, pick the same `.project` file).
+   This instance is fully interactive — the operator can navigate, inspect code,
+   double-click POUs, etc. without interfering with the bridge.
+3. **Seeing live updates** — CODESYS does NOT auto-detect external file changes
+   and has no "reload from disk" button. But the operator can **reopen the
+   project without closing CODESYS first** (File → Open Project → select the
+   same `.project`). This reloads the project from disk with all the agent's
+   changes, without killing the agent's MCP-connected instance.
+4. **When the agent is done with a batch** — the operator reopens the project
+   in the read-only instance to inspect the results. No kill, no relaunch, no
+   Sylo restart needed.
+
+This avoids the kill/relaunch cycle entirely for routine inspection. Only use
+the recovery procedure below if the watcher actually dies (cancel, close, or
+   crash).
+
+### Recovery when the watcher dies (cancel, close, or crash)
+
+No Sylo restart is needed. The MCP server child process is still alive
+(lazy-keep-alive keeps it resident), but the watcher inside CODESYS is dead —
+tool calls will time out (60s). To recover:
+
+1. The agent kills the dead CODESYS process from bash:
+   ```bash
+   taskkill /F /IM CODESYS.exe
+   ```
+2. The next tool call relaunches CODESYS with a fresh watcher and reopens the
+   project automatically.
+
+Alternatively, call `codesys_launch_codesys_with_project` with
+`killExisting=true` — it kills the orphan and relaunches in one step.
+
+### Orphaned CODESYS after Sylo broker restart
+
+If the Sylo broker restarts (or the machine reboots), the MCP server child
+process dies but the CODESYS window it launched stays open as an orphan. The
+new MCP server instance refuses to share IPC with the orphan:
+
+> `Refusing to launch: 1 CODESYS.exe instance(s) of the same install already
+> running... This MCP server cannot share IPC with an instance it didn't spawn.`
+
+Fix: kill the orphan (`taskkill /F /IM CODESYS.exe`) or call
+`launch_codesys_with_project` with `killExisting=true`, then the next tool call
+works normally.
+
+## Argument cheat-sheet (most-used tools)
+
+```js
+// Create a POU (type: Program | FunctionBlock | Function; language: ST | LD | FBD | SFC | IL | CFC)
+codesys_create_pou({
+  projectFilePath: "C:/Projects/MyPLC.project",
+  name: "FB_Motor",
+  type: "FunctionBlock",
+  language: "ST",
+  parentPath: "Application",            // relative path under the project root
+  declarationCode: "FUNCTION_BLOCK FB_Motor\nVAR\n  bRun : BOOL;\nEND_VAR",
+  implementationCode: "IF bRun THEN\n  ;\nEND_IF"   // optional
+})
+
+// Write declaration and/or implementation of an existing POU / method / property
+codesys_set_pou_code({
+  projectFilePath: "C:/Projects/MyPLC.project",
+  pouPath: "Application/FB_Motor",      // slash path to the object
+  declarationCode: "...",               // omit a field to leave it unchanged
+  implementationCode: "..."
+})
+
+// Create a method on an FB (returnType optional; pass code or leave empty + set_pou_code later)
+codesys_create_method({
+  projectFilePath: "...",
+  parentPouPath: "Application/FB_Motor",
+  methodName: "Reset",
+  returnType: "BOOL",
+  implementationCode: "Reset := TRUE;"
+})
+
+// DUT (dutType: Structure | Enumeration | Union | Alias) / GVL / folder
+codesys_create_dut({ projectFilePath: "...", name: "ST_Axis", dutType: "Structure", parentPath: "Application" })
+codesys_create_gvl({ projectFilePath: "...", name: "GVL_IO",  parentPath: "Application", declarationCode: "VAR_GLOBAL\n  bReady : BOOL;\nEND_VAR" })
+
+// Build + messages
+codesys_compile_project({ projectFilePath: "..." })
+codesys_get_compile_messages({ projectFilePath: "..." })
+
+// Libraries (name must match the installed Library Repository; refuses unknown libs)
+codesys_add_library({ projectFilePath: "...", libraryName: "Standard" })
+codesys_list_project_libraries({ projectFilePath: "..." })
+
+// Online
+codesys_connect_to_device({ projectFilePath: "..." })        // may pop a login modal
+codesys_read_variable({ projectFilePath: "...", variablePath: "PLC_PRG.bMotorRunning" })
+codesys_write_variable({ projectFilePath: "...", variablePath: "PLC_PRG.bMotorRunning", value: "TRUE" })
+codesys_start_stop_application({ projectFilePath: "...", action: "start" })  // action: start | stop
+codesys_get_application_state({ projectFilePath: "..." })
+```
+
+**Searching across POUs:** there is no `search_code` tool. Call
+`codesys_get_all_pou_code` (returns all declarations + implementations) and grep
+the returned text. The project tree is the `codesys://project/{+path}/structure`
+resource, read via the `mcp` proxy.
+
+## Scope
+
+This skill is only for **live CODESYS V3.5 projects** driven through the MCP
+server. It is not for projects edited as plain files on disk with no CODESYS
+running.