Add Railiance Stage 2 deploy observe tooling

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.