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

Context

The packaged CLI persists a private JSON configuration after install, but first installation accepts credentials only through --token. Windows has a root launcher, the Linux image relies on its entrypoint, and assembled Linux packages have no root launcher. attach already provides live coherent status, but operators reasonably look for a watch command. Active documentation mixes platform-specific syntax and server-capacity administration with local lifecycle commands.

Goals / Non-Goals

Goals:

• Make the same lifecycle vocabulary available from the package root on Windows and native Linux and through a short Docker helper.
• Keep the device token out of command arguments and shell history during installation.
• Verify start, clean stop, attach, status, and watch behavior before publishing copy-paste cheatsheets.
• Remove server cap 0 from routine worker maintenance instructions.

Non-Goals:

• Change the worker protocol, server API, assignment cancellation, or capacity semantics.
• Replace the installed private JSON configuration or expose its token.
• Add an updater, public artifact registry, or service-manager integration for native Linux.

Decisions

Treat watch as the live human status alias

watch uses the same authenticated local control stream and coherent status refresh as attach. It accepts the same optional bounded --follow-seconds argument and detaches without stopping the worker. Reusing the control path avoids a second polling implementation and behaves consistently where an OS watch utility is absent.

Accept a strict YAML installation document

install --config PATH reads an exact YAML mapping containing server, token, and parallelism. PATH=- reads a bounded document from standard input for Docker. A path must be a private regular file; YAML uses safe_load, rejects aliases/extra fields through exact shape validation, and never changes the durable installed JSON schema. Direct --server and --token remain supported for compatibility but cannot be combined with --config.

Add only a Linux package-root launcher

Assembled non-Windows packages receive executable truf-worker and run-worker shell launchers equivalent to the Windows command files. Docker keeps its existing entrypoint; the launcher also enables release tooling to export the assembled package for native Linux without inventing another client implementation.

Separate active instructions from evidence reports

The general quickstart links concise Windows, Linux, and Docker cheatsheets and retains conceptual guidance. Each platform sheet starts from its artifact or Compose root and contains installation plus start, stop, attach, status, and watch commands. Historical validation reports remain unchanged even where they record earlier cap-zero experiments.

Risks / Trade-offs

• [A YAML file leaves a plaintext token on disk] -> Require private permissions, label it one-time installation input, and instruct deletion after successful install; the durable token remains in the existing private state.
• [Standard input cannot prove source-file permissions] -> Bound and validate its content and document chmod 600 on the redirected host file.
• [Watch and attach appear redundant] -> Document watch as a discoverable alias rather than maintaining distinct semantics.
• [Native Linux lacks automatic daemon startup] -> Keep start/stop in the portable CLI and explicitly leave systemd installation out of scope.

Migration Plan

1. Add parser, YAML input, launcher, and tests without changing existing command forms.
2. Build fresh Windows and Linux/Docker artifacts and run isolated lifecycle checks.
3. Publish the updated general guide and platform sheets only after those checks pass.
4. Roll back by restoring the previous artifact; installed schema-2 JSON remains compatible.

Open Questions

None.