Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,61 @@
|
||||
# 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
|
||||
[](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.
|
||||
Reference in new issue
Block a user