feat(dev-seed): improve local seed scripts

[jeanduplessis]

Summary

Adds a reusable local seed runner and development fixtures for app users, credits, and KiloClaw test data.

Why this change is needed

Local setup and debugging need repeatable seed commands that create realistic data without requiring manual database edits or production-like onboarding flows. The KiloClaw fixtures also need to preserve billing/data-model invariants so local debugging does not rely on impossible states.

How this is addressed

• Adds a pnpm dev:seed runner that discovers seed topics, supports scope:topic and scope topic invocation, and can emit clean JSON for scripts.
• Adds seed topics for creating local app users, adding credits, creating fake KiloClaw instances, and preparing inactive trial fixtures.
• Creates real Stripe test-mode customers for seeded app users so Stripe-touching local pages do not fail on placeholder customer IDs.
• Aligns fake KiloClaw paid subscriptions with the credit ledger by adding matching credit grants/deductions and spend counter updates.
• Retires prior fake KiloClaw instances instead of deleting canonical instance, subscription, and audit-history rows.
• Documents the dev/seed topic contract for future seed additions.

Human Verification

Completed in-session checks

• Reviewed branch changes against the KiloClaw billing, data model, and controller specs where relevant.
• Ran help-output smoke checks for:
  • pnpm -s dev:seed app:create-user --help
  • pnpm -s dev:seed kiloclaw:fake-instance --help
  • pnpm -s dev:seed app:add-credits --help

Reviewer Notes

Human Reviewer Flags

• dev/seed is intentionally outside the main TypeScript project checks and runs through tsx; dev/seed/AGENTS.md documents this workflow.
• Fake KiloClaw instances are DB-only fixtures. They do not create Durable Objects, containers, or provider resources.
• The KiloClaw fake-instance seed now preserves canonical history by retiring prior fake rows instead of hard-deleting them.

Code Reviewer Agent

Code Reviewer Notes

• Seeded user email normalization is mirrored locally in dev/seed/lib/email.ts to avoid importing from apps/web/src/... while matching production duplicate-detection behavior.
• Paid fake KiloClaw subscriptions insert credit transactions and update kilocode_users.microdollars_used in the same transaction as the subscription fixture.
• Prior fake subscriptions receive subscription change-log entries when replaced, preserving auditability for local lifecycle debugging.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (10 files)

• .gitignore
• dev/seed/AGENTS.md
• dev/seed/app/add-credits.ts
• dev/seed/app/create-user.ts
• dev/seed/index.ts
• dev/seed/kiloclaw-billing/inactive-trials.ts
• dev/seed/kiloclaw/fake-instance.ts
• dev/seed/lib/email.ts
• dev/seed/lib/preflight.ts
• dev/seed/lib/stripe.ts

---

_{Reviewed by gpt-5.5-20260423 · 1,954,146 tokens}