Import supporting rail-kubernetes docs

docs/README.md

@@ -1,6 +1,11 @@
 # rail-kubernetes Docs
 
 - `app-toml-contract.md` — canonical workload declaration contract for the rail
+- `overlay-repo-pattern.md` — compatibility-era overlay pattern on the path to `rapp-*`
+- `canary-helm-template.md` — stage-aware canary/stable chart pattern
 - `deployment-lifecycle.md` — canonical stage 1 / 2 / 3 lifecycle contract
+- `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
 - `wave-1-contract.md` — current rail contract and boundary summary
 - `source-import-plan.md` — source material and migration direction from existing repos

docs/canary-helm-template.md

@@ -0,0 +1,55 @@
+# Canary Helm Template
+
+Generated Railiance overlays include a stage-aware Helm chart for Stage 2
+canaries and Stage 3 stable promotion.
+
+The chart keeps stable and canary release identities explicit:
+
+- `railiance.stableRelease` names the current stable release;
+- `railiance.canaryRelease` names the Stage 2 candidate release;
+- `railiance.stage` selects the rendered identity, labels, and selectors;
+- `railiance.previousStable` records rollback context before promotion.
+
+## Traffic Shape
+
+The default Stage 2 values use an isolated canary ingress:
+
+```yaml
+railiance:
+  stage: canary
+  traffic:
+    mode: isolated
+
+ingress:
+  enabled: true
+```
+
+This creates canary Deployment, Service, and Ingress resources without changing
+the stable release. For environments that use Traefik weighted routing, set:
+
+```yaml
+railiance:
+  traffic:
+    mode: weighted
+    provider: traefik
+    stableWeight: 95
+    canaryWeight: 5
+```
+
+The chart then renders a `TraefikService` and `IngressRoute` that split traffic
+between the stable and canary services. Other ingress controllers can use the
+same stable/canary values layout with controller-specific annotations or a later
+provider template.
+
+## Observability And Safety
+
+Generated workloads include:
+
+- Prometheus-compatible scrape annotations on pods and services;
+- readiness and liveness HTTP probes;
+- conservative resource requests/limits for single-node clusters;
+- separate `values/stage2-canary.yaml` and `values/stage3-production.yaml` so
+  canary exposure and stable promotion can be reviewed independently.
+
+Run `tests/stage2-template.sh` in the overlay repo before any Stage 2 attempt.
+It verifies the scaffold and runs `helm template` when Helm is available.

docs/overlay-repo-pattern.md

@@ -0,0 +1,179 @@
+# Railiance Overlay Repo Pattern
+
+A Railiance overlay repo wraps a third-party upstream application without
+forking Railiance deployment logic into the upstream source repository.
+
+The overlay repo owns the Railiance deployment contract, promotion evidence,
+Helm/Kubernetes overlay, values, probes, and runbooks. The upstream repository
+remains the source of application code and release artifacts.
+
+This pattern is a compatibility-era scaffolding model inside the
+`rail-kubernetes` migration. Long-term first-class package ownership should
+move toward `rapp-*` repos. Until the `rapp-*` path is fully materialized, the
+overlay structure remains a useful generic pattern for Kubernetes-managed
+workloads.
+
+## Goals
+
+- Keep upstream code and Railiance deployment mechanics separate.
+- Make Stage 1, Stage 2, Stage 3, and rollback behavior reproducible from Git.
+- Declare all platform dependencies, health checks, and secret references in
+  `railiance/app.toml` without plaintext secret values.
+- Allow third-party applications to adopt the staged promotion lifecycle without
+  requiring changes to their upstream repositories.
+
+## Repo Layout
+
+A generated compatibility overlay repo should look like this:
+
+```text
+<app>-railiance-overlay/
+  README.md
+  railiance/
+    app.toml
+    upstream.toml
+  charts/
+    <app>/
+      Chart.yaml
+      values.yaml
+      templates/
+        deployment.yaml
+        service.yaml
+  values/
+    stage1.yaml
+    stage2-canary.yaml
+    stage3-production.yaml
+  patches/
+    upstream/.gitkeep
+  tests/
+    stage1.sh
+  runbooks/
+    rollback.md
+  docs/
+    promotion.md
+```
+
+When a workload graduates into a durable package repo, the preferred target is
+to keep the same contract surfaces while moving the repo identity toward
+`rapp-<workload>`.
+
+## Ownership Boundary
+
+The overlay repo owns:
+
+- `railiance/app.toml` staged promotion declaration;
+- Railiance-specific Helm chart, values, probes, and runbooks;
+- canary and promotion evidence expectations;
+- secret references by approved route and target object name;
+- compatibility notes for a specific upstream revision or release line.
+
+The upstream repo owns:
+
+- application source code;
+- upstream build and release artifacts;
+- upstream tests and release notes;
+- upstream vulnerability and license notices.
+
+The overlay must not vendor upstream source by default. If a patch is required,
+store the patch under `patches/upstream/` and record why the patch exists, when
+it can be retired, and which upstream issue or release should replace it.
+
+## Required Files
+
+### `railiance/app.toml`
+
+This file follows `docs/app-toml-contract.md` and
+`schemas/railiance-app.schema.json` from `rail-kubernetes`. It is the primary
+machine-readable contract for promotion tooling.
+
+### `railiance/upstream.toml`
+
+This file records non-secret upstream identity:
+
+```toml
+[upstream]
+url = "https://example.com/vendor/app.git"
+revision = "v1.2.3"
+tracking = "tag"
+license = "see-upstream"
+notes = "Railiance overlay only; upstream code is not vendored here."
+```
+
+`revision` should be immutable where possible: tag, commit SHA, release id, or
+image digest. Mutable branches are acceptable only before a workload becomes a
+Stage 2 candidate.
+
+### `charts/<app>/`
+
+The chart is the Railiance deployment wrapper. It may start as a thin Helm
+chart around an upstream image and grow only as required by the promotion gates.
+Generated charts include stable/canary release identities, Prometheus-compatible
+annotations, HTTP probes, resource limits, isolated canary ingress, and optional
+Traefik weighted routing. Production-specific choices stay in `values/` files.
+
+### `values/`
+
+Stage values separate local validation, canary, and production settings:
+
+- `stage1.yaml`: local or dry-run defaults;
+- `stage2-canary.yaml`: limited exposure canary defaults;
+- `stage3-production.yaml`: stable production defaults.
+
+Secret values do not belong in these files. Use Kubernetes Secret,
+ExternalSecret, OpenBao, KeyCape, or another approved route and record only the
+reference name.
+
+### `tests/stage1.sh` And `tests/stage2-template.sh`
+
+Stage 1 should be runnable without production credentials. The generated script
+performs syntax and Helm rendering checks when the relevant tools are available.
+
+Stage 2 template validation verifies the canary scaffold, stable/canary values,
+Prometheus annotations, rollback labels, and Helm rendering when Helm is
+available. Workload-specific tests can extend either script.
+
+### `runbooks/rollback.md`
+
+Rollback instructions must exist before Stage 2. Early overlays may include a
+placeholder, but it must name the intended rollback target and verification
+check.
+
+## Creation Tool
+
+During the migration window, the compatibility scaffold still comes from:
+
+```bash
+railiance-cluster/tools/create_railiance_overlay_repo.sh \
+  --app-id forgejo \
+  --name "Forgejo" \
+  --owner railiance-forge \
+  --criticality critical \
+  --upstream-url https://codeberg.org/forgejo/forgejo.git \
+  --upstream-revision v12.0.0 \
+  --out-dir /tmp/forgejo-railiance-overlay
+```
+
+The tool writes only local files. It does not call Gitea, clone upstream code,
+fetch secrets, or push Git remotes.
+
+Long-term, the generic scaffolding behavior should move under the rail and/or
+become `rapp-*`-aware rather than preserving the overlay name forever.
+
+## Promotion Use
+
+1. Generate or update the overlay repo.
+2. Fill in accurate image, namespace, health, dependency, and rollback fields.
+3. Validate `railiance/app.toml` against the schema.
+4. Run `tests/stage1.sh` and `tests/stage2-template.sh`.
+5. Use later Stage 2 and Stage 3 commands to deploy, observe, promote, and
+   rollback.
+
+## Safety Rules
+
+- No plaintext secrets in `railiance/app.toml`, values files, tests, runbooks,
+  or generated evidence.
+- Do not hide deployment logic in upstream source patches.
+- Do not promote mutable upstream branches to Stage 2/3 without an explicit
+  operator exception.
+- Production-critical overlays require human approval before canary exposure and
+  production promotion.

docs/promote-rollback-onboarding.md

@@ -0,0 +1,71 @@
+# Promote, Rollback, And Onboarding
+
+This guide shows the representative Railiance lifecycle for an overlay repo.
+Commands default to plan mode so the path is repeatable before cluster access or
+operator approval exists.
+
+## Stage 1
+
+```bash
+bin/railiance run /path/to/overlay --pretty
+```
+
+Stage 1 validates `railiance/app.toml`, local commands, and local checks. Save
+the JSON result as non-secret evidence before Stage 2.
+
+## Stage 2
+
+```bash
+bin/railiance deploy --stage 2 /path/to/overlay --plan --pretty
+bin/railiance observe --stage 2 /path/to/overlay --plan --pretty
+```
+
+When Helm, kubectl, cluster access, and approval evidence are ready:
+
+```bash
+bin/railiance deploy --stage 2 /path/to/overlay --apply --approval-id <state-hub-id>
+bin/railiance observe --stage 2 /path/to/overlay --live --pretty
+```
+
+For critical workloads, Stage 2 apply must not run until the operator has
+approved canary exposure and rollback context is known.
+
+## Stage 3
+
+```bash
+bin/railiance promote /path/to/overlay --plan --pretty
+bin/railiance rollback /path/to/overlay --plan --pretty
+```
+
+Promotion plan mode emits a `railiance.stage3-promote-result.v1` JSON result
+with stable release identity, chart and values paths, previous-stable target,
+expected evidence, and approval requirements.
+
+Rollback plan mode emits a `railiance.stage3-rollback-result.v1` JSON result
+with rollback strategy, release identity, verification text, and apply-time
+requirements.
+
+When approval evidence and Helm access are ready:
+
+```bash
+bin/railiance promote /path/to/overlay --apply --approval-id <state-hub-id>
+bin/railiance rollback /path/to/overlay --apply --approval-id <state-hub-id> --revision <helm-revision>
+```
+
+Stage 3 apply fails closed if the chart or values are missing, previous stable
+is not recorded, Helm is unavailable, or approval evidence is missing. Rollback
+apply fails closed if the rollback strategy is missing, Helm is unavailable,
+approval evidence is missing, or a Helm revision is required but absent.
+
+## Human Approval Points
+
+Critical infrastructure workloads require explicit operator approval before:
+
+- Stage 2 canary exposure;
+- Stage 3 stable promotion;
+- rollback apply, unless an incident runbook defines a narrower break-glass
+  process and records the evidence id.
+
+Progress notes should include only non-secret result summaries: schema version,
+status, release, namespace, approval id, check counts, and command byte counts.
+Do not paste command logs, kubeconfigs, tokens, or private service output.

docs/railiance-run-command.md

@@ -0,0 +1,52 @@
+# Railiance Run Command
+
+`bin/railiance run` executes Stage 1 local validation for a repository that
+contains `railiance/app.toml`.
+
+The command is intentionally local and conservative:
+
+- reads `railiance/app.toml` using the `railiance.app.v1` contract;
+- runs `[stages.stage1].commands` from the app directory;
+- evaluates Stage 1 check ids listed in `[stages.stage1].checks` when they can
+  be checked locally;
+- emits a machine-readable `railiance.run-result.v1` JSON result;
+- records command references, exit codes, durations, and output byte counts,
+  but not shell text or command stdout/stderr content;
+- strips credentials, query strings, and fragments from URLs before reporting HTTP
+  check results.
+
+## Usage
+
+```bash
+bin/railiance run /path/to/app-or-overlay --pretty
+bin/railiance run . --json-out .railiance/stage1-result.json
+```
+
+The process exits `0` only when all Stage 1 commands and required checks pass.
+Optional checks may be skipped without failing the run. For example, an optional
+local health endpoint can be declared before a local server command exists.
+
+## Supported Local Checks
+
+- `command`: runs the check `run` command in the app directory.
+- `http`: calls the declared URL and compares the HTTP status.
+- `helm`: runs `helm template` when Helm is installed. Required Helm checks fail
+  if Helm is unavailable; optional Helm checks are skipped.
+
+Other check types are reported as skipped or failed depending on whether the
+check is required. Stage 2 and Stage 3 checks are never executed by
+`railiance run`.
+
+## Result Shape
+
+The JSON result includes:
+
+- app identity and source revision;
+- contract path and app directory;
+- command/check status summaries using contract references instead of raw shell
+  commands;
+- expected evidence labels from Stage 1;
+- timing and exit status metadata.
+
+The result is suitable for later promotion gates and State Hub progress notes,
+without embedding secrets or verbose logs.

docs/source-import-plan.md

@@ -10,6 +10,11 @@ Imported 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`
 
 Imported source assets from `railiance-cluster`:
 
@@ -18,14 +23,6 @@ Imported source assets from `railiance-cluster`:
 
 ## Pending First-Wave Imports
 
-Expected source documents from `railiance-cluster`:
-
-- `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`:
 
 - `tools/create_railiance_overlay_repo.sh`

docs/stage2-deploy-observe.md

@@ -0,0 +1,49 @@
+# Stage 2 Deploy And Observe
+
+`bin/railiance deploy --stage 2` and `bin/railiance observe --stage 2` provide
+the repeatable command path for production canaries declared in
+`railiance/app.toml`.
+
+Both commands default to non-mutating plan mode.
+
+## Deploy
+
+```bash
+bin/railiance deploy --stage 2 /path/to/overlay --pretty
+bin/railiance deploy --stage 2 /path/to/overlay --server-dry-run --pretty
+bin/railiance deploy --stage 2 /path/to/overlay --apply --approval-id <state-hub-id>
+```
+
+Plan mode validates the local Stage 2 chart and values paths and emits a
+`railiance.stage2-deploy-result.v1` JSON plan. It does not contact the cluster.
+
+`--server-dry-run` runs `helm upgrade --install --dry-run=server` when Helm and
+cluster access are available. `--apply` runs the Helm canary apply path with
+`--atomic --wait`. If Stage 2 declares `requires_approval = true`, apply mode
+fails closed unless `--approval-id` is provided.
+
+The result records release identity, namespace, chart path, values path,
+expected checks/evidence, precheck status, and command byte counts. It does not
+embed Helm or kubectl logs.
+
+## Observe
+
+```bash
+bin/railiance observe --stage 2 /path/to/overlay --pretty
+bin/railiance observe --stage 2 /path/to/overlay --live --pretty
+```
+
+Plan mode emits the rollout, pod selector, ingress selector, health URL, and
+metrics targets that live observation will query.
+
+Live mode uses `kubectl` to check rollout status, deployment JSON, canary pods,
+ingress/routing resources, and pod metrics when metrics-server is available.
+Metrics unavailability is reported separately so a canary can fail for rollout
+or readiness problems without hiding missing observability.
+
+## Safety
+
+Stage 2 remains blocked when required local paths are missing, Helm is missing
+for dry-run/apply, `kubectl` is missing for live observe, or approval evidence
+is missing for an apply that requires approval. Use the emitted JSON as
+non-secret evidence in State Hub progress notes.

workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md

@@ -79,6 +79,13 @@ still pending.
 `examples/railiance/app.toml`. Helper command surfaces and the remaining
 supporting docs are still pending.
 
+2026-07-25: Imported the remaining generic supporting docs from
+`railiance-cluster`: `docs/overlay-repo-pattern.md`,
+`docs/canary-helm-template.md`, `docs/stage2-deploy-observe.md`,
+`docs/promote-rollback-onboarding.md`, and
+`docs/railiance-run-command.md`. Helper scripts and command implementations
+remain pending.
+
 ## T03 - Prepare the compatibility handoff from `railiance-cluster`
 
 ```task