Codebase Onboarding Guide

---
description: Generate an interactive HTML onboarding guide for the repository
allowed-tools: Bash, Read, Write, Glob, Grep
context:
  - type: command
    command: "cat package.json 2>/dev/null || cat Cargo.toml 2>/dev/null || cat go.mod 2>/dev/null"
---

# Codebase Onboarding Guide

Generate a comprehensive, interactive HTML onboarding guide that helps a new developer understand the repository from zero to productive. This is not just documentation — it is a guided walkthrough with a logical reading order.

## Steps

1. **Identify the tech stack.** From the context output and project files, determine:
   - Language(s) and runtime version requirements
   - Framework(s) (Next.js, Express, Django, Rails, etc.)
   - Package manager (npm, yarn, pnpm, cargo, etc.)
   - Database and ORM (if any)
   - Test framework
   - CI/CD platform (check `.github/workflows`, `Jenkinsfile`, `.gitlab-ci.yml`)

2. **Map the directory structure.** Read the top-level directory layout and one level deep under `src/` (or equivalent). Categorize each directory:
   - Entry points (where execution starts)
   - Business logic (core domain code)
   - Infrastructure (database, auth, external integrations)
   - UI (components, pages, styles)
   - Configuration (build tools, linting, environment)
   - Tests

3. **Trace the main flow.** Starting from the application entry point:
   - For web apps: trace a request from route to response
   - For CLIs: trace from argument parsing to output
   - For libraries: trace the main public API usage
   Read the key files in this flow and document the chain.

4. **Identify conventions and patterns.** By reading multiple files, detect:
   - Naming conventions (file names, variable names, CSS classes)
   - Common patterns (repository pattern, service layer, hooks, etc.)
   - Error handling approach
   - State management strategy
   - How env vars are managed

5. **Find the "how to add X" patterns.** Identify the steps to:
   - Add a new API endpoint
   - Add a new page/route
   - Add a new component
   - Add a new database table/model
   - Add a new test

6. **Generate the HTML guide.** Create `onboarding-guide.html` with:

   ### Layout
   - **Fixed sidebar** with navigation links to each section, collapsible subsections
   - **Main content area** with smooth scroll between sections
   - **Top bar** with project name and "Search" input that filters sidebar entries

   ### Sections
   1. **Quick Start** — clone, install, configure, run (with copy-paste shell commands)
   2. **Tech Stack Overview** — what technologies are used and why
   3. **Directory Map** — annotated tree structure with descriptions of each directory
   4. **Architecture Overview** — how the pieces fit together, data flow diagram (described textually or as ASCII art)
   5. **Request Lifecycle** — step-by-step trace of the main flow with syntax-highlighted code snippets from the actual codebase
   6. **Conventions & Patterns** — naming rules, common patterns, do's and don'ts
   7. **How To Add...** — step-by-step guides for common development tasks
   8. **Key Files to Read First** — a prioritized reading list of 5-10 files with explanations of why each matters
   9. **Glossary** — project-specific terms, abbreviations, and domain concepts

   ### Styling
   - Clean, modern typography (use system font stack)
   - Syntax highlighting for code snippets (include a lightweight JS highlighter like Prism from CDN)
   - Light/dark mode toggle
   - Print-friendly layout
   - Responsive design

7. **Open the guide.** Run `open onboarding-guide.html`.

## Rules

- Write for someone who is a competent developer but has never seen this codebase.
- Include actual code snippets from the repo — not generic examples.
- Be opinionated about reading order — do not just list files alphabetically.
- If the codebase has a CONTRIBUTING.md or ARCHITECTURE.md, incorporate that content rather than contradicting it.
- The HTML file must be fully self-contained (inline styles, CDN script links, no local dependencies).