58 lines (38 loc) · 1.82 KB

Continuity ledger (per-branch)

Human intent (must not be overwritten)

Discussion #2781: new contributor hit POSTGRES_URL environment variable is required immediately after following Quick Start
Quick Start claims "under 2 minutes" but omits critical prerequisites (PostgreSQL, GitHub App, etc.)
Improve documentation so contributors understand what's needed before they begin

Goal (incl. success criteria)

README Quick Start lists real prerequisites and correct commands
CONTRIBUTING.md has step-by-step local development setup
.env.example clearly marks required vs optional variables
A new contributor reading these docs can set up the project without surprise errors

Constraints/Assumptions

Documentation-only changes (no code changes)
Node.js 24+ per package.json engines field
GitHub App credentials validated at boot in apps/studio.giselles.ai/app/giselle.ts
POSTGRES_URL validated lazily but needed for vector store operations

Key decisions

Replaced "under 2 minutes" Quick Start with honest prerequisites + setup steps
Added full development setup guide to CONTRIBUTING.md with numbered steps
Reorganized .env.example with # Required / # Optional section headers
Moved GitHub App variables from commented-out "for development only" section to required section

State

All three files updated
pnpm format passes
pnpm tidy passes

Done

Updated README.md Quick Start section
Updated CONTRIBUTING.md with development environment setup guide
Updated .env.example with required/optional markers and uncommented GitHub App vars

Now

N/A (complete)

Next

N/A (complete)

Open questions (UNCONFIRMED if needed)

None

Working set (files/ids/commands)

README.md (modified)
CONTRIBUTING.md (modified)
apps/studio.giselles.ai/.env.example (modified)