Ship Demo

Ship Demo

Make a project demo-ready: a seed that fills it with realistic, obviously-fake data, plus a script that walks someone through the product so it lands. Two deliverables that depend on each other — the script clicks through the records the seed creates, so a demo looks the same every run and never lands on an empty screen.

The point is a told story, not a feature dump. A handful of complete, wired-together records (a real-looking project with its tasks, files, money, and people) beats ten thousand random rows.

Part of the ship pack

ship-demo            → seed data + live-demo script        ← you are here
user-guide-builder   → the written guide the demo mirrors
shipping-log         → "what's new" the demo can show off
screenshot-capture   → can shoot the seeded screens for docs
logo-pack            → the brand the script + page are themed with
        all themed by docs/brand.json · versioned by docs/VERSION

Outputs go under the project's docs/. After seeding, offer to run screenshot-capture against the freshly-seeded app (the demo data makes for great doc screenshots), and user-guide-builder so the guide and the demo describe the same flows.

Workflow

1. Discover first — never seed blind. From the repo root, run the bundled scanner:

   node <skill-dir>/scripts/discover-model.mjs --json
   

   It reports: the ORM/data layer, schema files, model/table names, any existing seed script, prior demo docs (docs/demo/script.md, docs/DEMO-LOGINS.md), docs/brand.json, docs/VERSION, the package manager, and detected db:* scripts. Read it before doing anything.

   • If it finds an existing seed, extend/match it — do not create a parallel one.
   • If it finds prior demo docs, update them in place; preserve the established logins/story.
   • If the layer is unknown, ask where the model lives and how the app persists data. Do not guess — a wrong seed against a real DB is worse than none.

2. Read the real schema. Discovery gives names; open the actual schema files it listed for columns, required fields, enums, and foreign keys. Pick the adapter and the idempotency strategy from references/seed-adapters.md (Drizzle / Prisma / SQL+Supabase / TypeORM / Sequelize / Mongoose / API-only / unknown).

3. Design the dataset (depth over breadth). Plan a story, not a row dump:

   • 2–3 hero records fully populated end to end (the ones the demo clicks through).
   • 1 empty/new record to demo the create-flow and empty states live.
   • 1 edge record in a tricky state (overdue, rejected, partially paid) to show the product handling reality.
   • Enough breadth behind them (a populated list, users with distinct roles) that lists and dashboards aren't barren. Wire records together so navigation and links work.

4. Write the seed — idempotent and namespaced. Use the deterministic, dependency-free scripts/fake.mjs for all values (stable ids, @example.test emails, (555) phones — so data is reproducible AND obviously fake). The seed MUST:

   • Upsert by a stable natural key (never blind insert) so re-running changes nothing.
   • Scope to a demo namespace (a demo company/tenant, an is_demo flag, or the @example.test domain) and only ever touch that namespace.
   • Reuse the project's own db client/config, run in dependency order, ideally in one transaction. Add a --reset path that clears only the demo namespace.
   • Add a runnable entry point (e.g. a seed:demo package script) and capture logins in docs/DEMO-LOGINS.md (demo password or env var — never a real credential).

5. Run it (twice). Execute the seed, then run it again. Row counts must match — that proves idempotency. Fix any duplication before moving on. If you can't reach the DB, say so and hand the user the exact command.

6. Write the demo script. Following references/script-template.md (sequencing, voice, the exact markdown contract), write docs/demo/script.md: a hook → core loop → wow moment → live-create → value-close walkthrough, each step mapped to a real seeded record, with Go to / Say / Show / Reset lines and an operator's appendix (accounts, reset command, failure recovery, timing).

7. Render the presenter page.

   node <skill-dir>/scripts/render-demo.mjs   # docs/demo/script.md → docs/demo/script.html
   

   Self-contained, keyboard-navigable, themed from docs/brand.json (default slate-blue, never purple; no backdrop-filter / no feTurbulence). Print-to-PDF gives a handout.

8. Report honestly. List what was seeded (counts per entity), the logins, the reset command, and the two output paths. Flag anything you stubbed, any field you guessed, and any feature in the script that is staged rather than shipped.

Quality bar

• Obviously fake, zero real PII. Every value comes from the fictional pools in fake.mjs (@example.test, 555 numbers, fictional streets). Never scrape, copy, or invent a real person's name, email, address, or a real customer's data into the seed. If the repo already has demo data, reuse its conventions — don't introduce a second, conflicting fake-identity set.
• Idempotent or it's broken. Run-twice ⇒ identical state. A seed that duplicates on re-run fails this bar.
• A story, not noise. Records connect; the dataset reads like one real account using the product, with deliberate happy-path AND edge cases — not lorem-ipsum sprinkled across tables.
• Script is presenter-ready. Someone who has never seen the product can read it aloud and give the demo. Every step points at a record the seed actually created.
• Honest. Staged/coming-soon features are labeled as such in the script. The report names what was guessed or stubbed. No claim that un-run seeds or un-shipped features work.
• Evidence-based. The dataset and script come from the real schema and real features you read — not a generic template. If you couldn't verify the persistence layer, you stopped and asked rather than shipping a plausible-but-wrong seed.

Cross-project notes

Nothing here is hardcoded to one app. discover-model.mjs and fake.mjs are generic; seed-adapters.md covers the common ORMs and a fallback for unknown layers. External tools are referenced via adapters (the project's own db client, its db scripts, or its API/MCP) and never assumed installed — if a layer can't be reached, the skill asks instead of fabricating.

Bundled contents

• scripts/discover-model.mjs — bounded, read-only scanner: ORM, schema files, models, existing seed/demo work, brand/version, db scripts. Run it first, JSON or human output.
• scripts/fake.mjs — deterministic, dependency-free fake-data helpers (stable ids, fictional people/companies/addresses, money in cents, date offsets). Import it into the seed; it has a node fake.mjs <seed> self-test.
• scripts/render-demo.mjs — renders docs/demo/script.md → a themed, self-contained, keyboard-navigable presenter HTML page.
• references/seed-adapters.md — per-ORM read + idempotent-upsert playbook and the depth-over-breadth dataset guidance.
• references/script-template.md — demo-script sequencing, voice, the markdown contract render-demo.mjs consumes, and a full worked input→output example.