From 3aa0c2d0d086c1045565abf9f152c41d49f2976f Mon Sep 17 00:00:00 2001
From: lgcosta <me@luizgustavo.pro.br>
Date: Wed, 11 Nov 2026 19:56:24 -0300
Subject: [PATCH] docs: demo guide (asciinema recording/playback/upload)
 EN+PT-BR

---
 docs/en/demo.md    | 41 +++++++++++++++++++++++++++++++++++++++++
 docs/pt-BR/demo.md | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/en/demo.md
 create mode 100644 docs/pt-BR/demo.md

diff --git a/docs/en/demo.md b/docs/en/demo.md
new file mode 100644
index 0000000..b08b3a1
--- /dev/null
+++ b/docs/en/demo.md
@@ -0,0 +1,41 @@
+# Demo (asciinema)
+
+The lab can be recorded as an [asciinema](https://asciinema.org) cast.  Every
+byte in the recording is the real output of the lab VMs (Alpine under libvirt
+running the kernel built from source with `pf.ko`); only the pacing is
+scripted.
+
+## Record
+
+```sh
+pip install asciinema            # once
+bash scripts/vm-run-tests.sh      # or: scripts/vm-create.sh + deploy
+asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
+```
+
+The session walks through:
+
+1. the lab topology and the freshly loaded `pf.ko` (`dmesg` proof),
+2. `pfctl -s info` over the OpenBSD ioctl ABI,
+3. a real `pf.conf` (table, stateful rules, explicit drop) and `pfctl -sr`,
+4. transit ping + `pfctl -ss` (stateful),
+5. `pfctl -t <table> -T show` (live tables),
+6. a blocked ping (counters with `pfctl -sr -vv`),
+7. `divert-to` with the `pdivert` relay (packet to userspace and back),
+8. shutdown.
+
+## Play back
+
+```sh
+asciinema play out/demo-pf-linux.cast
+```
+
+## Upload
+
+```sh
+asciinema upload out/demo-pf-linux.cast
+```
+
+`scripts/demo-record.py` is an alternative recorder that produces the same
+asciicast v2 format without the asciinema binary (it drives the lab over
+ssh and writes the cast itself).
diff --git a/docs/pt-BR/demo.md b/docs/pt-BR/demo.md
new file mode 100644
index 0000000..fd754a2
--- /dev/null
+++ b/docs/pt-BR/demo.md
@@ -0,0 +1,40 @@
+# Demo (asciinema)
+
+O lab pode ser gravado como um cast do [asciinema](https://asciinema.org).
+Cada byte da gravação é a saída real das VMs do lab (Alpine sobre libvirt,
+rodando o kernel compilado do fonte com o `pf.ko`); só o ritmo é roteirizado.
+
+## Gravar
+
+```sh
+pip install asciinema            # uma vez
+bash scripts/vm-run-tests.sh      # ou: scripts/vm-create.sh + deploy
+asciinema rec out/demo-pf-linux.cast -c "bash scripts/demo-session.sh"
+```
+
+A sessão percorre:
+
+1. a topologia do lab e o `pf.ko` recém-carregado (prova no `dmesg`),
+2. `pfctl -s info` pela ABI de ioctl do OpenBSD,
+3. um `pf.conf` real (tabela, regras stateful, drop explícito) e `pfctl -sr`,
+4. ping em trânsito + `pfctl -ss` (stateful),
+5. `pfctl -t <tabela> -T show` (tabelas vivas),
+6. um ping bloqueado (contadores com `pfctl -sr -vv`),
+7. `divert-to` com o relay `pdivert` (pacote vai ao userspace e volta),
+8. desligamento.
+
+## Reproduzir
+
+```sh
+asciinema play out/demo-pf-linux.cast
+```
+
+## Publicar
+
+```sh
+asciinema upload out/demo-pf-linux.cast
+```
+
+`scripts/demo-record.py` é um gravador alternativo que produz o mesmo formato
+asciicast v2 sem o binário asciinema (ele conduz o lab por ssh e escreve o
+cast diretamente).