Public release release-98d969b26488

Source commit: 98d969b26488b4cda8b2381fa870276a00ca98ea

Public tree identity: sha256:d02dd1e8d3547a489bb300741bed544bdc60bb8fe0bd541fd43ce9bfa7129a3e

docs/getting-started.md

@@ -0,0 +1,125 @@
+# 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
+~~~
+
+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
+~~~
+
+## 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.
+
+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.