local-development

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.