truf-server/openspec/changes/improve-worker-operator-cheatsheets/proposal.md

Why

Remote-worker instructions do not provide independently verified copy-paste workflows for Windows, native Linux, and Docker. They also document a nonexistent watch command, require a device token in the install command line, claim a native Linux launcher that is not packaged, and recommend server cap 0 for routine local lifecycle operations.

What Changes

• Add a bounded watch lifecycle command alongside start, stop, attach, and status.
• Allow first-time installation to read the server origin, device token, and parallelism from a small YAML document instead of process arguments.
• Package a native Linux launcher and verify the lifecycle command surface on Windows, native Linux, and Docker.
• Keep the complete operator guide concise while adding separate copy-paste cheatsheets for each supported environment.
• Remove routine cap 0 instructions; local graceful stop drains the selected worker without changing server scheduling for other devices.

Capabilities

New Capabilities

• worker-operator-lifecycle: Cross-platform worker lifecycle commands, private YAML installation input, and verified platform cheatsheets.

Modified Capabilities

Impact

This affects worker_cli.py, worker package launchers, the Linux worker image, CLI/package tests, packaged lifecycle verification, and remote-worker operator documentation. The worker protocol, server API, stored private configuration schema, and assignment capacity model remain unchanged.