Import rail-kubernetes lifecycle tooling

docs/create-overlay-command.md

@@ -0,0 +1,58 @@
+# Create Overlay Command
+
+`bin/railiance create-overlay` scaffolds a local Railiance overlay repo for a
+third-party upstream application.
+
+The command is intentionally local and conservative:
+
+- records the upstream source in `railiance/upstream.toml`;
+- generates a stage-aware `railiance/app.toml`;
+- creates a starter Helm chart, stage values, tests, and runbooks;
+- initializes only local files and directories;
+- does not clone upstream code, create remotes, fetch secrets, or push
+  anything.
+
+## Usage
+
+```bash
+bin/railiance create-overlay \
+  --app-id forgejo \
+  --upstream-url https://codeberg.org/forgejo/forgejo \
+  --name Forgejo \
+  --owner platform \
+  --criticality high \
+  --init-git
+```
+
+Required arguments:
+
+- `--app-id`
+- `--upstream-url`
+
+Useful optional arguments:
+
+- `--name`
+- `--owner`
+- `--criticality`
+- `--upstream-revision`
+- `--upstream-tracking`
+- `--out-dir`
+- `--init-git`
+
+## Generated Structure
+
+The scaffold creates:
+
+- `README.md`
+- `railiance/upstream.toml`
+- `railiance/app.toml`
+- `charts/<app-id>/templates/`
+- `values/`
+- `patches/upstream/`
+- `tests/`
+- `runbooks/`
+- `docs/`
+
+The output is a compatibility-era overlay starting point on the path toward
+future `rapp-*` packaging. It keeps the current migration window usable without
+moving workload ownership into `rail-kubernetes`.