Bootstrap the first rail-kubernetes repo

SCOPE.md

@@ -0,0 +1,118 @@
+# 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.