# 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](https://asciinema.org/) cast in the README. The script below doubles as a manual sanity check after every major release.

## Recording the cast

```sh
# 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:

```md
[![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.