Add Railiance staged-promotion overlay for flex-auth

FLEX-WP-0011 T01/T02: railiance.app.v1 contract, independently pinned
Helm values for tenant-engine and user-engine, isolated canary cycle
(deploy/observe/promote/rollback), and emergency kubectl path retained.
T03 waits on the custodian drain-plan row.

railiance/README.md

@@ -0,0 +1,82 @@
+# flex-auth Railiance overlay
+
+Canonical staged-promotion contract for flex-auth (`RAIL-BS-WP-0006`,
+`FLEX-WP-0011`). The recovered `deploy/*.yaml` files remain as an emergency
+kubectl path; this overlay is the sanctioned shape.
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `railiance/app.toml` | `railiance.app.v1` contract |
+| `charts/flex-auth/` | One Deployment + Service + NetworkPolicy per release |
+| `values/tenant-engine.yaml` | Production pin for `flex-auth-tenant-engine` |
+| `values/user-engine.yaml` | Production pin for `flex-auth-user-engine` |
+| `values/stage2-canary.yaml` | Isolated canary `flex-auth-canary` (no consumer ingress) |
+| `values/stage3-production.yaml` | Stage 3 values for that same isolated canary release |
+| `tests/stage1.sh` | Local render of every values file |
+
+The two production consumers stay independently pinned and independently
+rollable. Do not collapse them into one Helm release. The official
+`bin/railiance deploy|observe|promote|rollback` cycle operates on the
+**isolated canary** so it cannot move a production pin by accident.
+
+## Stage 1
+
+```bash
+tests/stage1.sh
+# or
+/home/worsch/railiance-bootstrap/bin/railiance run . --pretty
+```
+
+## Stage 2 / Stage 3 (isolated canary)
+
+```bash
+RAILIANCE=/home/worsch/railiance-bootstrap/bin/railiance
+$RAILIANCE deploy --stage 2 . --plan
+$RAILIANCE deploy --stage 2 . --server-dry-run --pretty
+$RAILIANCE deploy --stage 2 . --apply --approval-id <state-hub-id>
+$RAILIANCE observe --stage 2 . --live --pretty
+$RAILIANCE promote . --plan
+$RAILIANCE promote . --apply --approval-id <state-hub-id>
+$RAILIANCE rollback . --apply --approval-id <state-hub-id> --revision <helm-rev>
+```
+
+The canary Service is `flex-auth-canary.flex-auth.svc.cluster.local:8080`.
+Production consumers keep calling their own Service names.
+
+## Rolling a production pin
+
+Policy is baked into the image. Do not build images on a workstation.
+`.forgejo/workflows/image.yaml` publishes `:latest` and `:main-<short-sha>`;
+deploy by digest.
+
+```bash
+# 1. Edit the digest in values/<consumer>.yaml
+# 2. Record the previous digest as the rollback target
+# 3. Apply only that release
+helm upgrade --install flex-auth-<consumer> charts/flex-auth \
+  --namespace flex-auth -f values/<consumer>.yaml --wait --timeout 2m
+
+# 4. Prove the new policy, not just that the pod started
+kubectl -n flex-auth port-forward svc/flex-auth-<consumer> 19099:8080
+curl -s -X POST http://127.0.0.1:19099/v1/check \
+  -H 'Content-Type: application/json' \
+  -d @examples/<consumer>/<request that exercises the change>.json
+```
+
+Emergency kubectl path (no Helm history): `kubectl apply -f deploy/flex-auth-<consumer>.yaml`.
+
+## Rollback
+
+Preferred: `helm rollback flex-auth-<consumer> <revision> -n flex-auth --wait`.
+
+If Helm history is missing: `kubectl -n flex-auth rollout undo deploy/flex-auth-<consumer>`,
+or re-apply the last-known-good digest in `deploy/README.md`.
+
+| Deployment | Last-known-good digest | Policy state |
+| --- | --- | --- |
+| `flex-auth-tenant-engine` | `sha256:c25fc34a6cd7e64d955f8723ec70e176a583d5ae71d76280c4e2d89fba0fe0aa` | **live 2026-08-16** — four-action policy; lifecycle actions deny `unknown_action` |
+| `flex-auth-tenant-engine` *(FLEX-WP-0010 image, scaled to 0)* | `sha256:9320df394a642eff24da8af4a0ee8886a7bb78b0f14d8ee1deeb30ea8eeeaba7` | seven-action policy, previously live 2026-08-11 |
+| `flex-auth-user-engine` | `sha256:1f5290376dc5fcf456dc7a785e394d8b90949dabecd1d3e856f38557149bb5f4` | FLEX-WP-0009-T04, nine fixtures, live 2026-08-16 |
+| `flex-auth-user-engine` *(previous)* | `sha256:a31961c45215aa6baf3bc748c6741ab703c2c8325e61aa7983a355026195e51b` | FLEX-WP-0009-T03, six fixtures |