docs: add datumctl compute overview

datumctl/compute/building-images.mdx

@@ -0,0 +1,94 @@
+---
+title: "Building images"
+sidebarTitle: "Building images"
+description: "Turn a Dockerfile into an image Datum Compute can run, check it for compatibility, and publish it with datumctl compute build."
+---
+
+`datumctl compute build` packages a Dockerfile and build context into an image, and optionally publishes it. Point it at the same Dockerfile you already use for a normal container — no Compute-specific syntax required.
+
+```bash
+datumctl compute build .
+```
+
+Compute doesn't run that image as a normal container — it boots it as a unikernel, which is what gives Compute VM-level isolation between workloads at container-like density and cold-start speed. `build` packages your Dockerfile into the artifact that runtime boots from, and validates it against unikernel requirements as part of the same step — so a missing shared library or the wrong architecture shows up as a build-time error instead of a workload that never comes up.
+
+<Info>
+  `build` needs a BuildKit backend to run: Docker Desktop or Docker Engine with BuildKit enabled (the default on modern installs), a standalone `buildkitd`, or `BUILDKIT_HOST` pointing at one.
+</Info>
+
+With no `--output`, this is a **local debug build**: it packages the image so you can confirm it builds successfully, without writing or publishing anything. Once you're ready to deploy it, add `--output` or move on to [deploying workloads](/datumctl/compute/deploying-workloads).
+
+## Choosing a Dockerfile
+
+By default, `build` looks for `Dockerfile.datum` in the build context and falls back to `Dockerfile` if that file does not exist — a convenient way to keep a Compute-specific variant alongside your normal one without extra flags. Use `-f` to point at a Dockerfile anywhere else:
+
+```bash
+# Use a Dockerfile in a non-default location
+datumctl compute build -f ./deploy/Dockerfile .
+
+# Pass build-time variables used by ARG instructions
+datumctl compute build --build-arg VERSION=1.2.3 .
+
+# Package a specific stage of a multi-stage Dockerfile (default: the final stage)
+datumctl compute build --target production .
+```
+
+## Writing the output somewhere
+
+`--output` (`-o`) accepts three kinds of destination:
+
+| Destination | Example |
+|-------------|---------|
+| Registry reference | `--output ghcr.io/acme/api:latest` |
+| OCI archive (`.tar`) | `--output ./compute-image.tar` |
+| OCI layout directory | `--output ./compute-image` |
+
+```bash
+# Publish straight to a registry
+datumctl compute build --push --output ghcr.io/acme/api:latest .
+
+# Write a portable OCI archive instead
+datumctl compute build --output ./compute-image.tar .
+```
+
+<Warning>
+  When `--output` is a registry reference, `build` asks for confirmation before pushing. Pass `--push` to skip that prompt — required in CI, where there is no terminal to confirm on.
+</Warning>
+
+## Checking compatibility before you package it
+
+`--analyze` inspects the built entrypoint for the kind of problem that only shows up once Compute's unikernel runtime tries to boot the image — a binary built for the wrong architecture, a startup script whose interpreter is missing, or a shared library the final stage never copied in:
+
+```bash
+datumctl compute build --analyze .
+```
+
+Where a fix is a mechanical Dockerfile edit, the finding shows exactly what to change:
+
+```text
+error[missing-libs]: /app/server requires 1 runtime file that is not present in the image
+   --> Dockerfile:8
+    | Copy the missing shared library into the final stage
+    | - COPY --from=build /app /app
+    | + COPY --from=build /app /app
+    | + COPY --from=build /lib/libc.so.6 /lib/libc.so.6
+```
+
+Reach for `--fix` once you're ready to apply changes like that automatically — it edits the selected Dockerfile in place and rebuilds. `--fix` implies `--analyze`, and only ever applies safe, exact-line edits — it will never restructure your Dockerfile.
+
+```bash
+datumctl compute build --fix .
+```
+
+## Inspecting a published image
+
+`build inspect <image>` is a diagnostic for an image that already exists in a registry — useful when a deployment isn't starting and you want to confirm the image itself is the problem before looking at the workload. It reports the same kind of compatibility findings as `--analyze`, plus the packaged filesystem and startup configuration Compute will boot from. Add `--extended` for additional OCI metadata — the image index, manifest digest, and layer count. Inspection never downloads the packaged filesystem layer itself, so it stays fast even against a large image.
+
+```bash
+datumctl compute build inspect ghcr.io/acme/api:1.4.2
+```
+
+## Next steps
+
+- `datumctl compute build --help` and `datumctl compute build inspect --help` for the full flag reference.
+- [Deploying workloads](/datumctl/compute/deploying-workloads) — take a published image and run it as a workload.

datumctl/compute/deploying-workloads.mdx

@@ -0,0 +1,86 @@
+---
+title: "Deploying workloads"
+sidebarTitle: "Deploying workloads"
+description: "Deploy a container image as a workload with datumctl compute deploy, and check its health with datumctl compute workloads."
+---
+
+`datumctl compute deploy` takes a container image and runs it as a workload across one or more cities. It supports two ways of describing what to deploy — flags, or a manifest file for the declarative form — and both converge on the same underlying workload.
+
+```bash
+datumctl compute deploy api \
+  --image=ghcr.io/acme/api:1.4.2 \
+  --city=DFW,IAD \
+  --min=2 \
+  --port=8080
+```
+
+<Warning>
+  `--image` must point to an image produced by `datumctl compute build`, not a standard OCI image from `docker build` — see [Building images](/datumctl/compute/building-images). Compute boots workloads as unikernels, which requires the packaged filesystem and startup metadata `compute build` adds during packaging.
+</Warning>
+
+If a workload named `api` doesn't exist yet, this creates it with one placement (`default`) spanning both cities, each running at least 2 instances. Run the same command again with a new `--image` and it updates the existing workload instead — `deploy` is create-or-update, the same idempotent shape as `datumctl apply` elsewhere in the CLI.
+
+## Flags at a glance
+
+| Flag | Meaning |
+|------|---------|
+| `--image` | Container image to deploy, required with the flags path. |
+| `--city` | One or more city codes to deploy to, comma-separated (`DFW,IAD`). |
+| `--min` | Minimum instances per city (default `1`). |
+| `--instance-type` | Instance type (default `datumcloud/d1-standard-2`). |
+| `--port` | Port to expose on the workload, optional. |
+| `-y`/`--yes` | Skip the confirmation prompt — needed in scripts and CI. |
+
+<Note>
+  `deploy` needs a network to attach the workload to. If none exists yet in the project, it offers to create a minimal one, with IP addresses assigned automatically, on your behalf — pass `-y` to accept that automatically in a non-interactive run.
+</Note>
+
+## Watching the rollout
+
+`deploy` waits and prints progress as instances come up, the same view `datumctl compute rollout` shows on demand — see [Operations](/datumctl/compute/scaling-and-operations). Ctrl-C detaches from the watch without canceling anything; the rollout keeps going in the background; run `datumctl compute rollout api` any time to reattach.
+
+## Deploying from a manifest
+
+A flag-based deploy writes a `workload.yaml` in the current directory after it succeeds — the same `Workload` resource the flags produced, expressed as YAML. Point `-f` at a manifest to deploy from it instead of flags:
+
+```bash
+datumctl compute deploy -f workload.yaml
+```
+
+This path shows a human-readable diff of what would change before touching anything, then asks for confirmation (skip it with `-y`):
+
+```bash
+datumctl compute deploy -f workload.yaml -y
+```
+
+<Tip>
+  A manifest is the only way to reach configuration the flags don't expose — a second placement, additional ports, or environment variables. Edit the generated `workload.yaml` (or write one from scratch) and apply it with `-f`.
+</Tip>
+
+## Checking workload health
+
+`datumctl compute workloads` lists every workload in the project, with per-city ready counts rolled into a single health summary:
+
+```bash
+# List everything
+datumctl compute workloads
+
+# Only workloads that are degraded right now
+datumctl compute workloads --health=degraded
+
+# Only workloads with a placement in one city
+datumctl compute workloads --city=DFW
+```
+
+Health is one of `available`, `degraded`, `progressing`, or `unknown`. For the full picture on a single workload — its container spec, scale settings, and per-city ready/desired counts together — use `describe`:
+
+```bash
+datumctl compute workloads describe api
+```
+
+## Next steps
+
+- `datumctl compute deploy --help` and `datumctl compute workloads --help` for the full flag reference.
+- [Operations](/datumctl/compute/scaling-and-operations) — restart, watch a rollout, and inspect individual instances.
+- [Destroying workloads](/datumctl/compute/destroying-workloads) — tear a workload down when you're done with it.
+- [Building images](/datumctl/compute/building-images) — build and publish the image you're deploying here.

datumctl/compute/destroying-workloads.mdx

@@ -0,0 +1,31 @@
+---
+title: "Destroying workloads"
+sidebarTitle: "Destroying workloads"
+description: "Delete a workload and every instance it created with datumctl compute destroy."
+---
+
+`datumctl compute destroy` removes a workload and every instance it created, across every city it was placed in:
+
+```bash
+datumctl compute destroy api
+```
+
+Before deleting anything, it prints a summary of what's about to go — the number of placements, the cities involved, and total minimum replicas — then asks for confirmation. Pass `-y`/`--yes` to skip the prompt in scripts and CI:
+
+```bash
+datumctl compute destroy api -y
+```
+
+<Warning>
+  Unlike `datumctl delete` elsewhere in the CLI, `destroy` has no `--dry-run` and there's no `diff` equivalent to preview it. The confirmation prompt is your only checkpoint — read the summary it prints, or check the workload yourself first:
+
+  ```bash
+  datumctl compute workloads describe api
+  ```
+</Warning>
+
+## Next steps
+
+- `datumctl compute destroy --help` for the full flag reference.
+- [Deploying workloads](/datumctl/compute/deploying-workloads) — redeploy the workload later from the same manifest or image.
+- [Operations](/datumctl/compute/scaling-and-operations) — restart or check instances before you decide to remove a workload altogether.

datumctl/compute/overview.mdx

@@ -0,0 +1,143 @@
+---
+title: "Compute"
+sidebarTitle: "Overview"
+description: "Deploy and manage containerized workloads on Datum Cloud with the datumctl compute plugin."
+---
+
+<Note>
+  Compute is coming soon and is not yet generally available.
+</Note>
+
+`datumctl compute` deploys a container image as a **workload** running across one or more Datum Cloud cities, then gives you the day-to-day commands to scale, restart, and tear it down. It is a first-party plugin rather than a built-in command — install it once and its commands behave exactly like the rest of the CLI.
+
+```bash
+datumctl plugin install compute
+datumctl compute --help
+```
+
+<Info>
+  New to plugins? [Using plugins](/datumctl/plugins/using-plugins) covers installation, upgrades, and how a plugin inherits your active context and credentials. Not installed `datumctl` itself yet? Start with the [Quickstart](/datumctl/quickstart).
+</Info>
+
+## Core concepts
+
+A handful of terms recur across every `compute` command:
+
+| Term | Meaning |
+|------|---------|
+| **Workload** | The thing you deploy — a container image plus its runtime configuration (ports, env, instance type) and one or more placements. |
+| **Placement** | A named group of cities and a scale policy (minimum replica count) within a workload. `deploy` from flags creates a single placement named `default`. |
+| **City** | A short code identifying a Datum Cloud location a workload can run in, for example `DFW` or `IAD`. |
+| **Instance** | One running copy of a workload's container in one city. A placement with `--min=2` across two cities produces four instances. |
+
+`compute` is project-scoped: every command reads `--project` (or your active context's project, injected automatically — see [Contexts & scoping](/datumctl/contexts-and-scoping)). There is no organization-level view and no `--namespace` flag; all compute resources live in the project's `default` namespace.
+
+## Requesting access
+
+Compute is a gated service. The first time you run a command that needs it, `datumctl` checks whether your project is entitled to use Compute:
+
+<CardGroup cols={2}>
+  <Card title="Not requested" icon="circle-question">
+    No request has been made yet. On an interactive terminal, the gate offers to submit one for you.
+  </Card>
+  <Card title="Pending approval" icon="hourglass-half">
+    A request is awaiting a manual decision by the service provider. Latency is unbounded.
+  </Card>
+  <Card title="Active" icon="circle-check">
+    The project is entitled — every `compute` command runs normally.
+  </Card>
+  <Card title="Denied / Revoked" icon="circle-xmark">
+    The provider rejected the request (or later revoked it). Recovery is submitting a new request.
+  </Card>
+</CardGroup>
+
+### The automatic gate
+
+Run any gated command — `deploy`, `workloads`, `instances`, and so on — without access, and on a TTY `datumctl` prompts you inline:
+
+```bash
+datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --city=DFW --min=1
+```
+
+`datumctl` checks if Compute is enabled for the project, and — if not — asks whether to request access; on confirmation, it submits the request and waits briefly to see whether the platform approves it immediately or the request needs manual review.
+
+Decline, and nothing is submitted — run `datumctl compute access request` yourself whenever you're ready. In a non-interactive shell (CI, a script, or a piped command), the gate never prompts; it fails immediately and tells you which command to run.
+
+### Checking and requesting access explicitly
+
+Use `datumctl compute access` to check the current state directly, and `access request` for more control over submitting one than the automatic prompt gives you:
+
+```bash
+# Show the current access state
+datumctl compute access
+
+# Submit a request with a justification, useful for the provider's review
+datumctl compute access request --message="Onboarding the api service"
+
+# Submit and block until the platform's first decision (or --timeout elapses)
+datumctl compute access request --wait
+
+# A denied or revoked request is terminal — --renew deletes it and submits fresh
+datumctl compute access request --renew
+```
+
+`datumctl compute access` prints the state, the platform's explanation, and — when there's a next step — the exact command to run:
+
+```text
+Service:  Compute (compute.datumapis.com)
+Project:  acme-prod
+Status:   Not requested
+          This service is not enabled for this project.
+
+Request access with: datumctl compute access request
+```
+
+Add `-o json` or `-o yaml` to script against the state instead of parsing prose.
+
+## Checking quota
+
+Once active, `datumctl compute quota` shows how much of your project's compute allotment is used:
+
+```bash
+datumctl compute quota
+```
+
+```text
+Quota for project acme-prod
+
+RESOURCE    UNIT        LIMIT   USED   AVAILABLE   USAGE
+Workloads   workloads   10      3      7           [######--------------]  30%
+Instances   instances   50      12     38           [#####---------------]  24%
+vCPUs       vCPUs       32      8      24           [#####---------------]  25%
+Memory      MiB         65536   16384  49152        [#####---------------]  25%
+```
+
+Pass `--constrained` to show only the resource types that are currently at their limit — the fastest way to check whether a stalled rollout is a quota problem:
+
+```bash
+datumctl compute quota --constrained
+```
+
+## Find your way around
+
+<CardGroup cols={2}>
+  <Card title="Building images" icon="cube" href="/datumctl/compute/building-images">
+    Turn a Dockerfile into an image Compute can run, and check compatibility before you deploy.
+  </Card>
+  <Card title="Deploying workloads" icon="rocket" href="/datumctl/compute/deploying-workloads">
+    Deploy a workload from flags or a manifest, and read back its health across cities.
+  </Card>
+  <Card title="Operations" icon="gauge" href="/datumctl/compute/scaling-and-operations">
+    Roll restarts, watch a rollout, and debug individual instances.
+  </Card>
+  <Card title="Destroying workloads" icon="trash" href="/datumctl/compute/destroying-workloads">
+    Tear down a workload and every instance it created.
+  </Card>
+</CardGroup>
+
+## Related
+
+- `datumctl compute --help` and `datumctl compute <command> --help` for the full flag reference.
+- [Using plugins](/datumctl/plugins/using-plugins) — how the `compute` plugin is installed, upgraded, and trusted.
+- [Contexts & scoping](/datumctl/contexts-and-scoping) — how the project a `compute` command runs against is resolved.
+- [Output formats & scripting](/datumctl/output-and-scripting) — `-o json`/`-o yaml` patterns that apply across `compute` subcommands.