Skip to content

Add privacy-safe CLI and TUI recordings#123

Open
tony wants to merge 11 commits into
masterfrom
screen-recording
Open

Add privacy-safe CLI and TUI recordings#123
tony wants to merge 11 commits into
masterfrom
screen-recording

Conversation

@tony

@tony tony commented Jul 12, 2026

Copy link
Copy Markdown
Owner

Summary

  • Keep the synthetic recording corpus, recorder inputs, rendered media, and still posters together under docs/_static/demos/.
  • Record 16 VHS scenarios across root help, search, grep, find, JSON/NDJSON, and two TUI workflows, plus canonical asciinema casts for search, grep, find, and ui.
  • Add a local-only {terminal-demo} directive that derives intrinsic geometry from an explicit poster and emits a native, no-JavaScript MP4 player with accessible builder fallbacks.
  • Embed six primary CLI and TUI recordings in their reference pages, while the README keeps linked posters with explicit dimensions.
  • Publish the 16 MP4 recordings and six posters through Sphinx while keeping casts, tapes, helpers, GIFs, and WebMs out of the static copy.
  • Keep the recording and documentation work in ten reviewable commits, with the pnpm regression fix in one separate CI commit.

Color and safety

  • Seed only synthetic Codex, Claude, Cursor, and Gemini history, and neutralize every catalogued store override plus the WSL host probe before agentgrep starts.
  • Reject seeding outside the fixed synthetic sandbox before cleanup.
  • Remove ambient NO_COLOR and FORCE_COLOR at the recording boundary and set truecolor explicitly. The old environment made Textual install its no-color filter, which stripped the TUI palette and materialized terminal-default backgrounds as black.
  • Scan sources, casts, captures, and metadata for developer paths, emails, credentials, secrets, and non-synthetic prompt content.

Preview

CLI

agentgrep search ranking matching prompts

TUI

agentgrep Textual explorer filtering local agent prompts

Verification

  • rm -rf docs/_build; uv run ruff check . --fix --show-fixes; uv run ruff format .; uv run ty check; uv run py.test --reruns 0 -vvv; just build-docs;
  • 2,301 tests passed, 3 skipped, and 3 strict xfails remained expected; 2 snapshots passed.
  • Both TUI capture families decode at 1200 by 700 across GIF, MP4, and WebM; their populated posters decode at the same geometry.
  • The built site contains native players for all six referenced demos, with typed MP4 sources, intrinsic dimensions, controls, and preload="none".
  • The built site contains all 16 MP4s and six posters under _static/demos/, with no recorder sources or alternate media in the static demo copy.
  • Focused directive tests cover asset confinement, required alt/poster metadata, playback sources, copied files, and non-HTML fallbacks.
  • The final pull-request docs and test jobs passed after removing the temporary preview deployment; normal master-only publication rules are restored.

tony added 5 commits July 12, 2026 15:46
why: Reproducible recordings show agentgrep's terminal surfaces without
reading a developer's real history. Keeping the sources beside their
rendered artifacts makes every preview refreshable.

what:
- Seed synthetic Codex, Claude, Cursor, and Gemini stores
- Record CLI and TUI workflows as GIF, MP4, WebM, and asciinema casts
- Add still poster frames for lightweight documentation previews
- Remove ambient color controls so Textual keeps its intended palette
why: The quickstart introduces both terminal interfaces with command
snippets alone. Still previews make their output visible immediately
without forcing an animated download.

what:
- Embed a ranked-search preview beside the CLI quickstart
- Embed an explorer preview beside the TUI invocation
- Link both stills to their hosted MP4 recordings
why: The CLI reference explains each output shape in prose, but readers
cannot see its hierarchy, highlighting, or terminal color at a glance.

what:
- Put the root help preview on the CLI landing page
- Add search, grep, and find previews to their command references
- Link each still preview to its hosted MP4 recording
why: The explorer's search, results, detail, and sticky-filter panes are
spatial interactions that are easier to understand from the real UI.

what:
- Add an explorer preview after the launch examples
- Place a filtered-results preview beside the sticky-filter guide
- Link both still previews to their hosted MP4 recordings
why: Sphinx copies the whole demo source tree from `_static` by default,
which would publish recorder inputs, alternate renders, and duplicate
poster files beside the linked videos.

what:
- Keep casts, tapes, helpers, GIFs, WebMs, and poster sources out
- Leave MP4 recordings available at stable `_static` URLs
- Let Sphinx copy referenced PNG posters through its image pipeline
tony added 6 commits July 12, 2026 19:57
why: Static posters linked to recordings do not provide in-page playback or
reserve a tested video surface across Sphinx builders.

what:
- Add a local-only terminal-demo directive with native MP4 playback.
- Infer intrinsic dimensions from required posters and publish responsive CSS.
- Cover asset validation, builder fallbacks, playback, and copied files.
why: CLI readers should be able to play each primary command demonstration
without leaving the command reference.

what:
- Embed the help, search, grep, and find MP4 recordings.
- Retain explicit posters and accessible descriptions for every demo.
why: The explorer overview and sticky-filter workflow are easier to understand
when their recordings play where those interactions are documented.

what:
- Embed the primary TUI and loaded-result filter recordings.
- Keep explicit posters and accessible descriptions for both workflows.
why: Explicit poster geometry prevents the README from shifting as the linked
CLI and TUI previews load.

what:
- Declare the search poster's intrinsic width and height.
- Declare the reframed TUI poster's intrinsic width and height.
why: The original wide captures made explorer text too small when embedded in
the documentation and did not foreground a populated detail pane.

what:
- Render both TUI workflows at 1200 by 700 with an 18-pixel font.
- Shorten each recording around one meaningful loaded-result interaction.
- Extract matching populated posters and regenerate GIF, MP4, and WebM files.
why: The moving pnpm 11 range began resolving to 11.12.0, whose bootstrap
self-update crashes in action-setup before the documentation build starts.
The previous docs runs proved 11.11.0 against the committed lockfile.

what:
- Pin the docs workflow to the last known-good pnpm 11 release.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant