Public release release-b8454b34d38c

Source commit: b8454b34d38cc2ba0bd278e842060db45d091e1c

Public tree identity: sha256:69d6c8143bf6227e1bb07852aa94e8af9c26793eca252bb46788894f728cb6d2

docs/nodes.md

@@ -0,0 +1,66 @@
+# 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"
+~~~
+
+Treat the enrollment grant as a short-lived secret. It is exchanged once and is
+not a worker credential. By default, `clusterflux node attach` creates and stores
+a local node key with restricted permissions. Use an explicit `--public-key`
+with `CLUSTERFLUX_NODE_PRIVATE_KEY` only when external secret management owns the
+key pair.
+
+## Run the worker
+
+~~~bash
+clusterflux-node \
+  --coordinator https://clusterflux.michelpaulissen.com \
+  --tenant "$TENANT" \
+  --project-id <project-id> \
+  --node workstation \
+  --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.