Public dry run release-5ee549dd5fdd

Source commit: 5ee549dd5fddc98e4ee5054679bb0ac405c82529

Public tree identity: sha256:61b170dbdd26d350b8aff072e1792d38afd76bac7881bd42f271864d9662a6d4

docs/nodes.md

@@ -0,0 +1,53 @@
+# Nodes
+
+Your node runs real commands and retains real output bytes. Enroll it once, then
+restart it with the same public-key identity.
+
+## Enroll
+
+~~~bash
+clusterflux node enroll --project-id <project-id> --json
+clusterflux node attach   --project-id <project-id>   --node workstation   --enrollment-grant "$ENROLLMENT_GRANT"   --public-key "$NODE_PUBLIC_KEY"
+~~~
+
+Treat the enrollment grant as a short-lived secret. It is exchanged once and is
+not a worker credential.
+
+## Run the worker
+
+~~~bash
+CLUSTERFLUX_NODE_PRIVATE_KEY="$NODE_PRIVATE_KEY" clusterflux-node   --coordinator https://clusterflux.michelpaulissen.com   --tenant "$TENANT"   --project-id <project-id>   --node workstation   --public-key "$NODE_PUBLIC_KEY"   --project-root "$PWD"   --worker   --emit-ready
+~~~
+
+Start the worker from the project directory when tasks need a local checkout.
+The worker reports detected command, container, source, VFS, environment, OS,
+and architecture capabilities. Use "clusterflux node attach --cap <capability>"
+only when detection needs an explicit override.
+
+## Liveness
+
+~~~bash
+clusterflux node list
+clusterflux node status workstation
+~~~
+
+The coordinator marks a node stale after its accepted heartbeat age exceeds the
+configured threshold. Stale nodes are excluded before placement and before a
+retained-node download link is created.
+
+## Local source
+
+A bind-mounted local checkout is fast and avoids transferring the repository,
+but it is non-hermetic: uncommitted changes, ignored files, and concurrent
+editor writes can affect the command. Use a content-addressed source snapshot
+when reproducibility matters.
+
+## Revoke
+
+~~~bash
+clusterflux node revoke workstation
+~~~
+
+Revocation removes the node identity and its live descriptor. Subsequent signed
+requests fail. Artifacts retained only by that node become unavailable unless
+you explicitly synchronized them elsewhere.