# rail-kubernetes

Wave-1 execution rail for Railiance-managed workloads on Kubernetes.

## Purpose

`rail-kubernetes` is the default base rail for the current Railiance
ecosystem. It owns the generic workload-on-Kubernetes execution contract that
should no longer stay mixed into `railiance-cluster`.

This repo exists to hold:

- the Kubernetes rail declaration
- the generic workload lifecycle contract
- the migration path from the current `railiance-cluster` compatibility surface
- future rail-local tooling and docs for Railiance-managed workloads on Kubernetes

## Boundary

`rail-kubernetes` does not own:

- k3s bootstrap
- cluster-level operator ownership
- cluster backup/restore posture
- workload-specific wrappers that belong in `rapp-*` repos
- substrate inventories that belong in `reef-*` repos

Those concerns stay with `railiance-cluster`, the relevant `rapp-*` repo, or
the relevant `reef-*` repo.

## Current Status

First-wave bootstrap is complete. The repo now owns the generic Kubernetes rail
contract, tooling, and migration-window compatibility handoff from
`railiance-cluster`.

The boundary and source material come from:

- `railiance-master/docs/rail-kubernetes-boundary.md`
- `railiance-cluster/docs/rail-kubernetes-extraction-map.md`
- `railiance-cluster/docs/rail-kubernetes-substrate-profile.md`

## Initial Layout

- `declarations/rail.yaml` — source-controlled rail contract
- `bin/` — thin generic rail lifecycle entrypoints
- `docs/` — wave-1 contract and import plan
- `tools/` — rail-owned helper implementations and scaffolds
- `schemas/` — machine-readable workload contract schema
- `examples/` — canonical example workload declarations for the rail
- `workplans/` — repo-local execution work