Onboarding Doc Generator

Generate a structured ONBOARDING.md for this codebase to help new developers get up to speed quickly.

Instructions

1. Gather codebase context:

   • Read CLAUDE.md, README.md if they exist
   • Read package.json, pyproject.toml, Cargo.toml, or go.mod (whichever exists)
   • List top-level directories with ls
   • Read the main entry point (e.g., src/index.ts, main.py, app/page.tsx, cmd/main.go)
   • Check .github/workflows/ for CI/CD setup
   • Check for any existing docs/ or adr/ directories

2. Identify:

   • Language(s) and framework(s)
   • Package manager (npm, pnpm, yarn, pip, cargo, go)
   • Database and ORM if present
   • Test framework and how to run tests
   • Deployment target (Vercel, Fly.io, Heroku, etc.)
   • Any non-obvious local setup requirements (env vars, external services, DB migrations)

3. Generate ONBOARDING.md with this exact structure:

# Onboarding Guide

## What This Is
[2–3 sentences: what the project does and who uses it]

## Architecture Overview
[How the major components fit together. Keep it to a paragraph or a simple
bullet list — just enough for a new dev to build a mental model.]

## Key Files and Directories

| Path | Purpose |
|------|---------|
| `src/` | [what lives here] |
| ... | ... |

## Local Setup

### Prerequisites
- [List tools and versions, e.g. Node.js 20+, Docker, PostgreSQL 15]

### Steps
```bash
git clone <repo-url>
cd <repo>
cp .env.example .env  # if applicable
[install command]
[start command]

Open http://localhost:3000 (or appropriate port).

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
...	...	...

Running Tests

[exact test command]

Common Gotchas

• [Things that trip up new developers — missing env vars, migration steps, port conflicts, etc.]

First PR Checklist

• Tests pass locally ([test command])
• No new linting errors ([lint command])
• Relevant docs updated if behavior changed
• PR description explains the why, not just the what

4. **Write the file** to the project root as `ONBOARDING.md`.

5. **After writing, ask:** "Anything missing or inaccurate? I can also add an Architecture Diagram section using ASCII art if that would help."