docs: switch README demo to a VHS recording (fixes truncation)

CONTRIBUTING.md

@@ -89,7 +89,14 @@ Some files are produced by scripts; edit the generator, not the output:
 
 - `docs/commands.md` and the website command reference — `npm run docs:commands`
   (run after `npm run build`, which writes the oclif manifest).
-- `docs/demo.svg` (the animated README terminal) — `npm run docs:demo`.
+- `docs/demo.webp` (the animated README terminal) — `npm run docs:demo`, which
+  runs [VHS](https://github.com/charmbracelet/vhs) on `docs/demo.tape`. Requires
+  `vhs` and an ffmpeg built with **libwebp** (Homebrew's core ffmpeg lacks it):
+  `brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-webp`.
+  Also needs an authenticated pdcli profile (use a sandbox). For a polished,
+  reproducible recording, first run `./scripts/seed-demo.sh` — it builds a clean
+  "pdcli demo" pipeline (sane deal values, a duplicate person, a stale deal so
+  `audit` has findings) and points the tape at it.
 
 `oclif.manifest.json` is generated and git-ignored; never commit it.
 

README.md

@@ -9,7 +9,7 @@
 [![Docs](https://img.shields.io/badge/docs-wavyx.github.io%2Fpdcli-1292EE)](https://wavyx.github.io/pdcli/)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wavyx/pdcli/main/docs/demo.svg" alt="pdcli demo — running pipeline health and a winning deal update" width="720">
+  <img src="https://raw.githubusercontent.com/wavyx/pdcli/main/docs/demo.webp" alt="pdcli demo — pipeline health, deal summary, and pipeline coverage" width="760">
 </p>
 
 Command-line interface for [Pipedrive](https://www.pipedrive.com/) — fast, scriptable, built for terminals, CI pipelines, and AI agents.

docs/demo.tape

@@ -0,0 +1,57 @@
+# docs/demo.tape — regenerate the animated README terminal with VHS.
+#
+#   brew install vhs           # or: go install github.com/charmbracelet/vhs@latest
+#   npm run docs:demo          # runs: vhs docs/demo.tape  →  docs/demo.webp
+#
+# This records REAL pdcli output, so run it against an AUTHENTICATED profile —
+# point it at a sandbox/demo account, not production. The commands below are
+# read-only and show aggregates only (no contact PII). Swap them freely, but
+# avoid mutating commands so the recording is repeatable.
+
+# WebP: crisp + ~10x smaller than GIF, renders in a GitHub <img>. Needs an ffmpeg
+# built with libwebp — Homebrew's core ffmpeg lacks it, so install the tap build:
+#   brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-webp
+Output docs/demo.webp
+
+Require pdcli
+
+# --- look & feel -------------------------------------------------------------
+Set Shell bash
+Set FontSize 16
+Set Width 1200          # wide enough that no output line clips (the old SVG was 720)
+Set Height 760
+Set Padding 28
+Set BorderRadius 12
+Set TypingSpeed 45ms
+Set CursorBlink true
+# Brand palette (matches the docs site / old demo): dark green ground, mint accent.
+Set Theme { "name": "pdcli", "background": "#0c1611", "foreground": "#c9d4cd", "cursor": "#4ade80", "selection": "#1f2b24", "black": "#0a120e", "brightBlack": "#6b7d72", "red": "#e06c75", "brightRed": "#e06c75", "green": "#4ade80", "brightGreen": "#4ade80", "yellow": "#e5c07b", "brightYellow": "#e5c07b", "blue": "#61afef", "brightBlue": "#61afef", "magenta": "#c678dd", "brightMagenta": "#c678dd", "cyan": "#56b6c2", "brightCyan": "#56b6c2", "white": "#c9d4cd", "brightWhite": "#ffffff" }
+
+# --- start clean -------------------------------------------------------------
+Hide
+Type "clear" Enter
+Show
+
+# --- scenes (read-only) ------------------------------------------------------
+# This account has 2 pipelines, so pipeline-scoped reports need --pipeline.
+# Each scene clears first (Hide/clear/Show) so output starts at the top — keeps
+# tall tables readable and one scene from bleeding into the next. Keep each
+# scene's output SHORT enough to fit the Height above (a full `field list` would
+# overflow and the frame catches it mid-scroll).
+Type "pdcli pipeline health --pipeline 1" Sleep 400ms Enter
+Sleep 3s
+
+Hide
+Type "clear" Enter
+Show
+Type "pdcli funnel --pipeline 1" Sleep 400ms Enter
+Sleep 3s
+
+Hide
+Type "clear" Enter
+Show
+Type "pdcli audit" Sleep 400ms Enter
+Sleep 3.5s
+
+# hold the final frame so the loop doesn't appear cut off
+Sleep 1.8s

package.json

@@ -197,7 +197,7 @@
   "scripts": {
     "build": "oclif manifest",
     "docs:commands": "npm run build && node scripts/gen-commands.mjs",
-    "docs:demo": "node scripts/gen-demo.mjs",
+    "docs:demo": "vhs docs/demo.tape",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "test": "vitest run",

scripts/seed-demo.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+#
+# seed-demo.sh — build a clean, realistic demo pipeline in your Pipedrive
+# SANDBOX so the README recording (docs/demo.tape → docs/demo.gif/webp) looks
+# polished instead of reflecting whatever junk a shared sandbox accumulated.
+#
+# It creates:
+#   - a "pdcli demo" pipeline with 4 stages (rising win probabilities)
+#   - 10 open deals with sane €values (per-stage totals mirror the hero frames)
+#   - 1 stale deal (old expected close) and a duplicate person, so `pdcli audit`
+#     has genuine findings to show
+# then rewrites the `--pipeline N` ids in docs/demo.tape to the new pipeline.
+#
+# Requires `pdcli` on PATH and an authenticated profile (use a SANDBOX, not
+# production — this writes data). Run once, then `npm run docs:demo`.
+#
+#   pdcli auth login            # or: export PDCLI_COMPANY_DOMAIN / PDCLI_API_TOKEN
+#   ./scripts/seed-demo.sh
+#
+# Everything lands in the new pipeline, so cleanup is just deleting it.
+
+set -euo pipefail
+
+command -v pdcli >/dev/null || { echo "pdcli not on PATH (npm i -g @wavyx/pdcli)"; exit 1; }
+pdcli api GET /api/v1/users/me >/dev/null 2>&1 || { echo "Not authenticated — run 'pdcli auth login' or set PDCLI_* env vars."; exit 1; }
+
+# Read `.data.id` from a raw `pdcli api` JSON response on stdin.
+id() { node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(String(JSON.parse(s).data.id)))'; }
+
+echo "Creating the 'pdcli demo' pipeline…"
+PID=$(pdcli api POST /api/v1/pipelines --body '{"name":"pdcli demo"}' | id)
+
+echo "Creating stages…"
+S1=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Qualified\",\"pipeline_id\":$PID,\"deal_probability\":20}" | id)
+S2=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Contact\",\"pipeline_id\":$PID,\"deal_probability\":40}" | id)
+S3=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Proposal\",\"pipeline_id\":$PID,\"deal_probability\":60}" | id)
+S4=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Negotiation\",\"pipeline_id\":$PID,\"deal_probability\":80}" | id)
+
+# title|value|stage — per-stage totals: 142k / 98.5k / 76.2k / 51k
+deal() {
+  pdcli api POST /api/v2/deals \
+    --body "{\"title\":\"$1\",\"value\":$2,\"currency\":\"EUR\",\"pipeline_id\":$PID,\"stage_id\":$3}" >/dev/null
+}
+
+echo "Creating deals…"
+deal "Initech onboarding"  60000 "$S1"
+deal "Umbrella pilot"      50000 "$S1"
+deal "Soylent trial"       32000 "$S1"
+deal "Hooli migration"     40000 "$S2"
+deal "Stark upgrade"       38500 "$S2"
+deal "Wayne add-on"        20000 "$S2"
+deal "Acme renewal"        50000 "$S3"
+deal "Globex expansion"    26200 "$S3"
+deal "Wonka enterprise"    30000 "$S4"
+deal "Cyberdyne seats"     21000 "$S4"
+
+# A long-stalled deal (old expected close, no activity) → stale-deal / next-step findings.
+pdcli api POST /api/v2/deals \
+  --body "{\"title\":\"Vandelay (stalled)\",\"value\":15000,\"currency\":\"EUR\",\"pipeline_id\":$PID,\"stage_id\":$S1,\"expected_close_date\":\"2024-01-01\"}" >/dev/null
+
+# Two persons sharing an email → duplicate-persons finding.
+echo "Creating a duplicate person for the audit scene…"
+for _ in 1 2; do
+  pdcli api POST /api/v2/persons \
+    --body '{"name":"Dana Demo","emails":[{"value":"dana@demo.example","primary":true}]}' >/dev/null
+done
+
+# Point the recording at the new pipeline.
+sed -i '' -E "s/--pipeline [0-9]+/--pipeline $PID/g" docs/demo.tape
+
+echo
+echo "Done. Demo pipeline id = $PID (docs/demo.tape updated)."
+echo "Record it:  npm run docs:demo"
+echo "Clean up later:  pdcli api DELETE /api/v1/pipelines/$PID  (deals go with it)"