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

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.

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, 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 – Your curriculum vitae in markdown format
• config/profile.yml – Personal configuration (see config/profile.example.yml for a template)
• modes/_profile.md – Mode-specific profile overrides (template available at modes/_profile.template.md)
• portals.yml – Job portal definitions (template at 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:

# Human-readable output with green ticks or red crosses

npm run doctor

For machine-readable output suitable for scripting:

node doctor.mjs --json

Example output:

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

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

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, config/profile.yml, modes/_profile.md, 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 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 is missing, it will suggest copying from 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 for your profile configuration, modes/_profile.template.md for mode-specific overrides, and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}