cv-2026/CLAUDE.md

# CV-2026 — Project Instructions for Claude

This project is Oleg's CV generation pipeline. It supports three workflows:

1. **Base CV refresh** — turn a new Markdown CV into a styled PDF.
2. **Company tailoring** — quickly adapt the latest base CV to a specific company/role and produce a tuned PDF.
3. **Application tracking** — log applications, outreaches, and follow-up communications.

The visual format of every generated PDF must match `base/reference/Oleg_Proskurin_Techlead_resume.docx.pdf` — that file is the canonical style reference.

---

## Folder layout

```
base/
  cv-YYYY-MM-base.md           # current master CV in Markdown
  reference/
    Oleg_Proskurin_*.pdf        # canonical visual reference (do not edit)
templates/
  cv-style.css                  # shared stylesheet — used by every CV
  cv-template.html              # skeleton HTML (use as a starting point)
tailored/
  <company-slug>/
    cv.md                       # tailored Markdown
    cv.html                     # generated HTML
    cv.pdf                      # final PDF
    notes.md                    # job posting, contact, decisions log
tracking/
  applications.md               # one row per application
  outreach.md                   # cold outreach + recruiter conversations
scripts/
  generate-pdf.mjs              # HTML -> PDF (puppeteer)
output/
  html/                         # generated HTML for base CVs (transient)
  pdf/                          # final PDFs for base CVs (committed)
```

---

## Workflow 1 — Generate base CV PDF from Markdown

**Input**: `base/cv-YYYY-MM-base.md`
**Output**: `output/pdf/cv-YYYY-MM-base.pdf`

Steps:

1. Read the Markdown source and the reference PDF (`base/reference/...`) to confirm structure.
2. Generate `output/html/cv-YYYY-MM-base.html` using `templates/cv-template.html` as a starting point.
   - Link the stylesheet via `<link rel="stylesheet" href="/templates/cv-style.css" />` (absolute path — the PDF script serves the project root).
   - Map MD content to HTML tags **verbatim** — section titles, punctuation, list structure, dates, and contact separators must match MD character-for-character. The structure below is the tag shape; the **text** comes from MD. See "Content vs. style — separation rule" below.
3. Run the PDF generator:
   ```bash
   pnpm pdf output/html/cv-YYYY-MM-base.html
   ```
4. Open the resulting PDF (`output/pdf/cv-YYYY-MM-base.pdf`) and verify single-page-ish, no orphan bullets, no overflow.

---

## Workflow 2 — Tailor CV for a specific company

**Input**: latest `base/cv-*.md` + job description / company info
**Output**: `tailored/<company-slug>/cv.pdf`

Steps:

1. Create `tailored/<company-slug>/` folder. Use a short kebab-case slug (e.g. `vercel`, `stripe-platform`, `anthropic-applied`).
2. Copy the base MD into `tailored/<company-slug>/cv.md`.
3. Tailor the content:
   - **Summary**: re-frame around the company's stack and the role's keywords. Keep facts intact, shift emphasis.
   - **Skills**: reorder so the most relevant categories/tools appear first. Drop categories that are irrelevant to keep density.
   - **Bullets**: reorder within each job so the top bullets match what the company values. Edit phrasing to use the company's vocabulary, but never invent achievements.
   - Keep length ≤ 2 pages.
4. Save the job posting, recruiter contacts, and tailoring decisions in `tailored/<company-slug>/notes.md`.
5. Generate `tailored/<company-slug>/cv.html` (same template/CSS).
6. Run the PDF generator with an explicit output directory:
   ```bash
   pnpm pdf tailored/<company-slug>/cv.html tailored/<company-slug>
   ```
   That writes `tailored/<company-slug>/cv.pdf`.
7. Add a row to `tracking/applications.md`.

---

## Workflow 3 — Tracking

- **`tracking/applications.md`**: one row per application. Status column drives the funnel (applied, screen, interview, offer, rejected, withdrawn). Always store absolute dates (e.g. `2026-05-24`).
- **`tracking/outreach.md`**: log cold messages, recruiter pings, and follow-ups. One row per touchpoint; group by company.
- When asked to "log this application" or similar, append to the right file — never rewrite existing rows unless explicitly asked.

---

## Content vs. style — separation rule

**This is the load-bearing rule for MD→HTML conversion. Read it before generating any HTML.**

All text in the generated HTML comes **verbatim** from the source Markdown — section titles, contact-row separators, date formats, punctuation, bullet leads, list structure. The reference PDF supplies **only** visual conventions: typography, sizes, margins, colors, spacing, alignment, two-column header rows. The only allowed transformation is mapping MD markup to HTML tags:

- `# x` → `<h1>x</h1>`
- `## x` → `<h2>x</h2>` (exact text — do not rename)
- `### x` → article header (exact text — do not reword)
- `**x**` → `<strong>x</strong>`
- `*x*` / `_x_` → `<em>x</em>`
- `` `x` `` → `<code>x</code>`
- `[text](url)` → `<a href="url">text</a>`
- `- item` → `<li>item</li>`
- `---` (horizontal rule) → drop (section separators are visual via `<h2>` underline)

Forbidden rewrites (examples — do not do these):

- `## Summary` → `Professional Summary` (rename) ❌
- `## Experience` → `Work History` (rename) ❌
- `·` separators in contacts → `|` (substitution) ❌
- `Feb 2025 – Present` → `02/2025 — Current` (date reformatting) ❌
- Skills bullet list collapsed into a dense paragraph (structure change) ❌
- Job-description paragraph truncated to a short label (content loss) ❌

If the visual style of the reference PDF appears to conflict with what's in MD, the **MD wins**. Update MD if you want different content; never silently rewrite it during HTML generation.

---

## Visual format rules (must match the reference PDF)

The CSS in `templates/cv-style.css` already encodes these — when generating HTML, just use the classes and the format will follow. Reference for human review:

- **Page**: A4, ~12mm margins, single column.
- **Font**: Times New Roman (serif), body 10.5pt, line-height 1.25.
- **Header**: centered name in 14pt bold caps, role in 11pt bold, single contact row with `|` separators.
- **Section headings**: ALL CAPS, bold, 10.5pt, with a thin bottom rule.
- **Job entry**:
  - Header row: company (bold, left) — role (bold, right).
  - Meta row: short company descriptor (italic, left) — dates (italic, right).
  - Bulleted list with disc markers, hanging indent.
- **Links**: blue `#1155cc`, underlined.
- **Length**: target 2 pages.

## HTML structure to use

```html
<header class="cv-header">
  <h1 class="name">OLEG PROSKURIN</h1>
  <p class="role">Role line</p>
  <p class="contacts">email | LinkedIn | Telegram | Github | ...</p>
</header>

<section class="cv-section">
  <h2><!-- exact ## heading from MD, e.g. "Summary" --></h2>
  <p>...</p>
</section>

<section class="cv-section cv-skills">
  <h2>Skills</h2>
  <!-- For each `**Category**` block in MD followed by a `-` list,
       render the category as <strong> then a <ul> of bullets verbatim. -->
  <p><strong>Category</strong></p>
  <ul>
    <li>Item from MD bullet (text verbatim, including ":" and punctuation)</li>
  </ul>
</section>

<section class="cv-section">
  <h2><!-- e.g. "Experience" --></h2>
  <article class="cv-job">
    <!-- ### Company — Role  →  split on first " — " -->
    <div class="cv-job-header">
      <span class="company">Company</span>
      <span class="role">Role</span>
    </div>
    <!-- "**Dates** · Location" line  →  location left, dates right -->
    <div class="cv-job-meta">
      <span>Location</span>
      <span class="dates">Dates verbatim from MD (e.g. "Feb 2025 – Present")</span>
    </div>
    <!-- Full description paragraph from MD (do not truncate). Italic. -->
    <p class="cv-job-desc">Full descriptor paragraph from MD...</p>
    <ul>
      <li>Bullet text verbatim from MD (keep <strong>...</strong>: punctuation as-is)</li>
    </ul>
  </article>
</section>

<section class="cv-section">
  <h2><!-- e.g. "Education" --></h2>
  <p>...</p>
</section>

<section class="cv-section">
  <h2><!-- e.g. "Languages" --></h2>
  <p>...</p>
</section>
```

---

## Conventions

- **Language**: every artifact (HTML, MD, PDF, tracking rows, card notes) is in English. Always.
- **Filenames**: kebab-case. CVs: `cv-YYYY-MM-base.md` for base, `cv.md` inside `tailored/<slug>/` for tailored.
- **Dates**: absolute (`2026-05-24`), never "last Thursday".
- **Don't edit the reference PDF.** It is the immutable visual anchor.
- **Don't auto-regenerate PDFs** unless Oleg asks — show diffs first when content changes.
- **Verify before claiming "done"**: after `pnpm pdf`, confirm the PDF exists and looks correct (open it, check page count). If you can't visually verify, say so.