# Where to Store Your Canonical CV Markdown File: A Complete Guide to the career-ops Data Contract

> Learn where to store your canonical CV markdown file in the career ops data contract repository. Follow this guide to keep your CV organized and accessible.

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

---

**Store your canonical CV as a file named [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) in the repository root directory (same level as [`README.md`](https://github.com/santifer/career-ops/blob/main/README.md)).**

The **career-ops** repository enforces a strict *Data Contract* that separates user-specific content from system infrastructure. Placing your résumé at the repository root ensures every pipeline tool—PDF generators, ATS scanners, and reporting scripts—can locate your authoritative career data without additional configuration.

## Understanding the Data Contract's User Layer

The **User Layer** explicitly designates [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) as the **single source of truth** for all résumé-related content. This contract is documented in [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) and prevents fragmentation by requiring one canonical location for your professional history.

When you follow this convention:

- PDF generation scripts read directly from [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) at build time
- ATS compatibility checks parse the same source file
- Report generators reference consistent career data

The system enforces this location by default, making root-level placement the zero-configuration option.

## Default Repository Structure

Your [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) belongs at the top level of the repository hierarchy:

```text
career-ops/
├─ cv.md               ← Your canonical CV (Markdown)
├─ config/
│   └─ profile.yml
├─ data/
│   └─ applications.md
└─ ... (other system files)

```

Notice that [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) sits alongside [`README.md`](https://github.com/santifer/career-ops/blob/main/README.md), not nested inside `config/` or `data/`. These subdirectories contain supplementary files—[`profile.yml`](https://github.com/santifer/career-ops/blob/main/profile.yml) for personal metadata, [`applications.md`](https://github.com/santifer/career-ops/blob/main/applications.md) for job tracking—but your **primary résumé content** remains elevated to root status.

## Verifying Your CV Location

Confirm correct placement with a simple directory listing:

```bash

# Verify the CV exists at the expected path

$ ls -1 cv.md
cv.md

```

If the file returns successfully, all dependent scripts will resolve it correctly.

## Programmatic Access

Scripts throughout the pipeline reference [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) directly by relative path. Here's how a typical tool ingests your résumé:

```javascript
// Example: a script that reads the CV
import { readFileSync } from 'fs';
const cv = readFileSync('cv.md', 'utf8');
console.log(cv);

```

This pattern appears in PDF generators, HTML exporters, and validation utilities. Hardcoding the relative path `'cv.md'` assumes root placement—deviating from this structure requires modifying every downstream consumer.

## Custom Data Root Configurations

The system supports relocating your entire data directory through two mechanisms:

- **`CAREER_OPS_ROOT`** environment variable
- **`.career-ops-data`** marker file

When either is present, [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) resolves relative to that custom root rather than the repository root. Documentation in [`docs/CUSTOMIZATION.md`](https://github.com/santifer/career-ops/blob/main/docs/CUSTOMIZATION.md) explains this discovery behavior.

However, the **default and recommended placement remains the repository root** unless you have specific organizational requirements. Custom roots add configuration overhead and complicate collaboration.

## Key Files in the Data Contract

| File | Role |
|------|------|
| [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) | Canonical Markdown résumé (User Layer) |
| [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) | Defines the contract and required user files, including [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) |
| [`docs/CUSTOMIZATION.md`](https://github.com/santifer/career-ops/blob/main/docs/CUSTOMIZATION.md) | Guidance on where user data files should reside |
| [`README.md`](https://github.com/santifer/career-ops/blob/main/README.md) | General project overview; mentions the CV location |

## Summary

- **Name your file [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md)** — the Data Contract mandates this exact filename
- **Place it in the repository root** — same level as [`README.md`](https://github.com/santifer/career-ops/blob/main/README.md) for automatic discovery
- **Reference it relatively** — scripts expect `'./cv.md'` without path prefixes
- **Reserve `config/` and `data/` for secondary files** — these house supplements, not your primary résumé

Following this convention maximizes compatibility with the career-ops toolchain and ensures your CV remains the authoritative source across all pipeline stages.

## Frequently Asked Questions

### What happens if I store my CV in a subdirectory?

Scripts will fail to locate [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) because they expect it at the repository root by default. You would need to modify every consuming script or set a custom data root via `CAREER_OPS_ROOT` or `.career-ops-data`, both documented in [`docs/CUSTOMIZATION.md`](https://github.com/santifer/career-ops/blob/main/docs/CUSTOMIZATION.md).

### Can I use a different filename like [`resume.md`](https://github.com/santifer/career-ops/blob/main/resume.md) or `cv.markdown`?

No. The Data Contract explicitly requires [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) as the filename. The extension `.md` and lowercase name are hard requirements across the pipeline.

### How do I migrate my CV if I already have it in the wrong location?

Move your file to the repository root and rename it to [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md). Verify with `ls -1 cv.md`. No configuration changes are needed if you use the default location.

### Does the system support multiple CV versions?

The Data Contract specifies one canonical [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) per repository. For version-specific variants, maintain separate branches or repositories, or use the `data/` directory for supplementary role-targeted content while keeping [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) as your master source.