Public dry run dryrun-a43e907efd9d

Source commit: a43e907efd9d1561c23fe73499478e881f868355

Public tree identity: sha256:453dea30195485dd8939f575a69b39f4bb7acd84c4df23f8aa29b55d044f2673

docs/getting-started.md

@@ -0,0 +1,110 @@
+# 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 create a project
+
+~~~bash
+clusterflux login --browser
+clusterflux auth status
+clusterflux project init   --new-project my-project   --name "My Project"   --yes
+clusterflux project select my-project
+~~~
+
+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.
+
+## 3. Enroll and start a node
+
+Create a short-lived grant:
+
+~~~bash
+clusterflux node enroll --project-id my-project --json
+~~~
+
+Generate a node key pair using your normal secret-management tooling. Exchange
+the grant once:
+
+~~~bash
+clusterflux node attach   --project-id my-project   --node workstation   --enrollment-grant "$ENROLLMENT_GRANT"   --public-key "$NODE_PUBLIC_KEY"   --json
+~~~
+
+Start the worker from the project directory with its private key supplied
+through protected environment or credential storage:
+
+~~~bash
+CLUSTERFLUX_NODE_PRIVATE_KEY="$NODE_PRIVATE_KEY" clusterflux-node   --coordinator https://clusterflux.michelpaulissen.com   --tenant "$TENANT"   --project-id my-project   --node workstation   --public-key "$NODE_PUBLIC_KEY"   --project-root "$PWD"   --worker   --emit-ready
+~~~
+
+The enrollment grant is not needed again. Stop and restart the worker with the
+same key identity. 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/".
+
+~~~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 the normal Threads,
+Stack, Variables, Continue, Pause, and Restart controls.
+
+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.
+
+## 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.