Goal
Make local setup and verification failures easier to diagnose so contributors can recover quickly.
Scope
setup.sh
scripts/verify_local_stack.py
README.md if setup instructions need to be updated
Background
The project already has a good local setup and verification story, but some install steps suppress output too aggressively. This makes failures harder to debug for first-time contributors.
Required changes
- Improve shell safety in
setup.sh (for example, stricter error handling)
- Make failed
pip install / npm install steps easier to diagnose
- Ensure setup output remains readable in the success path
- Review whether verification failure messages in
scripts/verify_local_stack.py can provide clearer next-step guidance
- Update README setup notes if behavior changes
Constraints
- Preserve the existing happy-path flow
- Do not remove the convenience of one-command setup and verification
- Keep the scripts suitable for local developer use
Acceptance criteria
- Setup failures expose enough detail for debugging without requiring script modification
- Verification failures clearly indicate which stage failed
- README remains consistent with the actual setup/verification behavior
Validation
- Run
./setup.sh in a clean environment or simulate dependency failure paths
- Run
./venv/bin/python scripts/verify_local_stack.py --start-api
- Confirm that failure output points to the relevant step and command
Goal
Make local setup and verification failures easier to diagnose so contributors can recover quickly.
Scope
setup.shscripts/verify_local_stack.pyREADME.mdif setup instructions need to be updatedBackground
The project already has a good local setup and verification story, but some install steps suppress output too aggressively. This makes failures harder to debug for first-time contributors.
Required changes
setup.sh(for example, stricter error handling)pip install/npm installsteps easier to diagnosescripts/verify_local_stack.pycan provide clearer next-step guidanceConstraints
Acceptance criteria
Validation
./setup.shin a clean environment or simulate dependency failure paths./venv/bin/python scripts/verify_local_stack.py --start-api