# Docs

This directory is the public documentation entrypoint for UltraCloud.

## Read First

- [../README.md](../README.md)
- [testing.md](testing.md)
- [component-matrix.md](component-matrix.md)
- [rollout-bundle.md](rollout-bundle.md)
- [control-plane-ops.md](control-plane-ops.md)
- [edge-trial-surface.md](edge-trial-surface.md)
- [provider-vm-reality.md](provider-vm-reality.md)
- [hardware-bringup.md](hardware-bringup.md)
- [storage-benchmarks.md](storage-benchmarks.md)

## Canonical Profiles

- `single-node dev`: `nix run .#single-node-quickstart`, `nix run .#single-node-trial`, `nix build .#single-node-trial-vm`, `nixosConfigurations.single-node-quickstart`, companion image `nixosConfigurations.netboot-all-in-one`
- `3-node HA control plane`: `nixosConfigurations.node01`, `nixosConfigurations.node02`, `nixosConfigurations.node03`, companion image `nixosConfigurations.netboot-control-plane`
- `bare-metal bootstrap`: `nix run ./nix/test-cluster#cluster -- baremetal-iso`, `nixosConfigurations.ultracloud-iso`, `nixosConfigurations.baremetal-qemu-control-plane`, `nixosConfigurations.baremetal-qemu-worker`, `checks.x86_64-linux.baremetal-iso-e2e` followed by `./result/bin/baremetal-iso-e2e` for the exact host-KVM proof

`nixosConfigurations.netboot-worker` is an archived helper outside the canonical profiles and their guard set. `baremetal/vm-cluster`, `k8shost-cni`, `k8shost-controllers`, `lightningstor-csi`, Firecracker, and mvisor remain in-tree only as non-product scaffolds or `legacy/manual` debugging paths.

`single-node-trial-vm` is the low-friction trial artifact for local use. OCI/Docker artifact is intentionally not the public trial surface because a privileged container would not exercise the same KVM, `/dev/net/tun`, and guest-kernel contract.

`ultracloud.cluster` backed by `nix/lib/cluster-schema.nix` is the only supported cluster authoring source.
`nix-nos` is limited to legacy compatibility and low-level network primitives.
`single-node-trial-vm` and `single-node-quickstart` are the standalone VM-platform story.

## Key References

- VM validation harness: [../nix/test-cluster/README.md](../nix/test-cluster/README.md)
- Hardware bring-up bridge: [hardware-bringup.md](hardware-bringup.md)
- Provider and VM-hosting reality proof: [provider-vm-reality.md](provider-vm-reality.md)
- Rollout bundle operator contract: [rollout-bundle.md](rollout-bundle.md)
- Core control-plane operator contract: [control-plane-ops.md](control-plane-ops.md)
- Edge and trial-surface contract: [edge-trial-surface.md](edge-trial-surface.md)
- APIGateway supported scope: [../apigateway/README.md](../apigateway/README.md)
- NightLight supported scope: [../nightlight/README.md](../nightlight/README.md)
- CoronaFS storage role: [../coronafs/README.md](../coronafs/README.md)
- CreditService supported scope: [../creditservice/README.md](../creditservice/README.md)
- K8sHost supported scope: [../k8shost/README.md](../k8shost/README.md)

## Core API Notes

- `chainfire` supports fixed-membership cluster introspection on the public surface: `MemberList`, `Status`, and the internal `Vote` plus `AppendEntries` Raft transport. `chainfire-core` remains a workspace-internal compatibility crate rather than a supported embeddable API.
- `flaredb` supports SQL over both gRPC and REST. The public REST endpoints are `POST /api/v1/sql` and `GET /api/v1/tables`.
- `lightningstor` keeps bucket versioning, bucket policy, bucket tagging, and explicit object version listing on the supported optional surface.
- `k8shost` keeps `WatchPods` on the supported surface as a bounded snapshot stream of the current matching pods.

## Design Notes

Longer-running redesign and investigation documents remain in `plans/`. Those documents are useful context, but they are not the primary onboarding path for contributors.