| name | local-development |
| description | Start, reuse, inspect, or browser-test local apps and services in this monorepo. Use for local service status, generated endpoint configuration, worktree ports, fake-user login, restarts, and logs. |
Local development
Read DEVELOPMENT.md for human setup and service procedures. Read ENVIRONMENT.md for the environment-variable inventory. Shared web environment mutations are governed by apps/web/AGENTS.md; do not use this skill for that workflow.
Start or reuse services
Before accessing local app or service endpoints, inspect this worktree's services:
pnpm dev:status --json
Reuse an active session and its reported ports. Do not start a competing stack.
dev:start cannot add services to an existing session. If the active session
does not include required services, stop it with pnpm dev:stop, then recreate
it with the complete needed group or named-service selection:
KILO_PORT_OFFSET=auto pnpm dev:start <needed-group-or-services>
When no session is active, start only the needed group or named services. If
generated local endpoint configuration is needed first, run the matching
selector, then start that same selection with the same automatic offset:
KILO_PORT_OFFSET=auto pnpm dev:env <needed-group-or-service>
KILO_PORT_OFFSET=auto pnpm dev:start <needed-group-or-service>
After startup or reuse, obtain actual ports from .dev-port, pnpm dev:status --json, or dev/logs/manifest.json. Never assume defaults. Open web at http://localhost:<reported-port>/.
A worktree on a port offset runs its own database container and starts empty. Run pnpm test:db for migrations, then seed the data the task needs. Read the connection string from this worktree's .env.local; never assume port 5432.
Run pnpm test:db before pnpm test in a worktree. It writes this worktree's database to apps/web/.env.test.local, which is the only file the Jest setup loads that can hold it. Without that file, Jest runs against port 5432 and drops a sibling worktree's test databases.
Fake login
Use:
http://localhost:<reported-port>/users/sign_in?fakeUser=<fake-email>&callbackPath=<path>
Always set callbackPath to destination page. Build <fake-email> as kilo-<username>-<time including seconds>@example.com, where username comes from home directory. For admin access, email must end in @admin.example.com. Wait for account-creation spinner to finish. Open admin panel from top-right account menu.
Service management
| Command or path | Use |
|---|
dev/logs/manifest.json | Static service and port snapshot written by dev:start. |
pnpm dev:status | Live service status and ports. |
pnpm dev:status --json | Machine-readable session, offset, service, port, status, and group data. |
pnpm dev:restart <service> | Restarts a running service. |
dev/logs/<service>.log | Service log file. |
Use tail -f dev/logs/<service>.log to follow a service log.
