Onboarding Walkthrough (90 seconds)

A scripted demo that takes a fresh clone to a running dev server with a logged-in admin in 90 seconds, recorded once and embedded as an asciinema cast in the README. The script below doubles as a manual sanity check after every major release.

Recording the cast

# 1. Install asciinema (one-time)
brew install asciinema   # or: pipx install asciinema

# 2. Start a clean recording in a fresh terminal session
asciinema rec docs/assets/onboarding.cast \
  --title "Boilerplate onboarding: clone to logged-in admin in 90s" \
  --command 'bash docs/scripts/onboarding-walkthrough.sh'

# 3. Upload (optional, for embedding)
asciinema upload docs/assets/onboarding.cast

Cast files are tracked in git as plain JSON; binary terminal output is not committed.

The 90-second script

The recording follows this exact sequence so the timings match the README claim:

t (s)	Action	Expected output
0-5	`pnpm install` (assumes a warm pnpm cache; on a cold cache add ~60s)	`Done in 5s`
5-10	`cp .env.example .env` + open `.env` and set `SESSION_SECRET`, `CRYPTO_SECRET`, `DATABASE_URL`	three new key/value pairs
10-30	`pnpm exec prisma migrate dev --skip-seed`	"All migrations have been successfully applied"
30-45	`SEED_DEMO_DATA=true pnpm seed`	"Seed completed"
45-50	`pnpm run permissions:sync`	"Role permissions in sync"
50-55	`pnpm dev` (background)	"Local: http://localhost:3000"
55-70	Open `http://app.localhost:3000` in browser; login as `admin@email.com` / `password`	tenant dashboard
70-90	Tour: tenant switcher, settings, create a row, observe i18n DE/EN switch	feature breadth visible

Speaking outline (for a screen-cast voiceover)

"This is the ToolCTRL boilerplate. One command installs dependencies, one applies migrations, one seeds demo data. Sixty seconds later we have a multi-tenant SaaS shell with two demo tenants, two demo users, full i18n in German and English, a built-in audit log, and the admin surface on a separate host. The whole thing is RR7-server-rendered, with Pino structured logging, a hardened Docker stack that drops to non-root, an SBOM in every image, and 30+ verify gates protecting the contract you fork from."

Embedding in README

The README's "Installation" section already links to this walkthrough. After uploading the cast, add the asciinema badge:

[![asciicast](https://asciinema.org/a/<id>.svg)](https://asciinema.org/a/<id>)

placed between sections 4 (env setup) and 5 (database setup).

Failure modes the walkthrough also exposes

If any of the following surface during the recording, fix them before pushing the cast — the walkthrough is also a release health check:

pnpm install takes >2 minutes on warm cache → lockfile bloat
prisma migrate dev fails → missing shadow database privilege
pnpm seed fails → SEED_DEMO_DATA contract regression
Login flow does not land on tenant dashboard → tenant-context regression
DE/EN switch leaves untranslated strings → i18n parity drift

When the recording is clean, the boilerplate is genuinely shippable.

3.1 KiB Raw Blame History