@vention/vention-skills 0.9.11 → 0.9.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vention",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "author": {
     "name": "Vention"

package/README.md

@@ -1,6 +1,6 @@
 # Vention skills
 
-Version 0.9.11. Skills for coding agents that work with Vention machines, packaged as one plugin, `vention`, in the `vention-skills` marketplace.
+Version 0.9.13. Skills for coding agents that work with Vention machines, packaged as one plugin, `vention`, in the `vention-skills` marketplace.
 
 | Skill                       | What it does                                                                                                                         |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vention/vention-skills",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "license": "MIT",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vention",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "author": {
     "name": "Vention"

package/skills/vention-design/SKILL.md

@@ -3,7 +3,7 @@ name: vention-design
 description: Create, build and edit Vention machine designs and design graphs for agentic layout. Use when the user wants to start a new design, lay out an automation cell, add or reposition components in a Vention design, generate a machine layout from a description, add or place a floor plan image under a design, list a design's versions, or inspect an existing design graph. Trigger on MachineBuilder designs, design graphs, assembly graphs, extrusions, actuators, robot mounting, cell footprints, floor plans, or a machine-builder URL.
 license: MIT
 metadata:
-  version: "0.9.11"
+  version: "0.9.13"
   author: Vention
 ---
 

package/skills/vention-machine-logic/SKILL.md

@@ -3,7 +3,7 @@ name: vention-machine-logic
 description: Write, edit, validate, and deploy MachineLogic Python applications for Vention machines with the machine-logic-sdk and the Vention CLI. Load it before writing or changing any Python that talks to a Vention machine, however short, since device names and version-specific SDK calls come from here. Use to program a Vention machine or MachineMotion controller, drive actuators, conveyors, robots, pneumatics, or digital I/O, change an existing application, build a state machine, debug from logs, or pull, push, or link with the Vention CLI (vention or vn). Trigger on MachineLogic, machine-logic-sdk, MachineMotion, MachineBuilder applications, the Vention CLI, or a directory holding .machine-code-app-directory-info.json. Printing what the machine or robot holds now (positions, taught targets, calibration, I/O) is a program: files on disk hold only as-designed values. Not for explaining an existing machine or its configuration in words when no program is asked for, nor for Python that never touches the machine.
 license: MIT
 metadata:
-  version: "0.9.11"
+  version: "0.9.13"
   machine-logic-sdk: ">=3.0,<4"
   author: Vention
 ---
@@ -216,6 +216,8 @@ pose[2] += 20.0
 robot.movel(pose, 50.0, 100.0)
 ```
 
+The scene holds only the design's library-level positions. A Python application cannot read the variables or expression frames a code-free application keeps, and it cannot own scene assets of its own. When a step needs one of those positions, ask the user to teach it as a library target. A pose given as an offset on a frame can instead be computed the way `move_to_target` resolves a cartesian target: `transform_position_between_ref_frames(offset, from_reference_frame=frame.get_calibrated_value() or frame.get_default_value())`, from `machinelogic.machinelogic.utils.robot_transforms`.
+
 ## Complete examples
 
 Each example is a standalone `main.py` whose module docstring names the device names it assumes. Copy the structure, then replace the names with the ones in the user's configuration.
@@ -244,6 +246,15 @@ Each example is a standalone `main.py` whose module docstring names the device n
 5. Read the output with `vention logs`. MachineLogic failures name the device and the reason; read the log before proposing a change.
 6. Show the user the diff before pushing over an application they did not write in this session.
 
+## Deploying to a real cell
+
+The controller keeps its own scene. Positions re-taught on the pendant and the controller's calibrations live only there, not on the design.
+
+- Deploy over the LAN from the application's Deploy menu in MachineBuilder with only the application ticked. "Design-level Scene Assets" replaces the controller's positions with the design's, including every one re-taught on the pendant, and "Configuration" replaces its configuration.
+- When the application needs a position the controller lacks, ask the user to teach it on the pendant under the same name it has on the design.
+- Deploying restarts the application, so deploy only while the cell is idle.
+- `print` what someone reading the controller's log needs, such as a step starting, a part finished or a fault. An HMI's event stream does not reach the log.
+
 ## Safety
 
 This code drives physical machinery that can injure someone.
@@ -265,6 +276,7 @@ This code drives physical machinery that can injure someone.
 - Hard-coding a pose the scene already holds under a taught name.
 - Creating `Machine()` at import time, or twice in one process.
 - Treating a simulation pass as evidence the program is safe on hardware.
+- Ticking "Design-level Scene Assets" on a LAN deploy, which overwrites the positions re-taught on the pendant.
 - `pip install machinelogic`: the package is `machine-logic-sdk`; only the import is `machinelogic`.
 - Calling a blocking SDK method (a wait, `home`, a blocking move) directly inside `async def`, or using `asyncio.TaskGroup` (Python 3.11) on a 3.10 target.
 - Assuming a cancelled task stopped its move.

package/skills/vention-machine-logic-hmi/SKILL.md

@@ -3,7 +3,7 @@ name: vention-machine-logic-hmi
 description: Build or edit the custom operator HMI of a MachineLogic application, the React touch screen in customui/ that runs in MachineBuilder and on the MachineMotion pendant, wired to the application's Python process through vention-communication. Use when the user asks for an operator screen, a custom HMI or UI, a touch panel, start and stop buttons, live machine state on screen, or recipes an operator picks, for a Vention machine or inside a directory holding .machine-code-app-directory-info.json. Uses @vention/machine-ui, @vention/machine-apps-components and @vention/machine-logic-ui-sdk. Do not use for the no-code HMI Builder, or for the Python motion logic alone (that is vention-machine-logic).
 license: MIT
 metadata:
-  version: "0.9.11"
+  version: "0.9.13"
   author: Vention
 ---
 
@@ -25,13 +25,16 @@ Once per session, before any other work, check for a newer version of the Ventio
 | --- | --- |
 | `customui/` | The HMI source and its `package.json`. The engine runs `npm install`, then `npm run build`, in it. |
 | `ui/` | Build output only. The build script writes `../ui/index.html` and `../ui/assets/`. Never edit it or read versions from it. |
-| `project.json` | One process under `processes.onPlay`: `{ name, command, port }`. The command sets its own port. |
+| `project.json` | One process under `processes.onPlay`: `{ name, command, port }`. The command sets its own port. `ui.showDefaultBackToControlCenterButton` is `false`, because the `NavigationBar` carries the Control Center button. |
 | `requirements.txt` | Exact pins for `machine-logic-sdk`, `vention-communication`, `vention-state-machine`, `vention-storage` and `uvicorn`. |
 | `proto/app.proto` | Written by `app.finalize()` when `server.py` is imported. Commit it; never edit it. |
 | `customui/src/gen/` | The client `buf generate ../proto` writes before every build. Gitignored; never commit or edit it. |
 
 ```json
-{ "processes": { "onPlay": [{ "name": "indexing-station", "command": "python3 -m uvicorn server:app --host 0.0.0.0 --port 8000", "port": 8000 }] } }
+{
+  "processes": { "onPlay": [{ "name": "indexing-station", "command": "python3 -m uvicorn server:app --host 0.0.0.0 --port 8000", "port": 8000 }] },
+  "ui": { "showDefaultBackToControlCenterButton": false }
+}
 ```
 
 ## The Python surface
@@ -148,6 +151,9 @@ The machine-apps-components README is behind its code: `NavigationBar` takes `Na
 ## Design rules
 
 - Wrap the app in `machineUiHmiTheme`.
+- Show each piece of information in one place only. The `StatusTopBar` already shows the state, so a page never repeats it, not even as a status indicator or an alert titled with the same word. A page adds only what the bar cannot say: the cause of a fault, what happens next, what to do.
+- The screen fits the pendant without scrolling: keep `body { margin: 0 }` from the example's `index.html`, or the full-viewport root overflows it. Only the page area between the two bars scrolls.
+- Exactly one way back to Control Center: the `NavigationBar`'s own button, which confirms before leaving. Keep `ui.showDefaultBackToControlCenterButton` `false` in `project.json`, or the pendant lays a second one over the screen.
 - Set `size="x-large"` or `size="xx-large"` on every control that takes a size. The default `"small"` is 24 px, below the 44 px touch minimum.
 - Text uses the `heading*` and `paragraph*` typography variants: `heading24SemiBold` for what the operator must see from a distance, such as the cycle count, `heading18SemiBold` for labels, `paragraph18Medium` for detail. The theme marks `hmiText*` deprecated.
 - Leave at least 16 px between adjacent touch targets and 24 px between buttons with opposite effects, such as Save and Delete. `theme.spacing` is a lookup table, not a multiplier: `gap: 2` is 8 px, `gap: 4` is 16 px, `gap: 5` is 24 px.
@@ -164,7 +170,7 @@ The machine-apps-components README is behind its code: `NavigationBar` takes `Na
 1. In the application directory, with the `requirements.txt` packages installed locally: `python3 -c "import server"` to re-emit `proto/app.proto`, and commit it if `git status` shows a change.
 2. In `customui/`: `npm install`, `npm run build`, then `npx tsc --noEmit`, and check that `ui/index.html` exists and loads its script from `./assets/`, a relative path.
 3. `vention push`, then open the HMI from the MachineLogic tab in MachineBuilder and run it on the digital twin before any hardware run.
-4. Read `vention logs` when a command fails; the server's errors land there.
+4. Read `vention logs` when a command fails; the server's errors land there. On a real controller, read them as the `vention-machine-logic` skill's "Deploying to a real cell" says.
 
 ## Safety
 
@@ -172,7 +178,8 @@ The HMI drives physical machinery that can injure someone.
 
 - Start never fires on page load, on reconnect, or from a stream message. Only an operator's tap, confirmed in a modal, starts motion.
 - Start and Stop live in the `StatusTopBar`, so they are on every page. Do not repeat them on a page. Raise the bar above `theme.zIndex.modal`, as the example's `app.tsx` does, or an open `VentionModal` covers Stop.
-- Stop stays enabled unless the station is known to be ready. That includes while the stream is disconnected: a dropped stream may hide a moving machine. Every other command is disabled while disconnected.
+- Stop stays enabled unless the station is known to be ready or already stopping. That includes while the stream is disconnected: a dropped stream may hide a moving machine. Every other command is disabled while disconnected.
+- A tap on Stop shows at once. While the station stops, the Stop button reads "Stopping…", the Run page's progress bar marks where the run now ends (the cycle in progress amber, the cancelled ones hatched and struck through), and a line by the heading says the emergency stop halts at once. Say it on the screen the operator already watches rather than in a separate alert.
 - Send Start with a `timeoutMs` and an abort signal, and abort it when the stream drops. A Start the operator can no longer see must not land later; say it was not confirmed and to check the station.
 - The HMI never offers a way around an emergency stop, safety interlock, light curtain or guard, not even a hidden one for testing.
 - The confirmation for anything that starts motion says what will move. The button itself can just say Start.
@@ -208,5 +215,8 @@ The HMI drives physical machinery that can injure someone.
 - `BrowserRouter`, whose routes miss under `.../index.html`.
 - Reading versions from `ui/package.json`; the manifest is `customui/package.json`.
 - Disabling Stop whenever the stream drops.
+- A Stop that looks the same before and after the tap while the station finishes its move.
+- The state shown in the `StatusTopBar` and again on a page.
+- `severity="warning"` on a `VentionAlert`. It is `"warn"`.
 - `--legacy-peer-deps` to get past a peer dependency conflict. Pin versions whose peers agree, as the example does.
 - A Start still in flight after the connection drops.

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/index.html

@@ -3,6 +3,11 @@
   <head>
     <meta charset="UTF-8" />
     <title>Indexing station</title>
+    <style>
+      body {
+        margin: 0;
+      }
+    </style>
   </head>
   <body>
     <div id="root"></div>

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/app.tsx

@@ -10,7 +10,7 @@ import type { Event, Recipe } from "./gen/app_pb"
 import { LogsPage } from "./pages/logs-page"
 import { RecipesPage } from "./pages/recipes-page"
 import { RunPage } from "./pages/run-page"
-import { canStart, canStop, describeState, errorText } from "./station"
+import { canStart, canStop, describeState, errorText, isStopping } from "./station"
 import { useStream } from "./use-stream"
 
 // Events are kept in memory from when the HMI opened, so the cap bounds a long shift.
@@ -100,7 +100,7 @@ export function App() {
             },
             {
               id: "stop",
-              label: "Stop",
+              label: isStopping(status, connected) ? "Stopping…" : "Stop",
               onClick: stop,
               disabled: !canStop(status, connected),
               backgroundColor: COLORS.red[600],

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/pages/run-page.tsx

@@ -1,9 +1,9 @@
 import { Box, Typography } from "@mui/material"
-import { VentionAlert, VentionSelect, VentionStatusIndicator } from "@vention/machine-ui"
+import { COLORS, VentionAlert, VentionSelect } from "@vention/machine-ui"
 import { useEffect, useState } from "react"
 import { client } from "../client"
 import type { Recipe, StationStatus } from "../gen/app_pb"
-import { canStart, describeState, errorText } from "../station"
+import { canStart, errorText, isStopping } from "../station"
 
 interface RunPageProps {
   status: StationStatus | undefined
@@ -13,9 +13,30 @@ interface RunPageProps {
   onError: (message: string) => void
 }
 
+const HATCHED = `repeating-linear-gradient(45deg, ${COLORS.slate[100]} 0 8px, ${COLORS.slate[200]} 8px 16px)`
+
+/** Done cycles green, the current one amber while stopping, and the cycles Stop cancels hatched. */
+function CycleProgress({ cycle, cycleCount, stopping }: { cycle: number; cycleCount: number; stopping: boolean }) {
+  const cancelled = stopping && cycleCount > cycle
+  const segment = (count: number, background: string) => <Box sx={{ flex: count, height: 16, borderRadius: 1, background }} />
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Box sx={{ display: "flex", gap: 1 }}>
+        {cycle > 1 && segment(cycle - 1, COLORS.green[500])}
+        {segment(1, stopping ? COLORS.amber[500] : COLORS.green[200])}
+        {cycleCount > cycle && segment(cycleCount - cycle, cancelled ? HATCHED : COLORS.slate[100])}
+      </Box>
+      <Typography variant="heading18SemiBold">
+        Cycle {cycle} of {cancelled ? <s>{cycleCount}</s> : cycleCount}
+        {stopping && ", stopping after the move in progress"}
+      </Typography>
+    </Box>
+  )
+}
+
 export function RunPage({ status, connected, recipe, onRecipeChange, onError }: RunPageProps) {
   const [recipes, setRecipes] = useState<Recipe[]>([])
-  const state = describeState(status, connected)
+  const stopping = isStopping(status, connected)
 
   useEffect(() => {
     if (!connected) return
@@ -31,21 +52,23 @@ export function RunPage({ status, connected, recipe, onRecipeChange, onError }:
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 6, maxWidth: 960 }}>
-      <VentionStatusIndicator size="xx-large" outline dotColor={state.color} label={state.label} />
       {status !== undefined && status.fault !== "" && (
         <VentionAlert
           severity="error"
           size="xx-large"
-          title="Fault"
-          descriptionText={status.fault}
+          title={status.fault}
           primaryButtonText={connected && status.state === "fault" ? "Reset" : undefined}
           onPrimaryButtonClick={reset}
         />
       )}
       <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
-        <Typography variant="heading24SemiBold">
-          {status?.recipeName ? `${status.recipeName}: cycle ${status.cycle}/${status.cycleCount}` : "No recipe running"}
-        </Typography>
+        <Box sx={{ display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 4 }}>
+          <Typography variant="heading24SemiBold">{status?.recipeName || "No recipe running"}</Typography>
+          {stopping && <Typography variant="paragraph18Medium">The emergency stop halts at once.</Typography>}
+        </Box>
+        {status?.state.startsWith("Station_") && status.cycle > 0 && (
+          <CycleProgress cycle={status.cycle} cycleCount={status.cycleCount} stopping={stopping} />
+        )}
         <Typography variant="paragraph18Medium">
           Last cycle: {status && status.lastCycleSeconds > 0 ? `${status.lastCycleSeconds.toFixed(1)} s` : "none yet"}
         </Typography>

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/station.ts

@@ -24,9 +24,13 @@ export function canStart(status: StationStatus | undefined, connected: boolean):
   return connected && status?.state === "ready" && status.fault === ""
 }
 
-/** Stop is disabled only when the station is known to be ready: a dropped stream may hide a moving conveyor. */
+export function isStopping(status: StationStatus | undefined, connected: boolean): boolean {
+  return connected && status?.state === "Station_stopping"
+}
+
+/** Stop is disabled only when the station is known to be ready or already stopping: a dropped stream may hide a moving conveyor. */
 export function canStop(status: StationStatus | undefined, connected: boolean): boolean {
-  return !(connected && status?.state === "ready")
+  return !(connected && status?.state === "ready") && !isStopping(status, connected)
 }
 
 export function errorText(error: unknown): string {

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/project.json

@@ -2,5 +2,5 @@
   "processes": {
     "onPlay": [{ "name": "indexing-station", "command": "python3 -m uvicorn server:app --host 0.0.0.0 --port 8000", "port": 8000 }]
   },
-  "ui": { "showDefaultBackToControlCenterButton": true }
+  "ui": { "showDefaultBackToControlCenterButton": false }
 }

package/skills/vention-monitoring/SKILL.md

@@ -3,7 +3,7 @@ name: vention-monitoring
 description: Diagnose deployed Vention machines from controller state, history, health, and activity data. Use when the user reports a machine that is down, faulted, offline, slow, or underperforming, asks why a cycle time regressed, wants to interpret MachineMotion event data or drive and brake status, asks about OEE or uptime, or wants to know which machine in a fleet needs attention. Trigger on a MachineMotion serial number plus any complaint.
 license: MIT
 metadata:
-  version: "0.9.11"
+  version: "0.9.13"
   author: Vention
 ---