Development setup

Fresh clone to local server

1. Install Node 22 (nvm use reads the repository .nvmrc). The supported range is recorded in the root package.json.

2. Clone the repository and select the intended branch. Normal feature work starts from staging.

3. Install exactly the committed dependencies:

   npm ci

4. Create a local configuration file without adding secrets to Git:

   cp .env.example .env

5. Obtain an approved non-production DATABASE_URL from the project owner. Never point local development or a seed command at production.

6. Start the server:

   npm run dev

   The expected startup signal is serving on port 5000; the dependency-free health check is GET /api/healthz.

7. Before opening a PR, run the focused test plus the normal static/build gates:

   npm test
   npm run check
   npm run build

Important limitation: schema bootstrap is not yet safe to automate

The repository currently has SQL migrations in three locations with duplicate sequence numbers. There is no approved migration runner, and npm run db:push is deliberately disabled. Do not hand-apply all SQL files from a fresh clone. See Migration Inventory for the collision register and the gated remediation path.

script/seed.ts is a legacy demo-data script. It is not part of the fresh-clone path, has no npm script, and must not be run against any shared or production database until it is redesigned under a separate schema/data-approved task.