@phuthuycoding/markcv 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ta Manh Quyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# markcv
+
+[![CI](https://github.com/phuthuycoding/markcv/actions/workflows/ci.yml/badge.svg)](https://github.com/phuthuycoding/markcv/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@phuthuycoding/markcv.svg)](https://www.npmjs.com/package/@phuthuycoding/markcv)
+
+<p align="center">
+  <img src="docs/screenshots/engineering-lead.png" width="640" alt="A CV rendered by markcv">
+  <br>
+  <sub><code>examples/engineering-lead.md</code> — plain Markdown in, two-page A4 PDF out</sub>
+</p>
+
+Build a CV from Markdown — a CLI **and** an MCP server for AI agents.
+
+Two things set it apart from ordinary markdown→PDF tools:
+
+- **`fit`** tells you *why* your CV does not fit on 2 pages. "Content too long" and "bad page break" are different illnesses with opposite cures — trimming words while the real culprit is a heading sitting 31px from the bottom of page 1 just wastes your time.
+- **`lint`** checks *content*, not formatting. It catches overselling **and underselling** — claiming less than you did is a mistake too, and it costs you something while gaining nothing.
+
+## Install
+
+```bash
+git clone https://github.com/phuthuycoding/markcv.git
+cd markcv
+npm install          # builds dist/ via the prepare script
+npm link             # puts `markcv` and `markcv-mcp` on your PATH
+```
+
+Or from npm:
+
+```bash
+npm install -g @phuthuycoding/markcv
+```
+
+The package is scoped, but the commands are not — you still type `markcv` and `markcv-mcp`.
+
+Requires a Chromium-based browser already on your machine (Chrome, Chromium, Edge, Brave). markcv deliberately does **not** download its own Chromium — it uses `puppeteer-core`, so the install stays small. If your browser lives somewhere unusual, point at it with `MARKCV_CHROME=/path/to/chrome`.
+
+## Usage
+
+```bash
+markcv render cv.md -o Output.pdf     # build the PDF, report the page count
+markcv fit cv.md --pages 2            # why it does not fit yet
+markcv lint cv.md                     # audit the content
+markcv tailor cv.md --jd jd.txt       # compare against a job description
+markcv new techlead --from cv-master.md
+markcv list                           # every CV in the folder
+markcv diff cv-a.md cv-b.md           # what a tailored copy dropped
+markcv build --pages 2                # build every cv-*.md
+```
+
+### `fit` — page-break diagnosis
+
+```
+✗ 3 pages (target 2)
+· content 1986px / 2080px available
+· 31px wasted by page breaks
+
+Blocks pushed to a new page:
+  PROJECT HIGHLIGHTS (H2, y=1009) → wastes 31px at the end of page 1
+
+Suggestions:
+  Content HAS ROOM (94px to spare) — length is not the problem, the page break is.
+  "PROJECT HIGHLIGHTS" at y=1009 has only 31px left before the end of page 1, so the whole block moved down.
+  Fix: reorder sections, cut ~3 lines above it, or use --theme compact.
+```
+
+### `lint` — rules
+
+| Rule | What it catches |
+|---|---|
+| `over-claim` | `spearheaded`, `rigorous`, `comprehensive`, `excellence`… — self-praise nobody can verify |
+| `under-claim` | `advised on` / `worked on` next to real scale — you are probably selling yourself short |
+| `tense` | a finished job still described in the present tense |
+| `unsupported-skill` | a skill listed under SKILLS with no experience line backing it |
+| `duplicate` | two bullets saying the same thing |
+| `role-mismatch` | an IC job title paired with people-management language |
+| `no-metric` | a long bullet with no number in it |
+| `ats-emoji` | emoji in a heading — risky for ATS parsers |
+| `long-bullet` | a bullet long enough that skimmers will skip it |
+
+## Examples
+
+Three complete CVs in [`examples/`](examples), written for different roles so you can see
+how the same format stretches. Each one builds with the default theme and no photo.
+
+<table>
+<tr>
+<td width="33%"><a href="docs/screenshots/backend-engineer.png"><img src="docs/screenshots/backend-engineer.png" alt="Backend engineer CV"></a></td>
+<td width="33%"><a href="docs/screenshots/engineering-lead.png"><img src="docs/screenshots/engineering-lead.png" alt="Engineering lead CV"></a></td>
+<td width="33%"><a href="docs/screenshots/data-scientist.png"><img src="docs/screenshots/data-scientist.png" alt="Data scientist CV"></a></td>
+</tr>
+<tr>
+<td align="center"><a href="examples/backend-engineer.md">backend-engineer.md</a><br><sub>1 page</sub></td>
+<td align="center"><a href="examples/engineering-lead.md">engineering-lead.md</a><br><sub>2 pages</sub></td>
+<td align="center"><a href="examples/data-scientist.md">data-scientist.md</a><br><sub>1 page</sub></td>
+</tr>
+</table>
+
+### With a portrait photo
+
+Markets differ: a CV in Berlin or Toronto normally carries no photo, while one in
+Vietnam, Japan or Germany's more traditional employers usually does. Drop a
+`photo.jpg` next to the markdown file and it lands in the top-right corner.
+
+<p align="center">
+  <a href="docs/screenshots/fullstack-engineer-photo.png">
+    <img src="docs/screenshots/fullstack-engineer-photo.png" width="440" alt="CV with a portrait photo">
+  </a>
+  <br>
+  <sub><a href="examples/with-photo/fullstack-engineer.md">examples/with-photo/fullstack-engineer.md</a> — one page, photo auto-detected</sub>
+</p>
+
+The photo lives in its own folder because detection is per-directory: any `.md`
+file next to a `photo.*` picks it up. Keep photo-less CVs in a separate folder,
+or pass `--no-photo`.
+
+Build them yourself:
+
+```bash
+markcv build examples --pages 2
+markcv render examples/with-photo/fullstack-engineer.md --pages 1
+```
+
+Note what the bullets in those samples have in common: a number, or a before and after.
+`lint` exists to push a CV in that direction — the samples are what it is aiming at, and
+[`test/fixtures/bad-cv.md`](test/fixtures/bad-cv.md) is what it is aiming away from.
+
+## MCP server
+
+Lets an AI agent (Claude Code, Claude Desktop, Cursor…) build and audit CVs on its own.
+
+Install it first (see [Install](#install) above), then point a client at `markcv-mcp`.
+
+Check the server starts (it waits for JSON-RPC on stdin and prints nothing — that is
+correct; Ctrl+C to quit):
+
+```bash
+markcv-mcp
+```
+
+### Register it with a client
+
+After `npm link` the command is simply `markcv-mcp`. Without it, use an **absolute path**
+to `dist/mcp/server.js`. The repo ships `.mcp.json.example` to copy from.
+
+**Claude Code** — add to `.mcp.json` in your project (shared with the team), or `~/.claude.json` (just you):
+
+```json
+{
+  "mcpServers": {
+    "markcv": {
+      "command": "markcv-mcp",
+      "cwd": "/path/to/your/cv/folder"
+    }
+  }
+}
+```
+
+Or add it from the command line:
+
+```bash
+claude mcp add markcv -- markcv-mcp
+claude mcp list          # confirm it connected
+```
+
+Restart the client afterwards so it picks the server up.
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), same `mcpServers` shape, then restart the app.
+
+**Cursor** — `.cursor/mcp.json` in the project, same shape.
+
+### File paths in tool arguments
+
+Every tool takes a file path. Relative paths resolve against the **server process's working directory**, so either pass absolute paths or give the server a `cwd`:
+
+```json
+{
+  "mcpServers": {
+    "markcv": {
+      "command": "node",
+      "args": ["/path/to/markcv/dist/mcp/server.js"],
+      "cwd": "/path/to/your/cv/folder"
+    }
+  }
+}
+```
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `render_cv` | build the PDF, return the real page count plus layout numbers |
+| `check_fit` | why it does not fit in N pages: too long, or bad page breaks |
+| `lint_cv` | audit content (overselling, underselling, tense, unbacked claims…) |
+| `tailor_to_jd` | compare against a job description (`jd_file` or `jd_text`) |
+| `list_variants` | list every CV in a folder |
+| `new_variant` | start a tailored copy from a master file |
+| `diff_variants` | compare two versions, see what a tailored copy dropped |
+
+Every tool returns **structured JSON**, not prose — so an agent can loop on it: edit the markdown → `check_fit` → read `slackPx` and `culprits` → edit again, until it fits.
+
+### Requirements
+
+Node >= 18 and a Chromium-based browser. If it is in a non-standard location:
+
+```json
+{ "mcpServers": { "markcv": { "command": "node", "args": ["..."],
+  "env": { "MARKCV_CHROME": "/path/to/chrome" } } } }
+```
+
+## CV format
+
+Plain Markdown. The only convention lives in the header:
+
+```markdown
+# Your Name
+
+**Email:** you@example.com
+**Phone:** +84 9xx xxx xxx
+
+***
+
+## OBJECTIVE
+...
+
+## WORK EXPERIENCE
+
+### Company Name
+
+**Job Title** | Jan 2020 - Dec 2023
+
+* Bullet...
+```
+
+`**Label:** value` lines directly under `# Your Name` become the contact block. A line containing `|` is read as job title + dates — and `lint` uses those dates to know whether a job has ended.
+
+**Portrait photo:** drop `photo.jpg` (or `photo.png`, `avatar.jpg`) next to the `.md` file and it is embedded in the top-right corner. Without one you get an empty placeholder box. Photos over 400KB trigger a warning, because they push the PDF past the upload limit many job portals enforce.
+
+**Skip a file in `markcv build`:** put `<!-- markcv:no-build -->` near the top. Useful for a master file that is a content store rather than something you submit.
+
+## Themes
+
+`classic` (default) and `compact`. Both are single-column, emoji-free, with a real text layer — safe for ATS parsers.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve, basename, join } from "node:path";
+import { render } from "./core/render.js";
+import { analyseFit } from "./core/fit.js";
+import { lint } from "./core/lint.js";
+import { tailor } from "./core/tailor.js";
+import { newVariant, listVariants, diffVariants } from "./core/variants.js";
+import { c, ok, bad, warn, info } from "./ui.js";
+const program = new Command();
+program.name("markcv").description("Build, fit and audit a CV written in Markdown").version("0.1.0");
+const pdfNameFor = (md) => md.replace(/\.md$/, ".pdf");
+function printFit(r) {
+    const head = r.fits ? ok(`${r.pages} page(s)`) : bad(`${r.pages} pages (target ${r.targetPages})`);
+    console.log(head);
+    console.log(info(`content ${r.contentHeight}px / ${r.usablePerPage * (r.targetPages ?? r.pages)}px available`));
+    if (r.wastedByBreaksPx > 0)
+        console.log(info(`${r.wastedByBreaksPx}px wasted by page breaks`));
+    if (r.culprits.length) {
+        console.log(c.bold("\nBlocks pushed to a new page:"));
+        for (const cu of r.culprits) {
+            console.log(`  ${c.yellow(cu.title)} ${c.dim(`(${cu.tag}, y=${cu.top})`)} → wastes ${c.red(String(cu.wastedPx) + "px")} at the end of page ${cu.page}`);
+        }
+    }
+    if (r.suggestions.length) {
+        console.log(c.bold("\nSuggestions:"));
+        for (const s of r.suggestions)
+            console.log(`  ${s}`);
+    }
+}
+function printLint(fs) {
+    if (!fs.length)
+        return console.log(ok("no issues found"));
+    const bySeverity = { error: 0, warn: 0, info: 0 };
+    for (const f of fs) {
+        bySeverity[f.severity]++;
+        const tag = f.severity === "error" ? c.red("error") : f.severity === "warn" ? c.yellow("warn ") : c.dim("info ");
+        console.log(`${tag} ${c.dim(`L${String(f.line).padStart(3)}`)} ${c.cyan(f.rule)}  ${f.message}`);
+        if (f.excerpt)
+            console.log(`      ${c.dim("→ " + f.excerpt)}`);
+        if (f.suggestion)
+            console.log(`      ${c.green("fix:")} ${f.suggestion}`);
+    }
+    console.log(`\n${bySeverity.error} error · ${bySeverity.warn} warn · ${bySeverity.info} info`);
+}
+program
+    .command("render <file>")
+    .description("Build a PDF (and HTML) from a markdown file")
+    .option("-o, --pdf <path>", "output PDF path")
+    .option("--html <path>", "keep the intermediate HTML")
+    .option("-t, --theme <name>", "theme: classic | compact", "classic")
+    .option("-p, --pages <n>", "target page count", (v) => parseInt(v, 10))
+    .option("--no-photo", "do not embed the portrait photo")
+    .action(async (file, o) => {
+    const res = await render({
+        input: file,
+        pdf: o.pdf ?? pdfNameFor(file),
+        html: o.html,
+        theme: o.theme,
+        photo: o.photo === false ? null : undefined,
+        targetPages: o.pages,
+    });
+    console.log(ok(`PDF  ${res.pdfPath}`));
+    if (o.html)
+        console.log(info(`HTML ${res.htmlPath}`));
+    const photoNote = o.photo === false ? "disabled" : res.photoFile ? basename(res.photoFile) : "none (placeholder box)";
+    console.log(info(`photo ${photoNote}`));
+    if (res.photoWarning)
+        console.log(warn(res.photoWarning));
+    const fit = analyseFit(res.measure, res.pageBox, res.pdfPages ?? 0, o.pages);
+    printFit(fit);
+});
+program
+    .command("fit <file>")
+    .description("Why the CV does not fit the target page count")
+    .option("-p, --pages <n>", "target page count", (v) => parseInt(v, 10), 2)
+    .option("-t, --theme <name>", "theme", "classic")
+    .option("--json", "output JSON")
+    .action(async (file, o) => {
+    const tmpPdf = join(process.env.TMPDIR ?? "/tmp", `markcv-fit-${Date.now()}.pdf`);
+    const res = await render({ input: file, pdf: tmpPdf, theme: o.theme, targetPages: o.pages });
+    const report = analyseFit(res.measure, res.pageBox, res.pdfPages ?? 0, o.pages);
+    if (o.json)
+        return console.log(JSON.stringify(report, null, 2));
+    printFit(report);
+    process.exitCode = report.fits ? 0 : 1;
+});
+program
+    .command("lint <file>")
+    .description("Audit content: overselling, underselling, tense, unbacked claims, duplicates")
+    .option("--json", "output JSON")
+    .option("--strict", "treat warnings as failures")
+    .action((file, o) => {
+    const findings = lint(readFileSync(resolve(file), "utf8"));
+    if (o.json)
+        return console.log(JSON.stringify(findings, null, 2));
+    printLint(findings);
+    const fail = findings.some((f) => f.severity === "error" || (o.strict && f.severity === "warn"));
+    process.exitCode = fail ? 1 : 0;
+});
+program
+    .command("tailor <file>")
+    .description("Compare the CV against a job description")
+    .requiredOption("--jd <path>", "job description file (txt/md)")
+    .option("--json", "output JSON")
+    .action((file, o) => {
+    const report = tailor(readFileSync(resolve(file), "utf8"), readFileSync(resolve(o.jd), "utf8"));
+    if (o.json)
+        return console.log(JSON.stringify(report, null, 2));
+    console.log(c.bold(`Match: ${report.score}%  (${report.covered.length}/${report.covered.length + report.missing.length + report.unsupported.length} JD keywords)`));
+    if (report.missing.length) {
+        console.log(c.bold("\nAsked for by the JD, missing from the CV:"));
+        for (const m of report.missing)
+            console.log(`  ${bad(m.keyword)} ${c.dim(m.hint)}`);
+    }
+    if (report.unsupported.length) {
+        console.log(c.bold("\nOnly under SKILLS, with no evidence:"));
+        for (const u of report.unsupported)
+            console.log(`  ${warn(u.keyword)} ${c.dim(u.hint)}`);
+    }
+    if (report.irrelevant.length) {
+        console.log(c.bold("\nBullets unrelated to the JD (cut these first):"));
+        for (const i of report.irrelevant.slice(0, 8))
+            console.log(`  ${c.dim(`L${i.line}`)} ${i.excerpt}`);
+    }
+    if (report.covered.length) {
+        console.log(c.bold("\nBacked by evidence:"));
+        console.log("  " + report.covered.map((x) => c.green(x.keyword)).join(", "));
+    }
+});
+program
+    .command("new <name>")
+    .description("Start a tailored version from a master file")
+    .requiredOption("--from <master>", "master CV file")
+    .action((name, o) => console.log(ok(`created ${newVariant(o.from, name)}`)));
+program
+    .command("list [dir]")
+    .description("List every CV in a folder")
+    .action((dir = ".") => {
+    for (const v of listVariants(dir)) {
+        console.log(`${c.bold(v.name.padEnd(28))} ${String(v.lines).padStart(4)} lines  ${String(v.bullets).padStart(3)} bullets  ${c.dim(v.sections.join(" · "))}`);
+    }
+});
+program
+    .command("diff <a> <b>")
+    .description("Compare two CVs bullet by bullet")
+    .action((a, b) => {
+    const d = diffVariants(a, b);
+    console.log(c.bold(`${d.shared} bullets in common`));
+    if (d.onlyInA.length) {
+        console.log(c.bold(`\nOnly in ${basename(a)}:`));
+        for (const l of d.onlyInA)
+            console.log(`  ${c.green("+")} ${l.slice(0, 100)}`);
+    }
+    if (d.onlyInB.length) {
+        console.log(c.bold(`\nOnly in ${basename(b)}:`));
+        for (const l of d.onlyInB)
+            console.log(`  ${c.blue("+")} ${l.slice(0, 100)}`);
+    }
+});
+program
+    .command("build [dir]")
+    .description("Build a PDF for every cv-*.md in a folder")
+    .option("-p, --pages <n>", "target page count", (v) => parseInt(v, 10), 2)
+    .option("-t, --theme <name>", "theme", "classic")
+    .action(async (dir = ".", o) => {
+    const all = readdirSync(resolve(dir)).filter((f) => f.startsWith("cv-") && f.endsWith(".md"));
+    // A file marked <!-- markcv:no-build --> is a content store, not something you
+    // submit — skip it in batch builds.
+    const files = all.filter((f) => {
+        const head = readFileSync(join(resolve(dir), f), "utf8").slice(0, 400);
+        const skip = /markcv:no-build/i.test(head);
+        if (skip)
+            console.log(`${c.dim("–")} ${f.padEnd(34)} ${c.dim("skipped (content store)")}`);
+        return !skip;
+    });
+    if (!files.length)
+        return console.log(warn("nothing to build"));
+    for (const f of files) {
+        const src = join(resolve(dir), f);
+        const res = await render({ input: src, pdf: pdfNameFor(src), theme: o.theme, targetPages: o.pages });
+        const fit = analyseFit(res.measure, res.pageBox, res.pdfPages ?? 0, o.pages);
+        const mark = fit.fits ? c.green("✓") : c.red("✗");
+        console.log(`${mark} ${f.padEnd(34)} ${fit.pages} page(s)  ${c.dim(fit.fits ? "" : fit.suggestions[0] ?? "")}`);
+    }
+});
+program.parseAsync(process.argv);

package/dist/core/browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Locate an installed Chrome. markcv deliberately does NOT ship its own Chromium
+ * (puppeteer-core, not puppeteer) so the install stays small.
+ */
+export declare function findChrome(explicit?: string): string;

package/dist/core/browser.js

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+/** Common Chrome/Edge/Chromium locations, per platform. */
+const PATHS = {
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ],
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/usr/bin/microsoft-edge",
+        "/snap/bin/chromium",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    ],
+};
+/**
+ * Locate an installed Chrome. markcv deliberately does NOT ship its own Chromium
+ * (puppeteer-core, not puppeteer) so the install stays small.
+ */
+export function findChrome(explicit) {
+    if (explicit) {
+        if (!existsSync(explicit))
+            throw new Error(`No browser found at: ${explicit}`);
+        return explicit;
+    }
+    const fromEnv = process.env.MARKCV_CHROME ?? process.env.CHROME_PATH;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    const found = (PATHS[platform()] ?? []).find(existsSync);
+    if (!found) {
+        throw new Error("No Chrome/Chromium/Edge found on this machine.\n" +
+            "Install Chrome, or point at it with MARKCV_CHROME=/path/to/chrome");
+    }
+    return found;
+}

package/dist/core/fit.d.ts

@@ -0,0 +1,11 @@
+import type { FitReport } from "../types.js";
+import type { RawMeasure, PageBox } from "./render.js";
+/**
+ * Explain why a CV does not fit the target page count.
+ *
+ * The key distinction: "content too long" and "bad page break" are TWO different
+ * problems with opposite cures. Trimming words while the real culprit is a heading
+ * sitting just above a page boundary wastes effort — that one needs a reorder or
+ * tighter spacing instead.
+ */
+export declare function analyseFit(measure: RawMeasure, pageBox: PageBox, pdfPages: number, targetPages?: number): FitReport;

package/dist/core/fit.js

@@ -0,0 +1,69 @@
+/**
+ * Explain why a CV does not fit the target page count.
+ *
+ * The key distinction: "content too long" and "bad page break" are TWO different
+ * problems with opposite cures. Trimming words while the real culprit is a heading
+ * sitting just above a page boundary wastes effort — that one needs a reorder or
+ * tighter spacing instead.
+ */
+export function analyseFit(measure, pageBox, pdfPages, targetPages) {
+    const usable = pageBox.heightPx;
+    const { contentHeight } = measure;
+    const culprits = [];
+    for (const b of measure.blocks) {
+        // Bottom edge of the page this block sits on. floor+1, not ceil: a block at
+        // y=0 belongs to page 1 and still has the whole page below it.
+        const pageEnd = (Math.floor(b.top / usable) + 1) * usable;
+        const room = pageEnd - b.top;
+        // The cluster (heading + the element glued to it) does not fit -> it gets pushed down.
+        if (b.clusterHeight > room) {
+            culprits.push({
+                title: b.title,
+                tag: b.tag,
+                top: b.top,
+                wastedPx: Math.round(room),
+                page: Math.floor(b.top / usable) + 1,
+            });
+        }
+    }
+    culprits.sort((a, b) => b.wastedPx - a.wastedPx);
+    const wastedByBreaksPx = culprits.reduce((sum, c) => sum + c.wastedPx, 0);
+    const target = targetPages ?? pdfPages;
+    const budget = usable * target;
+    const slackPx = Math.round(budget - contentHeight);
+    const contentWouldFit = contentHeight <= budget;
+    const fits = pdfPages <= target;
+    const suggestions = [];
+    if (!fits) {
+        if (contentWouldFit) {
+            const worst = culprits[0];
+            suggestions.push(`Content HAS ROOM (${slackPx}px to spare) - length is not the problem, the page break is.`);
+            if (worst) {
+                suggestions.push(`"${worst.title}" at y=${worst.top} has only ${worst.wastedPx}px left before the end of ` +
+                    `page ${worst.page}, so the whole block moved down.`);
+                suggestions.push(`Fix: reorder sections, cut ~${Math.ceil(worst.wastedPx / 15)} lines above it, ` +
+                    `or use --theme compact.`);
+            }
+        }
+        else {
+            const over = Math.abs(slackPx);
+            suggestions.push(`Content is ~${over}px longer than ${target} page(s) (~${Math.ceil(over / 15)} lines).`);
+            suggestions.push(`Cut ~${Math.ceil(over / 15)} lines, or use --theme compact.`);
+            if (wastedByBreaksPx > 0) {
+                suggestions.push(`On top of that, ${wastedByBreaksPx}px is wasted by page breaks - see culprits.`);
+            }
+        }
+    }
+    return {
+        pages: pdfPages,
+        targetPages,
+        fits,
+        contentHeight,
+        usablePerPage: usable,
+        slackPx,
+        contentWouldFit,
+        wastedByBreaksPx,
+        culprits: culprits.slice(0, 5),
+        suggestions,
+    };
+}

package/dist/core/lint.d.ts

@@ -0,0 +1,2 @@
+import type { LintFinding } from "../types.js";
+export declare function lint(raw: string): LintFinding[];