feat(api): add local-dev seed command and document it

[cavidelizade]

Feature summary

A new go run ./cmd/api seed command populates a local database with a demo user, workspace, project, workflow states, and sample work items, so a fresh clone is explorable in one step instead of clicking through first-run setup.

Linked issues / discussion

Closes #24

User-facing behavior

From apps/api, a contributor runs:

go run ./cmd/api seed

It creates a demo user (demo@devlane.test / Demo1234!), a Demo Workspace, a Getting Started project with the standard five workflow states (one marked default), and five sample work items across those states/priorities. Signing in with those credentials shows a populated instance. Running it again prints "already exists — nothing to do" and changes nothing.

What changed

API (apps/api/)

• New cmd/api/seed.go with a seed subcommand (wired in main.go next to the existing admin subcommand). It reuses the real services (auth.SignUp, workspace/project/issue services, state store) so seeded data goes through the same paths as normal creation. Idempotent via a demo-user existence check; instance admin + general settings are only seeded when the instance isn't already set up.

Database

• No schema changes.

Docs

• Root README.md, CONTRIBUTING.md (Local development), and apps/api/README.md (Commands) now mention the seed as an alternative to manual first-run setup.

Why this design

Driving the existing services rather than raw inserts keeps the seed correct as the domain evolves (sequence IDs, memberships, default-state fallback, activity rows all happen for free) and avoids a parallel data-creation path that could drift. Idempotency makes it safe to re-run in a shared/long-lived dev DB.

Test plan

• go test ./cmd/api — TestSeedDevData_CreatesDemoAndIsIdempotent asserts the demo user/workspace/project, 5 states with exactly one default, 5 issues, and that a second run adds nothing
• Ran go run ./cmd/api seed against a live local DB: created the demo data; a second run was a clean no-op
• go vet / pre-commit green

AI assistance

• AI tools were used — tool(s): Claude Code (Claude Opus 4.8) — and AI-assisted commits include a Co-Authored-By: trailer

Checklist

• PR title follows Conventional Commits and is ≤ 100 chars
• New env vars documented (none added)
• Acceptance criteria from the linked issue are all met (seed added + local dev documented)

Summary by CodeRabbit

• New Features

  • Added a local seed command to create a demo account, workspace, project, workflow states, and sample work items.
  • Seeding is idempotent and avoids creating duplicate demo data.
  • Added an admin-grant command for assigning instance administrator access locally.

• Documentation

  • Updated local development guides with setup commands, seeded data details, and local-only demo credential guidance.

[coderabbitai]

Warning

Review limit reached

@cavidelizade, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 6 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 824bf828-b8a4-4216-af5c-bc18ec132ed9

📥 Commits

Reviewing files that changed from the base of the PR and between f3c5b43 and d9715fb.

📒 Files selected for processing (1)

• apps/api/cmd/api/seed.go

📝 Walkthrough

Walkthrough

The API now supports a seed command that creates demo local-development data, including an admin user, workspace, project, workflow states, and sample issues. Documentation describes the command, credentials, and idempotent behavior, with integration coverage for repeated execution.

Changes

Local development seeding

Layer / File(s)	Summary
Seed command entrypoint apps/api/cmd/api/main.go, apps/api/cmd/api/seed.go, apps/api/README.md, README.md, CONTRIBUTING.md	Adds the seed CLI flow and documents its local-development usage and demo credentials.
Instance and project seeding apps/api/cmd/api/seed.go	Creates demo instance data, workspace, project, and workflow states while returning early when the demo user already exists.
Sample work-item seeding and validation apps/api/cmd/api/seed.go, apps/api/cmd/api/seed_test.go	Creates sample issues and verifies seeded entities and idempotent repeated execution.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant API
  participant Database
  participant Services
  Developer->>API: run go run ./cmd/api seed
  API->>Database: initialize connection
  API->>Services: create demo user, workspace, project, states
  Services->>Database: persist demo data
  API->>Services: create sample issues
  Services->>Database: persist issues
  API-->>Developer: print seed summary and credentials

Loading

Suggested labels: documentation

Poem

A rabbit hops through fields of code,
And plants demo seeds along the road.
A workspace blooms, states align,
Five little issues sprout in time.
Run twice—no duplicates appear,
Local-only carrots, crisp and clear!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, Conventional Commits-compliant, and accurately reflects the new seed command plus docs.
Description check	✅ Passed	The description covers the summary, linked issue, behavior, implementation, design rationale, and test plan.
Linked Issues check	✅ Passed	The PR implements #24 by adding the local-dev seed command and documenting it in the requested docs.
Out of Scope Changes check	✅ Passed	The changes stay focused on the seed command, related documentation, and tests, with no clear unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/cmd/api/seed.go`:
- Around line 84-95: Update seedDevData to propagate store errors: at
apps/api/cmd/api/seed.go:61-68, return GetByEmail errors except
gorm.ErrRecordNotFound; at apps/api/cmd/api/seed.go:84-95, handle and return
errors from CountActive, Create, settings.Get, and settings.Upsert; at
apps/api/cmd/api/seed.go:131-136, return ListByProjectID errors instead of
leaving stateByName empty. Preserve successful and not-found handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 79501450-643b-40c1-8a97-c96ab9f1080d

📥 Commits

Reviewing files that changed from the base of the PR and between dc28bb0 and f3c5b43.

📒 Files selected for processing (6)

• CONTRIBUTING.md
• README.md
• apps/api/README.md
• apps/api/cmd/api/main.go
• apps/api/cmd/api/seed.go
• apps/api/cmd/api/seed_test.go

[cavidelizade]

@martian56 this one's green (build + lint) with no open review comments. Small one: adds an api seed command for local dev plus docs. Good to merge when you get a chance.

[cavidelizade]

@martian56 addressed the review note (seed now surfaces store errors instead of swallowing them). Green — good to merge.