Import rail-kubernetes lifecycle tooling

docs/README.md

@@ -7,5 +7,6 @@
 - `stage2-deploy-observe.md` — stage 2 command behavior contract
 - `promote-rollback-onboarding.md` — representative lifecycle command path
 - `railiance-run-command.md` — stage 1 command behavior contract
+- `create-overlay-command.md` — overlay scaffolder behavior contract
 - `wave-1-contract.md` — current rail contract and boundary summary
 - `source-import-plan.md` — source material and migration direction from existing repos

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

docs/source-import-plan.md

@@ -20,16 +20,16 @@ Imported source assets from `railiance-cluster`:
 
 - `schemas/railiance-app.schema.json`
 - `examples/railiance/app.toml`
-
-## Pending First-Wave Imports
-
-Expected source assets from `railiance-cluster`:
-
+- `bin/railiance` generic lifecycle dispatcher surface
 - `tools/create_railiance_overlay_repo.sh`
 - `tools/cmd/railiance-run`
 - `tools/cmd/railiance-stage2`
 - `tools/cmd/railiance-stage3`
 
+## Pending First-Wave Imports
+
+No additional first-wave imports remain pending for this repo-local bootstrap.
+
 ## Deferred Migration Debt
 
 Do not import these into `rail-kubernetes` as part of wave 1: