README & onboarding

Summary

This skill enforces executability for the repo homepage and onboarding docs: pinned versions, copy-pasteable commands, env var tables, and an FAQ on one screen; security uses placeholder examples only—real secrets go through internal channels. The ladder goes from “can clone” to “can change one line and pass CI,” shared by agents and humans.

Onboarding ladder

Time-box steps so the README is not slogans without a next action.

1. Step 0 (same day): Clone, align language and package manager versions with docs, read “Requirements” and “Quick start,” and run them end to end.
2. Step 1 (same day): Set up sample .env, run tests or minimal smoke; capture the first local error and add or match an FAQ entry.
3. Step 2 (this week): Pick a small task (e.g. good-first-issue), complete PR and CI; learn on-call / escalation paths (optional).

Complete README template with all required sections (copy directly):

# project-name

> One-line description: what this project solves and who it's for.

[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](...)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Table of Contents
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [Environment Variables](#environment-variables)
- [Development Guide](#development-guide)
- [FAQ](#faq)
- [Contributing](#contributing)

## Requirements
| Tool | Version | Notes |
|------|---------|-------|
| Node.js | >=20.0.0 | Use version in `.nvmrc` |
| pnpm | >=9.0.0 | `corepack enable && corepack prepare pnpm@9` |
| Docker | >=24.0 | Local dependency services |
| PostgreSQL | 15 (via Docker) | No local install needed |

## Quick Start
(see Local Setup section below)

## Architecture Overview
[Architecture diagram](./docs/architecture.md) | [ADR list](./docs/adr/) | [API docs](./docs/api.md)

Key differences between local and production:
- Database: local uses Docker, production uses RDS
- Email: local uses Mailhog (localhost:8025), production uses SES
- Payments: local uses Stripe test mode, requires test key

Doc output flow

Recommended order for an agent from repo metadata to a shippable README / onboarding page.

Complete local setup steps, each with command and verification:

# Step 1: Clone and enter directory
git clone https://github.com/org/project-name.git
cd project-name

# Step 2: Check Node.js version (align with .nvmrc)
node --version          # Expected: v20.x.x
# If version mismatch:
nvm use                 # Auto-reads .nvmrc
# macOS/Linux: brew install nvm
# Windows: use nvm-windows: https://github.com/coreybutler/nvm-windows

# Step 3: Install dependencies
corepack enable
pnpm install
# Verify: should see "node_modules/.pnpm" directory, no errors

# Step 4: Copy and configure environment variables
cp .env.example .env
# Edit .env, fill in required fields (see env var table)
# Required: DATABASE_URL, JWT_SECRET (any string for dev)
# Optional: STRIPE_SECRET_KEY (skip payment features during dev)

# Step 5: Start local dependency services (Docker)
docker compose up -d postgres redis mailhog
# Verify:
docker compose ps       # Should see postgres/redis/mailhog as "Up"

# Step 6: Run database migrations
pnpm db:migrate
# Verify: should output "All migrations completed successfully"
# On failure: check DATABASE_URL points to local Docker
#   (default: postgresql://postgres:postgres@localhost:5432/app_dev)

# Step 7: Start dev server
pnpm dev
# Verify: open http://localhost:3000, should see homepage
# API docs: http://localhost:3000/api-docs

# Step 8: Run tests to confirm environment is OK
pnpm test               # Unit tests (~30s)
pnpm test:integration   # Integration tests (needs Docker services, ~2min)

Recommended agent flow from repo metadata to a shippable README / onboarding page:

[ Scan repo: language version, script entrypoints, CI, directory roles ]
                    │
                    ▼
         [ Blurb / requirements / quick start (copy-paste commands) ]
                    │
                    ▼
      [ Env table: name · purpose · example placeholder (no real secrets) ]
                    │
                    ▼
    [ FAQ: common failures + platform differences (Win / macOS / Linux) ]
                    │
                    ▼
 [ Day-one tasks + cross-links to CHANGELOG, runbooks, architecture ]

README essentials

## FAQ

### Q: `pnpm install` fails with "EACCES: permission denied"
**Symptom**: Permission error during install on macOS/Linux
**Cause**: npm global directory permissions issue
**Solution**:
```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

### Q: Database connection fails "ECONNREFUSED 127.0.0.1:5432"
**Symptom**: `pnpm dev` startup reports DB connection error
**Cause**: Docker service not started, or DATABASE_URL misconfigured
**Solution**:
```bash
# Check Docker service status
docker compose ps
# If not running:
docker compose up -d postgres
# Check DATABASE_URL in .env
cat .env | grep DATABASE_URL
# Should be: postgresql://postgres:postgres@localhost:5432/app_dev
```

### Q: Windows: `pnpm dev` reports "cross-env is not recognized"
**Symptom**: Windows PowerShell fails to run scripts
**Solution**:
```powershell
# Use Git Bash instead of PowerShell
# Or install cross-env:
pnpm add -D cross-env
# .nvmrc requires nvm-windows support on Windows
```

### Q: Tests fail "Cannot find module '@/components/...'"
**Symptom**: Path alias resolution failure
**Solution**: Confirm `tsconfig.json` paths match `vitest.config.ts` alias

## Contributing

### Branch Naming Convention
feat/short-description    # New features
fix/issue-number-desc     # Bug fixes (link to issue number)
docs/update-api-readme    # Documentation updates
refactor/extract-service  # Refactoring
chore/upgrade-deps        # Dependency/build changes

# Examples:
git checkout -b feat/user-avatar-upload
git checkout -b fix/1234-login-redirect-loop

### Commit Convention (Conventional Commits)
feat: add user avatar upload endpoint
fix(auth): resolve redirect loop on OAuth callback (#1234)
docs: update local setup for Windows
refactor(payment): extract charge logic to service class
chore: upgrade Node.js to v20.11.0

### PR Flow
1. Branch from main, keep branches short-lived (<1 week)
2. PR title follows Conventional Commits format
3. Must pass all CI checks (lint + test + build)
4. At least 1 reviewer approval (security-related code needs 2)
5. Merge method: Squash and merge (keeps main history clean)
6. Delete feature branch after merge

### Local CI Check (run before committing)
pnpm lint          # ESLint + Prettier check
pnpm type-check    # TypeScript type check
pnpm test          # Unit tests
# Or run all at once:
pnpm pre-commit    # Equivalent to above three commands

New-hire checklist (checkboxes)

Checkbox state is stored in the browser for self-checking against the ladder.

• Verified runtime and package manager versions match CI / .tool-versions or docs.
• Ran “Quick start” from scratch with no skipped steps.
• Understood the env table: required vs optional and opened internal links for secrets.
• FAQ or troubleshooting covers my platform (or I filed an issue to add it).
• Claimed or planned a first small task and know review/release links.