# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Default Railiance execution rail for generic workload-on-Kubernetes semantics.

---

## Core Idea

`rail-kubernetes` is the first concrete `rail-*` repo in Railiance.
It exists to hold the generic execution contract for Railiance-managed
workloads that run on Kubernetes, without keeping those semantics mixed into
the S2 ownership repo.

---

## In Scope

- Kubernetes rail declaration and compatibility notes
- Generic workload lifecycle semantics for Kubernetes-managed workloads
- Generic workload contract surface such as `railiance/app.toml`
- Generic rollout, observe, promote, and rollback semantics for the rail
- Migration compatibility guidance while the extraction from `railiance-cluster`
  is still in progress

---

## Out of Scope

- k3s bootstrap and cluster installation
- cluster-level ingress, operator, and certificate ownership
- cluster backup, restore, and preflight safety rails
- workload-specific wrappers and app packaging
- substrate inventories and machine grouping

---

## Relevant When

- Defining how a workload targets the default Kubernetes rail
- Moving generic workload lifecycle material out of `railiance-cluster`
- Attaching a `rapp-*` package to its Kubernetes execution contract
- Clarifying which S2 substrate facts the rail may depend on

---

## Not Relevant When

- The work is purely cluster substrate ownership
- The work is workload-specific packaging
- The work is substrate inventory or server grouping

---

## Current State

- Status: active bootstrap
- Implementation: baseline repo, declaration, and first repo-local workplan are present
- Stability: evolving
- Usage: wave-1 home for the default Kubernetes rail

---

## How It Fits

- Upstream dependencies: `railiance-cluster`, `railiance-master`
- Downstream consumers: future `rapp-*` repos and reefs that host the Kubernetes rail
- Often used with: `railiance-fabric`, `railiance-platform`, `railiance-infra`

---

## Terminology

- Preferred terms: rail, execution contract, workload lifecycle, substrate profile
- Also known as: default base rail
- Potentially confusing terms: this repo defines rail semantics; it does not own the Kubernetes substrate itself

---

## Related / Overlapping Repositories

- `railiance-cluster` — owns the Kubernetes substrate; `rail-kubernetes` owns the generic workload-on-Kubernetes contract
- `railiance-master` — defines the framework architecture and boundary
- future `rapp-*` repos — own workload packaging and scaffolding on top of this rail
- future `reef-*` repos — own the substrate boundaries that host this rail

---

## Getting Oriented

- Start with: `README.md`, `INTENT.md`
- Key files / directories: `declarations/`, `docs/`, `workplans/`
- Entry points: `declarations/rail.yaml`, `docs/wave-1-contract.md`

---

## Provided Capabilities

```capability
type: governance
title: Kubernetes execution rail contract
description: Defines the generic execution contract for Railiance-managed workloads that run on Kubernetes.
keywords: [railiance, rail, kubernetes, workload, execution]
```

---

## Notes

Keep this repo generic. If a behavior is specific to one workload or one
substrate, it belongs somewhere else.