Add Railiance canary chart template

docs/README.md

@@ -76,6 +76,7 @@ From two bare Linux servers, a Git repo, and valid credentials, you can rebuild
 - [Deployment lifecycle](deployment-lifecycle.md)
 - [Railiance app.toml contract](app-toml-contract.md)
 - [Railiance overlay repo pattern](overlay-repo-pattern.md)
+- [Canary Helm template](canary-helm-template.md)
 - [Railiance run command](railiance-run-command.md)
 
 ## 👥 Contributing

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

@@ -97,8 +97,9 @@ Stage 2 candidate.
 
 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.
-It should keep defaults conservative and route production-specific choices
-through `values/` files.
+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/`
 
@@ -112,11 +113,14 @@ 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`
+### `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.
-Workload-specific tests can extend it.
+
+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`
 
@@ -147,8 +151,8 @@ fetch secrets, or push Git remotes.
 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`.
-5. Use later T04-T07 commands to run, deploy, observe, promote, and rollback.
+4. Run `tests/stage1.sh` and `tests/stage2-template.sh`.
+5. Use later T06-T07 commands to deploy, observe, promote, and rollback.
 
 ## Safety Rules