railiance-cluster/docs/rail-kubernetes-extraction-map.md

rail-kubernetes Extraction Map

This document records the reviewed wave-1 extraction map from railiance-cluster to a future rail-kubernetes repo.

The goal is to separate:

• S2 Kubernetes substrate ownership that stays in railiance-cluster
• generic workload-on-Kubernetes contract material that moves to rail-kubernetes
• unrelated or workload-specific helpers that must be rehomed elsewhere instead of being normalized into either repo

Move To Future rail-kubernetes

Path	Why it moves
docs/deployment-lifecycle.md	Generic Stage 1/2/3 workload lifecycle semantics, not S2 substrate ownership
docs/app-toml-contract.md	Generic workload declaration contract
docs/overlay-repo-pattern.md	Generic wrapper/overlay packaging pattern
docs/canary-helm-template.md	Generic canary chart pattern for workloads
docs/stage2-deploy-observe.md	Generic Stage 2 command behavior
docs/promote-rollback-onboarding.md	Generic workload onboarding to the lifecycle
docs/railiance-run-command.md	Generic Stage 1 command contract
schemas/railiance-app.schema.json	Schema for the generic workload contract
examples/railiance/app.toml	Example for the generic workload contract
tools/create_railiance_overlay_repo.sh	Generic wrapper/overlay scaffolding
tools/cmd/railiance-run	Generic Stage 1 executor
tools/cmd/railiance-stage2	Generic Stage 2 canary deploy/observe executor
tools/cmd/railiance-stage3	Generic Stage 3 promote/rollback executor
bin/railiance subcommands create-overlay, run, deploy, observe, promote, rollback	Dispatcher surface for the generic workload rail
tools/README_tools.md sections for railiance-run, railiance-stage2, railiance-stage3, and create_railiance_overlay_repo.sh	Tool documentation should move with the tools it describes

Retain In railiance-cluster

Path	Why it stays
ansible/bootstrap.yml	k3s and Helm bootstrap are core S2 substrate ownership
docs/backup-restore.md	Cluster-state backup and restore posture
docs/kubeconfig.md	Cluster access delivery and handling
docs/operator-runbook.md	Operator-facing cluster-touching commands, though some rows need separate cleanup
docs/first_host.md	Host-to-cluster bootstrap guidance tied to S2 setup
tools/cmd/railiance-backup-s2	S2 cluster-state backup helper
tools/cmd/railiance-restore-s2	S2 restore guidance helper
tools/cmd/railiance-preflight	Cluster safety gate before invasive work
tests/smoke_kube.sh	Cluster health smoke test
tests/test_ha_failover.sh	Cluster/platform integration smoke for HA failover expectations
Makefile targets k3s-install, smoke, backup, restore, preflight, test-ha-failover	Cluster substrate operations and safety rails
bin/railiance subcommands backup and preflight	Compatibility wrapper for retained S2 operations until a cleaner CLI split exists

Rehome Outside Both Repos

These files are real migration debt, but they should not be normalized into future rail-kubernetes or kept as permanent S2 identity.

Path	Why it needs another home
tools/cmd/railiance-verify-activity-core	Workload-specific reconcile/verify flow for one app
tools/cmd/railiance-reconcile-activity-core-llm-connect	Cross-repo workload-specific helper, not generic substrate or generic rail
tools/cmd/railiance-deploy-activity-core-triage-robustness	Workload-specific deployment hardening helper
tools/cmd/railiance-admin-sync-smoke	Workload-specific app smoke command
Makefile targets verify-activity-core, reconcile-activity-core-llm-connect, deploy-activity-core-triage-robustness, admin-sync-smoke	Operator entry points for workload-specific helpers above
bin/railiance subcommands deploy-triage-robustness and admin-sync-smoke	Dispatcher surface for workload-specific helpers

Shared Tooling Debt Outside This Wave

The repo also contains bootstrap and shared-tooling commands that belong neither to S2 substrate ownership nor to the future rail-kubernetes rail. They should get a separate placement review rather than piggybacking on the current extraction:

• bin/railiance subcommands doctor, next, plan-host, gen-ssh-key, cloudinit, init-repo, build-spore, seed-local, checklist
• tools/cmd/railiance-doctor
• tools/cmd/railiance-plan-host
• tools/build_spore.sh
• tools/seed_node.sh
• tools/create_railiance_repo.sh
• tools/furnish_railiance_repo.sh

Resulting Rule

Until rail-kubernetes exists, railiance-cluster may host compatibility copies of the generic lifecycle and command surface. It must not keep claiming that those materials are the steady-state S2 ownership boundary.