# What the doctor.mjs Onboarding Check Verifies in Career-Ops Setup

> Discover what the doctor.mjs onboarding check verifies for your career-ops setup. Ensure Node.js, Playwright, dependencies, user files, fonts, and directories are ready for pipeline execution.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-06-10

---

**The `doctor.mjs` onboarding check validates that Node.js ≥18, Playwright Chromium, project dependencies, four required user-layer files, font assets, and writable directories are all present before the Career-Ops pipeline can execute.**

The `doctor.mjs` script serves as the deterministic setup validator for the `santifer/career-ops` repository. When executed, it runs a comprehensive checklist that guarantees both the runtime environment and personal data prerequisites required for the first-run experience are satisfied. The `main()` function at lines 60‑99 orchestrates the entire validation sequence, assembling the individual checks and formatting the output with green ticks for passing checks and red crosses for failures.

## Runtime Environment Validation

The script begins by verifying that the local machine can actually execute the Career-Ops automation suite.

### Node.js Version Requirement

In `doctor.mjs`, the `checkNodeVersion()` function (lines 25‑33) inspects `process.versions.node` to ensure Node.js version 18 or higher is installed. This prevents runtime errors from incompatible JavaScript features.

### Dependency Installation Status

The `checkDependencies()` function (lines 37‑45) validates that the `node_modules` directory exists, confirming that `npm install` has been executed. If this check fails, the script outputs the fix hint: "Run: npm install".

### Playwright Chromium Binary

Because Career-Ops relies on browser automation for certain tasks, `checkPlaywright()` (lines 48‑66) verifies that Playwright is installed and that its Chromium binary is actually present on the system, not just listed in [`package.json`](https://github.com/santifer/career-ops/blob/main/package.json).

## User-Layer Prerequisites

Beyond infrastructure, the script validates the *personal* files that make the system usable for a specific user. These requirements are also documented in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md), which mirrors the same four prerequisites for human reference.

### Required Personal Data Files

The `USER_LAYER_PREREQS` array (lines 73‑100) defines four files that must exist in the repository root:

- [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) – Your curriculum vitae in markdown format
- [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) – Personal configuration (see [`config/profile.example.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml) for a template)
- [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) – Mode-specific profile overrides (template available at [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md))
- [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml) – Job portal definitions (template at [`templates/portals.example.yml`](https://github.com/santifer/career-ops/blob/main/templates/portals.example.yml))

If any of these are missing, `doctor.mjs` exits with a non-zero status and provides specific copy commands to create them from the example templates.

## Asset and Directory Verification

The validation extends to runtime assets and writable storage locations required for PDF generation and data persistence.

### Font Assets for PDF Generation

The `checkFonts()` function (lines 15‑41) ensures the `fonts/` directory exists and is not empty. Career-Ops uses these fonts when generating PDF resumes, making this a critical dependency for output generation.

### Auto-Created Working Directories

The `checkAutoDir()` function (lines 43‑58) automatically creates three directories if they are missing: `data/`, `output/`, and `reports/`. These are invoked at lines 70‑73 to ensure subsequent scripts have writable locations for storing scraped data, generated PDFs, and analytics reports.

## Programmatic Onboarding State

For automation and agent integration, `doctor.mjs` exposes a machine-readable interface.

The `onboardingState()` function (lines 102‑111) returns a JSON object with the structure `{ onboardingNeeded: bool, missing: [] }`, indicating whether the setup is complete and listing any missing prerequisites.

When invoked with the `--json` flag (handled at lines 112‑119), the script suppresses the human-readable output and prints only this JSON structure, enabling CI pipelines and AI agents to react programmatically to the validation results.

## Running the Validation Script

Execute the onboarding check from the repository root using npm:

```bash

# Human-readable output with green ticks or red crosses

npm run doctor

```

For machine-readable output suitable for scripting:

```bash
node doctor.mjs --json

```

Example output:

```json
{
  "onboardingNeeded": true,
  "missing": [
    "cv.md",
    "config/profile.yml",
    "modes/_profile.md",
    "portals.yml"
  ]
}

```

To validate a different directory (useful for testing fresh installations):

```bash
node doctor.mjs --json --target /tmp/empty-career-ops

```

## Summary

The `doctor.mjs` onboarding check guarantees four critical conditions before allowing Career-Ops execution:

- **Runtime readiness**: Node.js ≥18 and Playwright Chromium are installed and functional
- **Dependency completeness**: All npm packages are installed in `node_modules`
- **Personal data layer**: The four user-layer files ([`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md), [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), [`portals.yml`](https://github.com/santifer/career-ops/blob/main/portals.yml)) are present
- **Runtime assets**: The `fonts/` directory contains required assets, and `data/`, `output/`, and `reports/` directories exist for file operations

If validation fails, the script provides specific fix hints, such as copying templates from [`config/profile.example.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml) or running `npm install`.

## Frequently Asked Questions

### What does doctor.mjs do if it finds missing prerequisites?

The script exits with a non-zero status code and prints a red cross for each failed check alongside a specific fix hint. For example, if [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) is missing, it will suggest copying from [`config/profile.example.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml), ensuring users can resolve issues immediately without consulting documentation.

### Can doctor.mjs validate a Career-Ops installation in a different directory?

Yes. Use the `--target` flag to point the script at an arbitrary directory. This is particularly useful for testing or when managing multiple Career-Ops profiles. Example: `node doctor.mjs --json --target /path/to/another/career-ops`.

### Where are the templates for the required user-layer files?

The repository provides templates for all four required files: [`config/profile.example.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml) for your profile configuration, [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) for mode-specific overrides, and [`templates/portals.example.yml`](https://github.com/santifer/career-ops/blob/main/templates/portals.example.yml) for job portal definitions. The `doctor.mjs` script references these paths in its error messages when it detects missing files.

### How does doctor.mjs support CI/CD pipelines?

The `--json` flag produces machine-readable output that returns a structured object from `onboardingState()`. This allows CI scripts to parse the validation results programmatically and determine whether the environment is ready for subsequent Career-Ops automation steps, making it ideal for pre-deployment checks.