# AgendaPro: local setup and failure recovery

## Recommended install

Use the checked-in lockfile and a project-local npm cache:

```text
npm run setup
npm run dev
```

On PowerShell machines where `npm.ps1` is blocked by execution policy, use `npm.cmd`:

```text
npm.cmd run setup
npm.cmd run dev
```

The setup script uses `npm ci`; it does not mutate dependency versions. The local cache is ignored by Git and avoids failures caused by an unwritable global npm cache.

## What was audited

- `SEC_E_NO_CREDENTIALS` during clone: Git was using the Windows Schannel TLS backend and the host could not acquire TLS credentials. This is a machine-level Git/TLS issue, not an application error. Retry the clone with `git -c http.sslBackend=openssl clone <url>`.
- `npm.ps1` execution-policy error: PowerShell blocked the npm wrapper. `npm.cmd` is the same npm installation without the blocked PowerShell wrapper.
- npm `EPERM` in `AppData\Local\npm-cache`: the global cache was not writable. `.npmrc` and `scripts/setup.mjs` route the cache to `.cache/npm` inside the project.
- `tsx` `uv_os_get_passwd`/`os.userInfo()` error: the host returned an OS error while tsx selected its temporary directory. `scripts/run-tsx.mjs` keeps the native call when it works and supplies a safe username fallback when it fails.
- Vite/esbuild config loading: the original config used `__dirname` in an ESM project. `vite.config.ts` now resolves `src` from `import.meta.url`, binds the dev server deterministically to `127.0.0.1`, supports `VITE_PORT`, and fails clearly when the port is already occupied.
- Git `dubious ownership`: some managed workspaces are created by a different Windows identity. If needed, authorize only this checkout with `git config --global --add safe.directory <absolute-project-path>`.

## Preflight and recovery

The project validates Node.js >= 22.5 and `node:sqlite` before development, build, and production start. If a port is busy, inspect it with:

```text
netstat -ano | findstr :3000
netstat -ano | findstr :5173
```

Change ports without editing source:

```text
PORT=3001 VITE_PORT=5174 API_URL=http://127.0.0.1:3001 npm run dev
```

PowerShell equivalent:

```text
$env:PORT='3001'; $env:VITE_PORT='5174'; $env:API_URL='http://127.0.0.1:3001'; npm.cmd run dev
```