Public release release-b8454b34d38c

Source commit: b8454b34d38cc2ba0bd278e842060db45d091e1c

Public tree identity: sha256:69d6c8143bf6227e1bb07852aa94e8af9c26793eca252bb46788894f728cb6d2

docs/getting-started.md

@@ -0,0 +1,151 @@
+# Getting started
+
+This guide uses the hosted coordinator. For your own coordinator, complete
+[Self-hosting](self-hosting.md) first and then return to the node and run steps.
+
+## 1. Install the commands
+
+~~~bash
+cargo install --path crates/clusterflux-cli --bin clusterflux
+cargo install --path crates/clusterflux-node --bin clusterflux-node
+cargo install --path crates/clusterflux-dap --bin clusterflux-debug-dap
+~~~
+
+Install rootless Podman on each Linux node that will execute container-backed
+environments.
+
+## 2. Sign in and select your hosted project
+
+~~~bash
+clusterflux login --browser
+clusterflux auth status
+clusterflux project list
+clusterflux project select <hosted-project-id>
+~~~
+
+The browser flow is owned by the configured Authentik identity provider. The CLI
+stores an opaque Clusterflux session, not provider authorization codes or
+provider tokens. Hosted login creates or links your single project; hosted
+admission rejects additional project creation.
+
+## 3. Enroll and start a node
+
+Create a short-lived grant:
+
+~~~bash
+clusterflux node enroll --project-id <hosted-project-id> --json
+~~~
+
+Create the local node identity and exchange the grant once:
+
+~~~bash
+clusterflux node attach \
+  --project-id <hosted-project-id> \
+  --node workstation \
+  --enrollment-grant "$ENROLLMENT_GRANT" \
+  --json
+~~~
+
+Clusterflux creates and stores the node key locally with restricted permissions.
+The enrollment grant is not needed again. Stop and restart the worker with the
+same stored identity:
+
+~~~bash
+clusterflux-node \
+  --coordinator https://clusterflux.michelpaulissen.com \
+  --tenant "$TENANT" \
+  --project-id <hosted-project-id> \
+  --node workstation \
+  --project-root "$PWD" \
+  --worker \
+  --emit-ready
+~~~
+
+Supplying `--public-key` and `CLUSTERFLUX_NODE_PRIVATE_KEY` is an advanced option
+for nodes whose key material is managed externally. Check server-derived
+liveness with:
+
+~~~bash
+clusterflux node list
+clusterflux node status workstation
+~~~
+
+## 4. Inspect and run a bundle
+
+A project contains `clusterflux.toml`, Rust workflow source, and any declared
+environments under `envs/`. Task arguments and handles use portable canonical
+representations; they are not host pointers or shared process memory.
+
+~~~bash
+clusterflux bundle inspect --project .
+clusterflux run --project . build
+~~~
+
+From this checkout, the complete source-to-task-to-artifact path is:
+
+~~~bash
+clusterflux bundle inspect --project examples/hello-build
+clusterflux run --project examples/hello-build build
+clusterflux artifact list --process <process-id>
+clusterflux artifact download <artifact-id> --to ./hello-clusterflux
+chmod +x ./hello-clusterflux
+./hello-clusterflux
+~~~
+
+The workflow snapshots `examples/hello-build`, starts its `compile` task in the
+offline Linux environment, and retains the real static executable returned by
+that task.
+
+Choose another entrypoint by replacing `build`. Clusterflux rejects an oversized
+or invalid bundle before it creates the virtual process.
+
+## 5. Inspect tasks and output
+
+~~~bash
+clusterflux process list
+clusterflux process status
+clusterflux task list
+clusterflux logs
+clusterflux artifact list
+~~~
+
+A failed task configured with `AwaitOperator` remains visible as awaiting action.
+Restart it as a new attempt under the same logical task identity:
+
+~~~bash
+clusterflux task restart <task-id> --process <process-id> --yes
+~~~
+
+`examples/recovery-build` demonstrates this without a synthetic trap. It starts
+two instances of `build_lane`; one completes while the other runs a command that
+exits with status 23. Edit that command to produce the recovering output, then
+restart the failed task. Its original join resolves from the replacement
+attempt.
+
+## 6. Debug in VS Code
+
+Open the project in VS Code and start `Clusterflux: Launch Virtual Process`.
+Set a breakpoint on a generated probe location and use Threads, Stack,
+Variables, Continue, Pause, and Restart.
+
+Breakpoints remain unverified until the coordinator installs them. Thread IDs
+are stable for an exact logical task instance across snapshot updates and retry
+attempts. Observer reconnect diagnostics do not manufacture stopped events, and
+Continue succeeds only after the coordinator acknowledges resume.
+
+A fully frozen Debug Epoch gives a consistent all-participant view. If a
+participant cannot freeze within five seconds, the adapter reports a partial
+epoch. You may inspect frozen participants, but values across running and frozen
+tasks are not a consistent global snapshot. Continue resumes only participants
+that acknowledged the freeze.
+
+## 7. Download an artifact
+
+~~~bash
+clusterflux artifact list --process <process-id>
+clusterflux artifact download <artifact-id> --to ./output.bin --max-bytes 67108864
+~~~
+
+The command opens a scoped, expiring download and verifies the artifact digest.
+It fails if the retaining node is stale, the bytes were garbage collected, the
+digest or size changed, or policy cannot reserve the transfer.