PUDA Deployment
Overview
Use this skill to install a new PUDA-connected tool or diagnose an incomplete installation. Work from high-level infrastructure down to physical labware. Stop at the first failed gate; do not skip to motion to compensate for a software or connection failure.
When to use
- Installing PUDA, NATS, a driver repository, or an edge service.
- Moving a working installation to another site or host.
- Diagnosing missing/stale machine discovery, dependency/build failures, controller errors, or alignment problems.
- Creating an installation log, incident record, or reusable SOP for a new tool.
- Exporting deployment logs and learnings as a zip for the user.
Do not use deployment as permission to move hardware. Motion, homing, gripping, or process commands require separate authorization and a clear workspace.
Progressive gate sequence
- System model: Read references/system-and-gates.md. Record site, host, tool, machine ID, controller transport, and owners.
- Host: Run
scripts/preflight.sh. Verify required commands, Docker access, clock, disk, and permissions.
- Network/NATS: Read references/network-and-nats.md, run the read-only inspectors, and prove host-to-controller and client-to-broker routes separately.
- PUDA: Read references/puda-cli-project.md. Verify CLI version, login, skills, project root, and configured NATS endpoints.
- Source/package: Read references/edge-packaging.md. Verify repository access, clean Git state, Python/uv workspace packaging, Docker context, and environment loading.
- Edge readiness: Start/recreate only after configuration review. Require driver initialized → NATS connected → command consumers ready → acceptable queue state → fresh discovery/state.
- Controller: Read references/hardware-commissioning.md. Use one session owner, read-only communication first, then a separately authorized low-risk command.
- Labware: Read references/labware-alignment.md. Calibrate approach, intermediate, and process poses with provenance and tolerances.
- Operations/recovery: Read references/operations-recovery.md. Validate live command exposure, protocol schema, stop boundaries, and incident recovery.
- Failure lookup: Use references/error-catalog.md by symptom; append new proven errors after resolution.
Mandatory evidence model
Report each layer independently:
| Layer |
Minimum evidence |
| Host |
command/version/permission checks |
| Broker |
listener plus successful NATS handshake/health probe |
| PUDA |
configured endpoint, project, login, CLI output |
| Edge |
logs showing driver initialization, NATS connection, subscriptions, queue state |
| Controller |
valid read-only response through the owning edge session |
| Machine |
authorized command result plus independent measurement when physical |
| Labware |
dated alignment record, frame, tolerance, and verifier |
A heartbeat or idle state is not proof of controller readiness. A returned motion target is not proof of measured final pose. A digital-output acknowledgment is not proof of jaw state.
Installation logging
Copy templates/deployment-record.md before starting. Append actions and actual outputs as work proceeds. Use templates/incident-record.md when a command times out, is interrupted, or produces uncertain physical state. Redact secrets and never rewrite history to hide failed attempts.
Export logs and learnings
When asked to export the PUDA deployment logs and learnings:
- Collect everything from the deployment session: filled deployment/incident records, site and machine profiles, labware alignment records, error-catalog updates, and any other logs or learnings produced during the work. Redact secrets.
- Resolve the zip name from the PUDA CLI username and today's date:
- Username:
puda config get user.username
- Date:
YYYY-MM-DD (UTC)
- Filename:
<username>-<YYYY-MM-DD>.zip (example: zhao-2026-07-22.zip)
- Zip the collected files under that name and send the archive to the user.
Completion criteria
A deployment is complete only when:
- Every applicable gate is checked with fresh evidence.
- The expected machine appears with a fresh timestamp and live command registry.
- Controller communication succeeds through the edge-owned path.
- Any authorized physical commissioning result is independently verified.
- Labware coordinates have provenance and tolerance records.
- Environment templates contain placeholders, not credentials.
- Installation and unresolved risks are recorded.
Common pitfalls
localhost in a container points to the container unless host networking is deliberate.- A shallow Docker healthcheck can stay green during driver retry loops.
- PUDA login does not grant private GitHub repository access.
puda protocol validate does not prove a command is exposed by the live edge.- Restarting/rebuilding can change controller session or queue behavior; inspect before retrying.
- A second controller diagnostic session may disrupt the edge-owned session.
- Site-specific IPs, coordinates, and active-low outputs are not portable defaults.
1---2name: puda-deployment3description: Use when installing, commissioning, transferring, or troubleshooting a PUDA edge driver, or when asked to export PUDA deployment logs and learnings. Applies a progressive host-to-labware SOP, records software and hardware failures, and requires evidence at every readiness gate.4license: MIT5---67# PUDA Deployment89## Overview1011Use this skill to install a new PUDA-connected tool or diagnose an incomplete installation. Work from high-level infrastructure down to physical labware. Stop at the first failed gate; do not skip to motion to compensate for a software or connection failure.1213## When to use1415- Installing PUDA, NATS, a driver repository, or an edge service.16- Moving a working installation to another site or host.17- Diagnosing missing/stale machine discovery, dependency/build failures, controller errors, or alignment problems.18- Creating an installation log, incident record, or reusable SOP for a new tool.19- Exporting deployment logs and learnings as a zip for the user.2021Do not use deployment as permission to move hardware. Motion, homing, gripping, or process commands require separate authorization and a clear workspace.2223## Progressive gate sequence24251. **System model:** Read [references/system-and-gates.md](references/system-and-gates.md). Record site, host, tool, machine ID, controller transport, and owners.262. **Host:** Run `scripts/preflight.sh`. Verify required commands, Docker access, clock, disk, and permissions.273. **Network/NATS:** Read [references/network-and-nats.md](references/network-and-nats.md), run the read-only inspectors, and prove host-to-controller and client-to-broker routes separately.284. **PUDA:** Read [references/puda-cli-project.md](references/puda-cli-project.md). Verify CLI version, login, skills, project root, and configured NATS endpoints.295. **Source/package:** Read [references/edge-packaging.md](references/edge-packaging.md). Verify repository access, clean Git state, Python/uv workspace packaging, Docker context, and environment loading.306. **Edge readiness:** Start/recreate only after configuration review. Require driver initialized → NATS connected → command consumers ready → acceptable queue state → fresh discovery/state.317. **Controller:** Read [references/hardware-commissioning.md](references/hardware-commissioning.md). Use one session owner, read-only communication first, then a separately authorized low-risk command.328. **Labware:** Read [references/labware-alignment.md](references/labware-alignment.md). Calibrate approach, intermediate, and process poses with provenance and tolerances.339. **Operations/recovery:** Read [references/operations-recovery.md](references/operations-recovery.md). Validate live command exposure, protocol schema, stop boundaries, and incident recovery.3410. **Failure lookup:** Use [references/error-catalog.md](references/error-catalog.md) by symptom; append new proven errors after resolution.3536## Mandatory evidence model3738Report each layer independently:3940| Layer | Minimum evidence |41|---|---|42| Host | command/version/permission checks |43| Broker | listener plus successful NATS handshake/health probe |44| PUDA | configured endpoint, project, login, CLI output |45| Edge | logs showing driver initialization, NATS connection, subscriptions, queue state |46| Controller | valid read-only response through the owning edge session |47| Machine | authorized command result plus independent measurement when physical |48| Labware | dated alignment record, frame, tolerance, and verifier |4950A heartbeat or `idle` state is not proof of controller readiness. A returned motion target is not proof of measured final pose. A digital-output acknowledgment is not proof of jaw state.5152## Installation logging5354Copy `templates/deployment-record.md` before starting. Append actions and actual outputs as work proceeds. Use `templates/incident-record.md` when a command times out, is interrupted, or produces uncertain physical state. Redact secrets and never rewrite history to hide failed attempts.5556## Export logs and learnings5758When asked to export the PUDA deployment logs and learnings:59601. Collect everything from the deployment session: filled deployment/incident records, site and machine profiles, labware alignment records, error-catalog updates, and any other logs or learnings produced during the work. Redact secrets.612. Resolve the zip name from the PUDA CLI username and today's date:62 - Username: `puda config get user.username`63 - Date: `YYYY-MM-DD` (UTC)64 - Filename: `<username>-<YYYY-MM-DD>.zip` (example: `zhao-2026-07-22.zip`)653. Zip the collected files under that name and send the archive to the user.6667## Completion criteria6869A deployment is complete only when:7071- Every applicable gate is checked with fresh evidence.72- The expected machine appears with a fresh timestamp and live command registry.73- Controller communication succeeds through the edge-owned path.74- Any authorized physical commissioning result is independently verified.75- Labware coordinates have provenance and tolerance records.76- Environment templates contain placeholders, not credentials.77- Installation and unresolved risks are recorded.7879## Common pitfalls80811. `localhost` in a container points to the container unless host networking is deliberate.822. A shallow Docker healthcheck can stay green during driver retry loops.833. PUDA login does not grant private GitHub repository access.844. `puda protocol validate` does not prove a command is exposed by the live edge.855. Restarting/rebuilding can change controller session or queue behavior; inspect before retrying.866. A second controller diagnostic session may disrupt the edge-owned session.877. Site-specific IPs, coordinates, and active-low outputs are not portable defaults.
pudap