Prove the local boundary before debugging the product.

These are source-development checks, not instructions for a supported installer. Keep real accounts disconnected while you diagnose a local run.

Baseline checks

Confirm the toolchain. Use Node 20 or newer and the repository’s pnpm workspace. Install dependencies with pnpm install.
Build before a broad dev run. A serial build avoids a documented local Turbo race on generated database declarations.
```
pnpm build --concurrency=1
```
Start only what you need. For a dashboard evaluation, the API and web app can be run individually after the build.
```
pnpm --filter @skytwin/api dev
pnpm --filter @skytwin/web dev
```

Database and fictional sample

Run migrations before seeding. The sample is a development fixture with fictional people and records, separate from the packaged read-only sample authority.

pnpm db:migrate
pnpm db:seed

If seeding fails because a table is missing, migrations did not finish. Re-run the migration command and verify its successful completion before starting another seed. Do not create tables manually.

Stale local build outputs

After rebasing, a package can have an old local dist/ directory even when its source export is correct. If TypeScript says a shared type is missing, rebuild that package and inspect the generated output:

rm -rf packages/shared-types/dist packages/shared-types/tsconfig.tsbuildinfo
pnpm --filter @skytwin/shared-types build
grep '<EXPORT_NAME>' packages/shared-types/dist/index.js

If a full build reports an API declaration mismatch that clearly exists in packages/db, use the serial build above. This local-worktree workaround does not weaken CI’s clean-install check.

Ports and services

The local API health endpoint is http://localhost:3100/api/health; the dashboard normally serves from http://localhost:3200. If a port is already occupied, stop the conflicting local process or use the documented development port overrides. Do not point a troubleshooting run at production data or a remote database.

Before reporting an issue

Include the exact command, the first error, your OS and Node version, and whether the fictional sample or a real account was involved. Remove tokens, cookies, database URLs, private records, and screenshots containing personal data. For release claims, compare the observation with the release guide and claim ledger.

Start guide · Operations · Contributing