Demo Guide

This page shows the fastest way to produce a clean, repeatable demo for gig.

Why The Demo Matters

gig lands best when people can see the product promise quickly:

  • guided CLI front door
  • command-palette front door that accepts ticket-like queries
  • remote-first workflow
  • clear ticket audit
  • release verdict instead of raw Git output

A strong demo helps docs, portfolio pages, hiring conversations, and GitHub stars for the same reason: it makes the value obvious fast.

Run The Deterministic Walkthrough

./scripts/demo/frontdoor.sh

What it shows:

  • gig opening the guided front door
  • the branded ticket-to-release terminal layout
  • saving a remote-style project
  • re-opening gig with current-project shortcuts
  • gig assist doctor readiness output
  • gig assist setup bootstrap output

The script is deterministic and does not require live provider access.

Record The Terminal Cast

./scripts/demo/record-frontdoor.sh

Default output:

docs/assets/gig-demo.cast

If asciinema is not installed, the script falls back to the deterministic local cast builder and still writes the same .cast file.

You can also choose a custom output path:

./scripts/demo/record-frontdoor.sh /tmp/gig-demo.cast

Optional: Render Shareable Assets

If you want a README- or social-friendly showcase asset:

./scripts/demo/render-share-assets.sh

Default outputs:

docs/assets/gig-showcase.gif
docs/assets/gig-showcase.mp4

This script renders the repo's SVG demo states into PNG frames with qlmanage, then builds a short MP4 and GIF with ffmpeg.

For a 45 to 60 second product demo, keep the flow tight:

  1. show gig with no arguments
  2. show the command palette idea: repo payments, gh owner/name, ABC-123, then verify
  3. show one remote-style project being saved
  4. show gig inspect or the guided shortcut path
  5. close with gig verify, gig packet, or gig assist audit

That sequence sells the strongest product story without drowning the viewer in command surface area.

Publishing Checklist

Use the demo in these places:

  • README hero link or thumbnail
  • GitHub release notes
  • LinkedIn or X post with one clear sentence about the release-audit problem
  • portfolio page or job application follow-up

When writing the caption, lead with:

  • gig = ticket-to-release confidence
  • multi-repo ticket reconciliation
  • remote-first release audit
  • deterministic evidence with optional AI explanation

Supporting Assets

The repo already includes stable visual assets for documentation and project showcases:

  • docs/assets/gig-showcase.gif
  • docs/assets/gig-showcase.mp4
  • docs/assets/gig-demo-thumbnail.svg
  • docs/assets/ticket-inspect-demo.svg
  • docs/assets/ticket-verify-demo.svg
  • docs/assets/ticket-assist-demo.svg

Use those when you need a consistent visual story without rerecording screenshots.