Seed ah

Seed-ah!

Empty databases make every screenshot, demo, and dev session lie — and seeding with "test test test" rows lies differently. This skill seeds data that looks like production: real-shaped names in the right locale, timestamps that spread like history, distributions with heavy users and ghosts, images in the image fields — all fake, all wipeable, all documented in a manifest that tells you exactly who the demo users are.

The Prime Directive (family rule)

The schema is read, never assumed — and production is never touched. Every column seeded exists in evidence (migration/model/introspection, cited). The target database is verified and confirmed by the user before the first row is written. Every seeded row can be identified and wiped.

Hard safety rules

1. Production gate ⛔ — before seeding, resolve the actual connection (env/config, file:line), print host + database name + environment to the user, and require explicit confirmation. Names that smell like production (prod, a public host, a managed-DB hostname) require the user to type the database name back. When in doubt, refuse and suggest a local copy. The gate is checked TWICE: once here, and again at run time — immediately before executing, query the live connection for its own identity (SELECT DATABASE() / current_database() / PRAGMA database_list) and compare host + database name against what the user confirmed. Any mismatch = abort, zero rows written. If no user can respond (headless run), the gate cannot pass — write the scripts and stop; never execute a seed unattended.
2. Wipeable by construction — and proven, not promised — seeded rows are identifiable (a deterministic marker: known email domain like @demo.example, a demo_ slug prefix, or a seed-run tag column where one exists) and an unseed script ships alongside the seed script. Before mass seeding, the marker must match zero existing rows (query it — a marker that overlaps real data turns the wipe into a data-loss tool), and the wipe round-trip in Step 6 must pass on a one-row skeleton.
3. Demo passwords are demo — obviously fake, unique to this seed (never a real credential, never reused from anywhere), hashed through the app's OWN hasher (file:line of the hashing call/config). Policy- compliant so login actually works.
4. No real humans — no real names/emails/photos of actual people. Generated faces are avoided too (likeness risk); use initials-avatars or illustrations instead.

Progress checklist

Copy this into your response and check items off:

Seed-ah Progress:
- [ ] Step 1: Frame — target env confirmed ⛔, volume, locale, purpose
- [ ] Step 2: Schema census — Census Questions answered with evidence, FK graph, seed order
- [ ] Step 3: Realism plan — per-table shape, distributions, edge cases; Seed Brief confirmed
- [ ] Step 4: Seed scripts — framework-native, committed, idempotent, side effects muted or accepted
- [ ] Step 5: Images — generated for every image field, correct sizes
- [ ] Step 6: Run + verify — target re-checked ⛔, skeleton + wipe round-trip proven, then mass seed, demo logins tested
- [ ] Step 7: Manifest — what was seeded + demo accounts (user/pass/role)

Step 1 — Frame

Volume (S: enough for screenshots / M: realistic dev / L: pagination and performance testing), locale for the fake data (Thai names for a Thai product — locale mismatch screams "fake"), and purpose (feeding love-me-love-my-docs screenshots? a customer demo? dev fixtures?). Then run the production gate from the hard rules — nothing proceeds past this step without the confirmation.

If no database is reachable (connection fails, credentials missing), stop here: write the seed scripts and manifest template as deliverables, but execution cannot proceed — report the blocker and what's needed to resolve it (connection string, credentials, network access).

Step 2 — Schema census

Read the structure from evidence, per references/schema-census.md: migrations and ORM models first (they carry intent: enums, defaults, validation), live introspection to confirm (information_schema / SHOW CREATE TABLE / PRAGMA), FK relationships → a dependency graph that dictates seed order (parents before children), and every constraint that can reject a row (NOT NULL, UNIQUE, CHECK, enum values). Note which tables the app writes vs reference/lookup tables that may already be populated.

The census exists to answer the numbered Census Questions in that reference — constraints, FK order, what fires on insert, what already lives in the target — before a single row is invented. Every answer carries evidence (file:line or pasted introspection output). A question you cannot answer from evidence never becomes a guess: it becomes a named probe (insert one throwaway row inside a transaction, observe, roll back) or the table waits. The census is complete when every question is answered or probed — not when every file has been read.

Step 3 — Realism plan

Per table, decide what "production-like" means — rules in references/realism-guide.md: locale-correct fake identities, timestamps spread over months with plausible rhythms, power-law distributions (a few heavy users, a long tail, some zeros), statuses covering the whole enum including the ugly ones (cancelled, banned, pending), and deliberate edge cases (longest plausible name, unicode, empty optionals) — because demos eventually meet them.

Seed Brief Gate — before writing a single script, present a compact brief in chat: the target database (exactly as confirmed at the production gate), per-table row counts, the wipe marker, the demo-account roster (role + what each demos), and any side effects that will fire or be muted. 10–20 lines total; ask for confirmation once. Changing a row count here costs one message; changing it after the scripts and images exist costs a rewrite. If the user cannot respond, write the scripts anyway (files are reversible) — but execution stays behind the production gate, which never passes unattended.

Step 4 — Write the seed scripts

Use the framework's blessed mechanism — Laravel seeders/factories, Symfony Foundry, Prisma seed, Django fixtures/factory_boy, plain SQL as last resort — cited from the project's own conventions (file:line of an existing example if one exists). Scripts are committed (database/seeds/ or the stack's home), deterministic where possible (fixed random seed so re-runs produce the same demo world), and paired with the unseed script. Every insert-time side effect the census found (Census Question 4 — observers, signals, callbacks, queued jobs) is handled IN the script: muted with the framework's own switch (cite it) or left firing with a one-line justification. Silence is not handling.

Step 5 — Images and media

For every image/file column found in the census, produce real files at the sizes the app expects — options and rules in references/images-and-media.md: AI image generation when tooling is available, deterministic programmatic rendering (brand-colored covers, initials-avatars) as the always-works fallback. Never scraped/copyrighted images, never real people. Store them where the app actually serves media from (file:line of the storage config).

Step 6 — Run and verify

Re-check the target first (the run-time half of the production gate ⛔), then prove the pipeline before trusting it with volume — in this order:

1. Baseline — record pre-seed row counts per table, and query for rows already matching the wipe marker. That count must be zero; if it isn't (and the rows aren't a prior seed run per the manifest), pick a different marker before going on.
2. Walking skeleton — seed exactly ONE row per table through the real seeder (including one image landing in real storage), then check FK integrity and one demo login. The thinnest slice that exercises the whole pipeline.
3. Wipe round-trip — run the unseed script for real against the skeleton. Re-query the counts: every table must equal the baseline. A diff of zero is the proof that "wipeable" is true. Until this passes, mass seeding is forbidden — a wipe that fails on 1 row per table would have failed on thousands.
4. Mass seed — now run the full seed, and verify like it matters:
   • Row counts per table match the plan.
   • FK integrity: zero orphans (query it, don't assume it).
   • Log in as every demo account through the app's real auth (HTTP or the app's test client) — a demo account that can't log in is a seed failure, report it as such.
   • Spot-render: one page per major entity shows seeded data without errors.

Step 7 — The manifest

Write the summary per references/manifest-template.md to SEED_MANIFEST.md (repo root or docs/): per-table seeded counts and shape notes, the demo accounts table — username/email, password, role, what that account is good for demoing — image inventory, the exact re-seed and wipe commands, and the marker that identifies seeded rows. Warn in the file header: it contains demo credentials by design — keep it out of public repos unless the database is disposable.

End by reporting the manifest inline: what was seeded (counts), the demo accounts (user / pass / role), and the one-command re-seed and wipe.

When things go wrong

Situation	Response
Production gate fails (smells like prod)	Refuse; suggest local copy or explicit database name confirmation typed back by user
No database reachable	Write scripts and manifest template as deliverables; report blocker (connection, credentials, network) — execution cannot proceed
User cannot respond (headless run)	Write scripts (reversible) but never execute — production gate cannot pass unattended
Wipe marker matches existing rows	Pick different marker before seeding; a marker collision turns wipe into data-loss tool
Wipe round-trip fails on skeleton	Fix wipe script before mass seed — a wipe that fails on 1 row/table would fail on thousands
Demo account login fails after seed	Report as seed failure; check password hashing config (file:line) and policy compliance
Insert-time side effects discovered	Mute with framework's own switch (cite) or accept with one-line justification — silence is not handling