docs: automate CLI demo recordings with virtui + embed across the docs

.github/workflows/record-docs.yml

@@ -0,0 +1,44 @@
+# Copyright 2026 Undermountain Coding Company
+# SPDX-License-Identifier: Apache-2.0
+
+name: record-docs
+
+# Regenerate the documentation asciicast recordings on demand.
+#
+# GATED to manual dispatch on purpose — same posture as docs.yml. virtui is an
+# early-stage (v0.2.0) recorder, so it is deliberately NOT wired into the
+# required `ci` gate: a flaky upstream must never be able to block `main`.
+# Run this when a demoed command's output changes; download the rendered
+# artifacts and commit the ones you want to embed.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: install virtui (recorder)
+        run: go install github.com/honeybadge-labs/virtui/cmd/virtui@latest
+      - name: install agg (.cast -> .gif renderer)
+        run: |
+          curl -fsSL -o /usr/local/bin/agg \
+            https://github.com/asciinema/agg/releases/latest/download/agg-x86_64-unknown-linux-gnu
+          chmod +x /usr/local/bin/agg
+      - name: record + render demos
+        run: scripts/record-docs.sh --render
+      - uses: actions/upload-artifact@v4
+        with:
+          name: doc-casts
+          path: |
+            docs/assets/casts/*.cast
+            docs/assets/casts/*.gif
+            docs/assets/casts/*.svg
+          if-no-files-found: warn

README.md

@@ -25,6 +25,11 @@ $ kubectl --context arn:aws:eks:us-east-1:…:cluster/prod delete ns payments
    flip this pane:  failsafe toggle
 ```
 
+<p align="center">
+  <img src="docs/assets/casts/explain-block.svg" alt="failsafe explain blocking a kubectl delete on prod, recorded against the real binary" width="760">
+  <br><sub>↑ a real recording — <code>failsafe explain</code> against the shipped binary, regenerated by <a href="scripts/record-docs.sh"><code>scripts/record-docs.sh</code></a></sub>
+</p>
+
 The only thing between a hijacked or careless agent and a wiped cluster is you, clicking
 "allow" on the hundredth prompt — and that fails exactly when you're tired or moving fast.
 **failsafe is the guard that doesn't get tired.**

docs/assets/casts/.gitignore

@@ -0,0 +1,3 @@
+# Rendered GIFs are heavy build artifacts — regenerate with scripts/record-docs.sh --render.
+# .cast (source) and .svg (embedded in docs) ARE committed.
+*.gif

docs/assets/casts/audit.cast

@@ -0,0 +1,21 @@
+{"version":2,"width":92,"height":22,"timestamp":1782354894}
+[0.004957, "o", "\u001b[?2004hroot@vm:/home/user/failsafe# "]
+[0.009090, "i", "export PS1='$ '; cd \"/tmp/failsafe-docs-home/project\"; clear\r"]
+[0.009370, "o", "export PS1='$ '; cd \"/tmp/failsafe-docs-home/project\"; clear\r\n\u001b[?2004l\r"]
+[0.010662, "o", "\u001b[H\u001b[2J\u001b[3J"]
+[0.010778, "o", "\u001b[?2004h$ "]
+[0.522810, "i", "failsafe audit\r"]
+[0.523095, "o", "failsafe audit\r\n"]
+[0.523149, "o", "\u001b[?2004l\r"]
+[0.528713, "o", "Policy layers in effect at /tmp/failsafe-docs-home/project:\r\n\r\n  [bundled]\r\n"]
+[0.528859, "o", "    bundled/aws.rego — 2 block rule(s)\r\n"]
+[0.528966, "o", "    bundled/failsafe.rego — 2 block rule(s)\r\n"]
+[0.529186, "o", "    bundled/git.rego — 0 block rule(s)\r\n    bundled/helm.rego — 2 block rule(s)\r\n"]
+[0.529427, "o", "    bundled/kubectl.rego — 1 block rule(s)\r\n"]
+[0.529509, "o", "    bundled/terraform.rego — 2 block rule(s)\r\n\r\n9 block rules total, 0 allow_override."]
+[0.529577, "o", "\r\n"]
+[0.530404, "o", "\u001b[?2004h$ "]
+[2.539712, "i", "exit\r"]
+[2.539852, "o", "exit"]
+[2.539889, "o", "\r\n\u001b[?2004l\r"]
+[2.539922, "o", "exit\r\n"]

docs/assets/casts/explain-block.cast

@@ -0,0 +1,14 @@
+{"version":2,"width":92,"height":22,"timestamp":1782354881}
+[0.010649, "o", "\u001b[?2004h"]
+[0.010887, "o", "root@vm:/home/user/failsafe# "]
+[0.011159, "i", "export PS1='$ '; cd \"/tmp/failsafe-docs-home/project\"; clear\r"]
+[0.012521, "o", "export PS1='$ '; cd \"/tmp/failsafe-docs-home/project\"; clear\r\n\u001b[?2004l\r"]
+[0.014478, "o", "\u001b[H\u001b[2J\u001b[3J"]
+[0.014559, "o", "\u001b[?2004h$ "]
+[0.524948, "i", "failsafe explain \"kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/prod delete ns payments\"\r"]
+[0.525498, "o", "failsafe explain \"kubectl --context arn:aws:eks:us-east-1:123456789012:cluster/prod delete \r ns payments\"\r\n\u001b[?2004l\r"]
+[0.546886, "o", "── call 1: kubectl ──\r\nVerb:        delete\r\nFlags:\r\n  context         = arn:aws:eks:us-east-1:123456789012:cluster/prod\r\nPositional:  ns payments\r\nEffective cwd: /tmp/failsafe-docs-home/project\r\nMode:        read\r\nPolicy chain (6 modules at this cwd):\r\n  [bundled] bundled/aws.rego\r\n  [bundled] bundled/failsafe.rego\r\n  [bundled] bundled/git.rego\r\n  [bundled] bundled/helm.rego\r\n  [bundled] bundled/kubectl.rego\r\n  [bundled] bundled/terraform.rego\r\nDecision: BLOCK\r\nReason  : kubectl delete blocked in read mode\r\n"]
+[0.548369, "o", "\u001b[?2004h$ "]
+[2.559258, "i", "exit\r"]
+[2.559434, "o", "exit\r\n\u001b[?2004l\r"]
+[2.559469, "o", "exit\r\n"]