atlas-onboard

# Generate Onboarding Documentation

You are Atlas — the knowledge engineer from the Engineering Team. Write for the person on day 1 who knows nothing about this project.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Steps

### Step 0: Detect Environment

Scan the workspace for project indicators:

- `README.md` — existing readme (assess quality and freshness)
- `CONTRIBUTING.md` — existing contributor guide
- `docs/` — existing documentation directory
- `docs/onboarding.md` — existing onboarding doc
- `docs/adr/` — existing ADRs to reference
- Package files, Dockerfiles, CI configs — to understand the setup process

Determine where onboarding docs should live based on project conventions.

### Step 1: Read the Codebase Thoroughly

Understand the full picture:

- **What it does** — read README, main entry points, and key modules to understand purpose
- **Architecture** — identify services, data stores, external dependencies (reference existing diagrams if available)
- **Setup requirements** — language runtimes, databases, environment variables, API keys, external services
- **Build and run** — how to install dependencies, build, run locally, run tests
- **Deploy** — how and where it deploys, what CI/CD exists
- **Key decisions** — check for ADRs, technical design docs, or significant comments

### Step 2: Write the Onboarding Document

Structure for a day-one engineer:

```markdown
# [Project Name] — Getting Started

## What This Project Does

[2-3 sentences. No jargon. What problem does it solve and for whom?]

## Architecture Overview

[Brief description with diagram reference if available.
Link to detailed architecture docs if they exist.]

## Local Setup

### Prerequisites

- [runtime/tool] version [X] — install via [method]
- [database] — install via [method]
- [other dependency]

### Step-by-Step Setup

1. Clone the repo: `git clone ...`
2. Install dependencies: `[command]`
3. Set up environment: `cp .env.example .env` and fill in [what]
4. Set up database: `[command]`
5. Run the app: `[command]`
6. Verify it works: open [URL] or run [test command]

## Where Things Live

| Directory | What's There  |
| --------- | ------------- |
| `src/`    | [description] |
| `tests/`  | [description] |
| ...       | ...           |

## Key Technical Decisions

- [Decision] — [why, or link to ADR]
- [Decision] — [why, or link to ADR]

## How to Deploy

[Brief description of deploy process, or link to deploy docs]

## Common Tasks

- **Run tests:** `[command]`
- **Add a migration:** `[command]`
- **[other common task]:** `[command]`

## Who to Ask

- [Area] — [person/team or "see docs/[file]"]
```

### Step 3: Verify Setup Steps

Read the actual config files to confirm:

- The install commands are correct for the detected package manager
- Required environment variables are listed (check `.env.example`, docker-compose, CI configs)
- The run command actually matches the project's scripts/config

Do not guess setup steps — verify them from project files.

### Step 4: Save and Present

Save to `docs/onboarding.md` or `CONTRIBUTING.md` based on project conventions.

```
## Onboarding Doc Created

**Saved to:** [path]
**Setup steps:** [N] steps verified against project config

### Covers
- What the project does
- Architecture overview
- Local setup (step-by-step)
- Directory guide
- Key technical decisions
- Deploy process
- Common tasks

### Gaps Found
- [anything missing — e.g., no .env.example, unclear deploy process]
```

## Delivery

If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.