# 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.