diff --git a/workflows/README.md b/workflows/README.md
index 9a61540b3..40c593fb6 100644
--- a/workflows/README.md
+++ b/workflows/README.md
@@ -246,13 +246,19 @@ steps can branch on it:
   then:
     - id: review
       type: gate
-      message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Retry or skip?"
+      message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to continue, or reject to skip the rest of this branch."
       on_reject: skip
   else:
     - id: next-thing
       command: speckit.next-thing
 ```
 
+The gate's default `options: [approve, reject]` map directly to "continue
+the run" vs. "skip the rest of this branch" — gates do not automatically
+re-run the failed step. To express a retry path, either define custom
+gate options and branch on the choice downstream, or wrap the failing
+step in your own loop.
+
 **Notes:**
 
 - The field must be a literal boolean (`true` / `false`); coerced
@@ -284,6 +290,33 @@ message: "{{ status | default('pending') }}"
 
 Supported filters: `default`, `join`, `contains`, `map`.
 
+### Runtime Context
+
+`{{ context.* }}` exposes engine-managed runtime metadata for the
+current run:
+
+| Variable | Description |
+|----------|-------------|
+| `context.run_id` | The current workflow run id (the same value Spec Kit prints as `Run ID:` at the end of `workflow run`). Auto-generated runs are 8-character hex from `uuid4`; operator-supplied ids may be any alphanumeric string with hyphens or underscores. Empty string outside a run context. |
+
+```yaml
+# Stamp telemetry events with the run id for cross-system join.
+- id: emit-event
+  type: shell
+  run: 'echo "{\"run_id\":\"{{ context.run_id }}\",\"event\":\"started\"}" >> events.jsonl'
+
+# Per-run scratch directory.
+- id: prep-scratch
+  type: shell
+  run: 'mkdir -p /tmp/run-{{ context.run_id }}'
+
+# Pass run id into a command for artifact metadata.
+- id: tag-artifact
+  command: speckit.specify
+  input:
+    args: "{{ context.run_id }}"
+```
+
 ## Input Types
 
 Workflow inputs are type-checked and coerced from CLI string values: