docs(demo): scene-based demo with intro/changes modes per channel

README.md

@@ -11,9 +11,9 @@ brew install open330/tap/aas
 ```
 
 <div align="center">
-  <img src="docs/assets/cli-usage-sessions.gif" alt="aas CLI demo showing usage and isolated account sessions" width="920" />
+  <img src="docs/assets/cli-demo.gif" alt="aas CLI demo: account list, usage table, an isolated session and a switch" width="920" />
   <br />
-  <sub>Rendered from the reproducible <a href="docs/assets/cli-demo.tape">VHS tape</a>.</sub>
+  <sub>Rendered from reproducible <a href="docs/demo/">VHS scenes</a> against a throwaway fixture.</sub>
 </div>
 
 - **Isolated sessions:** `aas exec work` runs the agent under another account for one session and
@@ -299,8 +299,8 @@ cargo fmt --all -- --check
 cargo clippy --workspace --all-targets --all-features -- -D warnings
 cargo test --workspace --all-targets --all-features
 
-# Regenerate the README CLI demo (requires VHS)
-vhs docs/assets/cli-demo.tape
+# Regenerate the README CLI demo (requires VHS). --mode intro|changes, --channel readme|social|square
+docs/demo/render.sh
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete development workflow,

docs/demo/fixture.sh

@@ -0,0 +1,51 @@
+# shellcheck shell=bash
+# Demo fixture for the README/social recordings. Sourced (hidden) by the generated VHS tape.
+# Builds a throwaway aas state with three accounts and stub agent CLIs; touches nothing real.
+export AAS_CONFIG_DIR=/tmp/aas-demo/config
+export CODEX_HOME=/tmp/aas-demo/native-codex
+export CLAUDE_CONFIG_DIR=/tmp/aas-demo/native-claude
+rm -rf /tmp/aas-demo
+mkdir -p "$AAS_CONFIG_DIR/profiles/codex-personal" "$AAS_CONFIG_DIR/profiles/codex-team" \
+  "$AAS_CONFIG_DIR/profiles/claude-work" /tmp/aas-demo/bin "$CODEX_HOME" "$CLAUDE_CONFIG_DIR"
+
+cat > "$AAS_CONFIG_DIR/accounts.json" <<'JSON'
+{"version":1,"accounts":[
+ {"provider":"claude","name":"work","label":"Work","addedAt":"2026-07-12T00:00:00.000Z","profileType":"isolated"},
+ {"provider":"codex","name":"personal","label":"Personal","addedAt":"2026-07-12T01:00:00.000Z","profileType":"isolated"},
+ {"provider":"codex","name":"team","label":"Team","addedAt":"2026-07-12T02:00:00.000Z","profileType":"isolated"}]}
+JSON
+printf '%s\n' '{"claude":"work","codex":"personal","updated":"2026-07-12T03:00:00.000Z"}' > "$AAS_CONFIG_DIR/.active.json"
+printf '%s\n' '{"tokens":{"access_token":"demo-personal"}}' > "$AAS_CONFIG_DIR/profiles/codex-personal/auth.json"
+printf '%s\n' '{"tokens":{"access_token":"demo-team"}}' > "$AAS_CONFIG_DIR/profiles/codex-team/auth.json"
+
+now=$(($(date +%s) * 1000)); h=$((60 * 60 * 1000))
+meter() { printf '{"label":"%s","used_pct":%s,"reset_ms":%s}' "$1" "$2" $((now + $3 * h / 60)); }
+entry() { printf '"%s":{"fetchedAtMs":%s,"usage":{"headline":"%s","plan":"%s","meters":[%s,%s],"notes":[],"error":null}}' \
+  "$1" "$now" "$2" "$3" "$4" "$5"; }
+{
+  printf '{"version":1,"entries":{'
+  entry claude/work "subscription=max tier=default_claude_max_20x" max \
+    "$(meter 5h 86 47)" "$(meter 7d 62 $((52 * 60)))"; printf ','
+  entry codex/personal "codex pro" pro "$(meter 5h 12 $((3 * 60 + 12)))" "$(meter 7d 31 $((118 * 60)))"; printf ','
+  entry codex/team "codex team" team "$(meter 5h 41 $((1 * 60 + 38)))" "$(meter 7d 57 $((76 * 60)))"
+  printf '}}\n'
+} > "$AAS_CONFIG_DIR/usage-cache.json"
+
+# Stub agent CLIs: report which profile they were launched with instead of starting a real session.
+for agent in codex claude; do
+  cat > "/tmp/aas-demo/bin/$agent" <<STUB
+#!/bin/sh
+home=\${CODEX_HOME:-\${CLAUDE_CONFIG_DIR:-}}
+profile=\${home##*/}
+case "\$profile" in native-*) profile="your default login" ;; esac
+printf '\033[32m✓\033[0m %s session started\n  profile: \033[1m%s\033[0m\n' "$agent" "\$profile"
+STUB
+  chmod +x "/tmp/aas-demo/bin/$agent"
+done
+
+export PATH="/tmp/aas-demo/bin:$PWD/target/release:$PATH"
+export PS1='\[\033[38;5;111m\]❯\[\033[0m\] '
+# scene "Title" — full-width caption bar shown at the top of a cleared screen.
+# end_card "Title" "line"… — closing card with no prompt left on screen.
+end_card() { PS1=''; scene "$1"; shift; printf '  %s\n' "$@"; }
+scene() { clear; printf '\033[1;38;5;183m%s\033[0m\n\033[38;5;60m%s\033[0m\n\n' "$1" "$(printf '─%.0s' $(seq 1 ${#1}))"; }

docs/demo/render.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Render the aas demo with VHS.
+#
+#   docs/demo/render.sh [--mode intro|changes] [--channel readme|social|square] [--out PATH]
+#
+#   --mode intro      first-time introduction (README, launch posts)             [default]
+#   --mode changes    what is new since the last release (release notes, update posts)
+#   --channel readme  1000px-wide GIF for README.md                              [default]
+#   --channel social  1280x720 MP4 for X, LinkedIn, YouTube
+#   --channel square  860x860 MP4 for feeds that crop to square (scaled up by the feed)
+#
+# Scenes live in docs/demo/scenes/<mode>.tape. docs/demo/fixture.sh builds a throwaway state
+# under /tmp/aas-demo, so no real account is touched. Requires vhs and cargo. If vhs stops at
+# "could not open ttyd: EOF", run with VHS_NO_SANDBOX=true.
+set -euo pipefail
+
+mode=intro channel=readme out=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --mode) mode="$2"; shift 2 ;;
+    --channel) channel="$2"; shift 2 ;;
+    --out) out="$2"; shift 2 ;;
+    -h|--help) sed -n '2,14p' "$0"; exit 0 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+root="$(cd "$(dirname "$0")/../.." && pwd)"
+scenes="docs/demo/scenes/$mode.tape"
+[ -f "$root/$scenes" ] || { echo "no scenes for mode '$mode' ($scenes)" >&2; exit 2; }
+
+case "$channel" in
+  readme) width=1000 height=560 font=16 pad=28 margin=24 ext=gif ;;
+  social) width=1280 height=720 font=20 pad=28 margin=24 ext=mp4 ;;
+  # On-screen text size depends on how many columns the canvas holds, not on its pixels: the
+  # usage table needs 80, so this is sized to 81 (measured with `tput cols` under VHS) and the
+  # feed scales it up.
+  square) width=860 height=860 font=15 pad=8 margin=0 ext=mp4 ;;
+  *) echo "unknown channel: $channel" >&2; exit 2 ;;
+esac
+
+# The intro GIF is the README asset; everything else is a build output for posting.
+if [ -z "$out" ]; then
+  if [ "$mode-$channel" = "intro-readme" ]; then
+    out="docs/assets/cli-demo.gif"
+  else
+    out="target/demo/aas-$mode-$channel.$ext"
+  fi
+fi
+
+cd "$root"
+mkdir -p "$(dirname "$out")"
+cargo build --release --quiet
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/aas-demo.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT
+tape="$tmp/demo.tape"
+{
+  cat <<TAPE
+Output "$out"
+Set Shell "bash"
+Set FontFamily "Menlo"
+Set FontSize $font
+Set LineHeight 1.25
+Set Width $width
+Set Height $height
+Set Padding $pad
+Set Margin $margin
+Set MarginFill "#1e1e2e"
+Set BorderRadius 14
+Set WindowBar Colorful
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 45ms
+Set CursorBlink false
+Set Framerate 30
+
+Hide
+Type "source docs/demo/fixture.sh"
+Enter
+Type "clear"
+Enter
+Show
+TAPE
+  cat "$scenes"
+  cat <<'TAPE'
+
+Hide
+Type "rm -rf /tmp/aas-demo"
+Enter
+TAPE
+} > "$tape"
+
+vhs "$tape"
+echo "wrote $out"

docs/demo/scenes/changes.tape

@@ -0,0 +1,34 @@
+# changes: what is new since the last release (release notes, update posts).
+# Rewrite these scenes for each release from CHANGELOG.md's [Unreleased] section.
+
+Hide
+Type `scene "New: a provider name runs its active account"`
+Enter
+Show
+Type "aas active codex"
+Sleep 300ms
+Enter
+Sleep 1.2s
+Type "aas exec codex"
+Sleep 300ms
+Enter
+Sleep 2.5s
+
+Hide
+Type `scene "Switch, and the provider name follows"`
+Enter
+Show
+Type "aas switch codex team"
+Sleep 300ms
+Enter
+Sleep 1s
+Type "aas exec codex"
+Sleep 300ms
+Enter
+Sleep 3s
+
+Hide
+Type `end_card "Update: brew upgrade aas" "Release notes: github.com/Open330/aas/releases"`
+Enter
+Show
+Sleep 3s

docs/demo/scenes/intro.tape

@@ -0,0 +1,47 @@
+# intro: first-time introduction of aas (README, launch posts, landing pages).
+
+Hide
+Type `scene "Several agent accounts on one machine"`
+Enter
+Show
+Type "aas list"
+Sleep 300ms
+Enter
+Sleep 2.5s
+
+Hide
+Type `scene "Every account's remaining usage at a glance"`
+Enter
+Show
+Type "aas usage"
+Sleep 300ms
+Enter
+Sleep 4s
+
+Hide
+Type `scene "One session on another account, default login untouched"`
+Enter
+Show
+Type "aas exec team"
+Sleep 300ms
+Enter
+Sleep 1.5s
+Type "codex"
+Sleep 300ms
+Enter
+Sleep 2.5s
+
+Hide
+Type `scene "Or switch the default in one command"`
+Enter
+Show
+Type "aas switch codex team"
+Sleep 300ms
+Enter
+Sleep 2.5s
+
+Hide
+Type `end_card "aas: Agent Account Switcher" "brew install open330/tap/aas" "github.com/Open330/aas"`
+Enter
+Show
+Sleep 3.5s