Bootstrap the first rail-kubernetes repo

.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+Thumbs.db
+__pycache__/
+*.pyc
+.venv/
+venv/
+env/

.repo-classification.yaml

@@ -0,0 +1,18 @@
+repo_classification:
+  standard: Repo Classification Standard
+  version: "1.0"
+  classified_at: "2026-07-25"
+  classified_by: agent
+  category: project
+  domain: financials
+  secondary_domains:
+    - infotech
+  capability_tags:
+    - platform
+    - operations
+  business_stake:
+    - technology
+    - operations
+  business_mechanics:
+    - coordination
+    - operation

AGENTS.md

@@ -0,0 +1,41 @@
+# rail-kubernetes — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** Default Railiance execution rail for generic
+workload-on-Kubernetes semantics.
+
+**Domain:** financials
+**Repo slug:** rail-kubernetes
+**Topic slug:** railiance
+**Workplan prefix:** `RAIL-K8S-WP-`
+
+---
+
+## Session Protocol
+
+**Start:**
+1. Read `README.md`, `INTENT.md`, and `SCOPE.md`
+2. Review active work in `workplans/`
+3. Re-read the current rail declaration in `declarations/rail.yaml`
+
+**During work:**
+- Keep the boundary with `railiance-cluster` explicit
+- Keep workload packaging concerns out of this repo
+- Prefer source-controlled declarations over implicit conventions
+
+**Close:**
+1. Update workplan files to reflect progress
+2. Register or refresh the repo from `.repo-classification.yaml` when needed
+3. Run `statehub fix-consistency`
+
+---
+
+## Boundary Reminders
+
+- Do not move substrate bootstrap into this repo
+- Do not normalize workload-specific helper commands here
+- Do not let `rapp-*` packaging or `reef-*` substrate inventory drift into this repo
+
+The canonical framework boundary lives in
+`railiance-master/docs/rail-kubernetes-boundary.md`.

CLAUDE.md

@@ -0,0 +1,4 @@
+# rail-kubernetes — Claude Code Instructions
+
+@SCOPE.md
+@AGENTS.md

INTENT.md

@@ -0,0 +1,55 @@
+# INTENT
+
+## Why This Repo Exists
+
+`rail-kubernetes` exists so Railiance has a first-class home for the default
+execution rail used by platform services and managed workloads.
+
+Before this repo, generic workload lifecycle semantics, workload declarations,
+and Kubernetes rollout helpers were mixed into `railiance-cluster`. That was
+pragmatic while Railiance had only one runtime path, but it is the wrong steady
+state once Railiance starts introducing multiple rails.
+
+This repo establishes the durable answer to:
+
+- how a Railiance-managed workload targets Kubernetes as a rail
+- which workload lifecycle semantics are generic to Kubernetes-managed
+  workloads
+- which substrate guarantees the rail expects from S2
+- where future packages such as `rapp-openbao` attach when they run on the
+  default rail
+
+## What This Repo Must Protect
+
+This repo must keep the wave-1 Kubernetes rail narrow and reusable.
+
+That means:
+
+- protect the distinction between rail semantics and cluster ownership
+- protect the distinction between rail semantics and workload packaging
+- keep the compatibility path from `railiance-cluster` explicit while the
+  extraction is incomplete
+- avoid encoding assumptions that only work for one workload or one substrate
+
+## What This Repo Is Not
+
+This repo is not:
+
+- the ownership home for the Kubernetes substrate
+- the ownership home for OpenBao, Forgejo, or any other single workload
+- the ownership home for one specific server or cluster substrate
+- the place to normalize workload-specific operator commands
+
+## Initial Operating Context
+
+Wave 1 is intentionally centered on Kubernetes.
+
+Railiance should treat this repo as the default rail path until a later
+workload presents a strong enough reason to justify a different rail such as
+`rail-knative`.
+
+The first version of this repo therefore prioritizes:
+
+- a clean boundary with `railiance-cluster`
+- a stable attachment point for future `rapp-*` repos
+- compatibility with the currently published S2 substrate profile

README.md

@@ -0,0 +1,45 @@
+# 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
+
+This repo is in first-wave bootstrap.
+
+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
+- `docs/` — wave-1 contract and import plan
+- `workplans/` — repo-local execution work

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.

WORK-RECORDS.md

@@ -0,0 +1,15 @@
+# Work Records — rail-kubernetes
+
+> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
+> stage 3). Do not edit by hand — edit the source file/block listed for
+> each record and re-run fix-consistency to refresh this index. Archived
+> workplans are omitted; closed decisions/intakes/engagements stay listed
+> so recently-resolved work is still visible. [auto]
+
+| Kind | ID | Status | Lane | Source |
+| --- | --- | --- | --- | --- |
+| workplan | RAIL-K8S-WP-0001 | active | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md |
+| task | RAIL-K8S-WP-0001-T01 | done | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md |
+| task | RAIL-K8S-WP-0001-T02 | progress | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md |
+| task | RAIL-K8S-WP-0001-T03 | wait | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md |
+| task | RAIL-K8S-WP-0001-T04 | wait | — | workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md |

declarations/rail.yaml

@@ -0,0 +1,26 @@
+kind: execution-rail
+rail_id: rail-kubernetes
+repo: rail-kubernetes
+ownership_repo: railiance-cluster
+execution_architecture: kubernetes
+status: wave-1-bootstrap
+supported_rollout_modes:
+  - stage1-run
+  - stage2-isolated-canary
+  - stage3-promote-rollback
+substrate_prerequisites:
+  - kubernetes-api
+  - helm-apply-path
+  - operator-driven-kubeconfig-access
+  - namespace-creation-supported
+compatibility_notes:
+  - Weighted routing is optional and must not be assumed in wave 1.
+  - Metrics availability is opportunistic and not a rollout success criterion.
+  - Storage guarantees remain explicit-review territory until S2 publishes them.
+source_documents:
+  - repo: railiance-master
+    path: docs/rail-kubernetes-boundary.md
+  - repo: railiance-cluster
+    path: docs/rail-kubernetes-extraction-map.md
+  - repo: railiance-cluster
+    path: docs/rail-kubernetes-substrate-profile.md

docs/README.md

@@ -0,0 +1,4 @@
+# rail-kubernetes Docs
+
+- `wave-1-contract.md` — current rail contract and boundary summary
+- `source-import-plan.md` — source material and migration direction from existing repos

docs/source-import-plan.md

@@ -0,0 +1,40 @@
+# Source Import Plan
+
+## Purpose
+
+Record which reviewed source materials are expected to seed this repo.
+
+## First-Wave Imports
+
+Expected source documents from `railiance-cluster`:
+
+- `docs/deployment-lifecycle.md`
+- `docs/app-toml-contract.md`
+- `docs/overlay-repo-pattern.md`
+- `docs/canary-helm-template.md`
+- `docs/stage2-deploy-observe.md`
+- `docs/promote-rollback-onboarding.md`
+- `docs/railiance-run-command.md`
+
+Expected source assets from `railiance-cluster`:
+
+- `schemas/railiance-app.schema.json`
+- `examples/railiance/app.toml`
+- `tools/create_railiance_overlay_repo.sh`
+- `tools/cmd/railiance-run`
+- `tools/cmd/railiance-stage2`
+- `tools/cmd/railiance-stage3`
+
+## Deferred Migration Debt
+
+Do not import these into `rail-kubernetes` as part of wave 1:
+
+- workload-specific activity-core helper commands
+- workload-specific smoke or reconciliation helpers
+- cluster substrate operations
+- shared bootstrap helpers that still need a separate placement review
+
+## Rule
+
+Imports into this repo should preserve the boundary already reviewed in
+`railiance-master` and `railiance-cluster`.

docs/wave-1-contract.md

@@ -0,0 +1,59 @@
+# Wave-1 Kubernetes Rail Contract
+
+## Purpose
+
+Summarize the initial contract `rail-kubernetes` owns in wave 1.
+
+This repo starts from already-reviewed source documents rather than inventing a
+new runtime model:
+
+- `railiance-master/docs/rail-kubernetes-boundary.md`
+- `railiance-cluster/docs/rail-kubernetes-extraction-map.md`
+- `railiance-cluster/docs/rail-kubernetes-substrate-profile.md`
+
+## What `rail-kubernetes` Owns
+
+Wave 1 assigns these concerns to the rail:
+
+- the generic workload-on-Kubernetes execution contract
+- the generic `railiance/app.toml` workload declaration surface
+- generic stage 1 / stage 2 / stage 3 lifecycle semantics
+- generic canary, observe, promote, and rollback behavior
+- generic wrapper and overlay guidance for workloads that still use the current
+  overlay pattern during migration
+
+## What Stays In `railiance-cluster`
+
+Wave 1 keeps these concerns in the S2 ownership repo:
+
+- k3s bootstrap and host-to-cluster installation
+- cluster backup, restore, smoke, and preflight operations
+- operator ownership for ingress, TLS, and other cluster-level components
+- cluster access delivery and kubeconfig handling
+- substrate-level safety rails
+
+## Published Substrate Assumptions
+
+Wave 1 `rail-kubernetes` may assume:
+
+- a Kubernetes API backed by k3s
+- Helm-based apply paths
+- operator-driven kubeconfig access
+- isolated canary exposure as the safe default
+- namespace creation during workload rollout
+
+Wave 1 `rail-kubernetes` must not assume:
+
+- guaranteed weighted routing
+- a generic workload RBAC model
+- a generic persistent-storage contract
+- a secret-delivery contract at the S2 layer
+
+## Migration Constraint
+
+Until the extraction is complete, `railiance-cluster` remains the compatibility
+surface for current operators.
+
+`rail-kubernetes` should become the durable home of the contract first. Only
+then should commands, docs, schemas, and helpers move here in a migration-safe
+sequence.

workplans/archived/.gitkeep

@@ -0,0 +1 @@
+