Troubleshoot the local stack

Outcome

You can isolate the failing boundary, reproduce one normal and one failure path, and recover without destructive cleanup.

Prerequisites

Run commands from the repository root. Preserve the first failing output and git status; unrelated worktree changes belong to their owner.

Steps

1. Run pnpm bootstrap for version, dependency, PostgreSQL, migration, seed, and generated-client setup.
2. Run pnpm check to identify the first contract or integration gate that fails.
3. For database readiness, inspect the exact postgres Compose service before changing credentials.
4. For generated-client drift, run pnpm api:generate, inspect the diff, and fix the canonical Python contract rather than editing generated TypeScript.
5. For documentation reference drift, run pnpm --filter @lumen/docs generate:reference and inspect which backend truth changed.
6. For SSE failures, verify the API is reachable, authentication is present, and the last opaque cursor is retried unchanged.

Verify

Rerun the narrow failing command, then pnpm check. Confirm the original failure path now produces its documented rejection or recovery rather than disappearing from coverage.

Recover

Do not delete the database, artifact directory, lockfile, or build evidence as a first fix. If a local reset is eventually required in the disposable epoch, inspect and record the exact state first and use the repository's reviewed reset procedure when one exists.

Next task

Review the security boundaries.