@forwardimpact/outpost 3.12.1 → 3.13.0

package/templates/.claude/skills/req-bundle/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: req-bundle
+description: >
+  Split a Workday CV-bundle PDF into per-candidate CV.pdf files under
+  2-Confidential/Candidates/. Reads the PDF outline (one bookmark per candidate) to
+  find each candidate's page range, matches it to the requisition roster so
+  folder names agree with req-workday, and extracts each CV losslessly. Use
+  when the user provides a Workday CV bundle (a large combined resume PDF, often
+  split into `_N_of_M` parts) and asks to split, unbundle, or extract individual
+  CVs — run this before req-workday imports the roster.
+---
+
+# Workday CV Bundle Split
+
+Write tier: `2-Confidential`
+Frontmatter: none (writes CV assets into candidate folders)
+
+Split a Workday CV-**bundle** PDF — one combined file holding every applicant's
+attachments — into per-candidate
+`2-Confidential/Candidates/{Clean Name}/CV.pdf`.
+
+This is the **PDF companion** to `req-workday`. `req-workday` imports the roster
+from the `.xlsx` (briefs + `CV.md` from embedded resume text); `req-bundle`
+attaches the real binary CV. Run `req-bundle` **first** so the folders it
+creates carry canonical names that `req-workday` then enriches — no duplicate
+folders.
+
+**How the split works.** Workday bundles have
+**no per-candidate separator page** and the name printed on a CV often differs
+from the roster name, so text-based splitting is unreliable. The one dependable
+delimiter is the **PDF outline**: exactly one flat bookmark per candidate, its
+destination being that candidate's first page. Candidate *i* = pages
+`[bookmark(i), bookmark(i+1) − 1]`; the last runs to EOF; the leading Table of
+Contents (before the first bookmark) is skipped. Multiple attachments for one
+candidate sit under one bookmark, so the range captures them all.
+`split-bundle.mjs` reads the outline with `pdfjs-dist` (`getOutline` +
+`getPageIndex`) and extracts each range losslessly with `pdf-lib` (`copyPages`).
+Full anatomy: [references/pdf-structure.md](references/pdf-structure.md).
+
+## Trigger
+
+- The user provides a Workday CV bundle PDF (a large combined resume export),
+  possibly split into `..._1_of_N.pdf … _N_of_N.pdf` parts.
+- The user asks to split, unbundle, or extract individual CVs from a Workday
+  export before importing candidates.
+
+## Prerequisites
+
+- PDF libraries for the split (`bun`/`node`), installed via the standard guard:
+  `bun pm ls pdfjs-dist 2>/dev/null || bun install pdfjs-dist` and
+  `bun pm ls pdf-lib 2>/dev/null || bun install pdf-lib`.
+- The `req-workday` parser dependencies, since the roster is produced by
+  `parse-workday.mjs` (see [../req-workday/SKILL.md](../req-workday/SKILL.md)):
+  `read-excel-file` and `fflate`.
+
+## Inputs
+
+- One or more bundle PDF paths (pass **all** parts of a multi-part export).
+- The requisition `.xlsx` (same req as the bundle) — parsed by
+  `req-workday`'s `parse-workday.mjs` into the roster JSON this script consumes,
+  so folder names are identical to what `req-workday` will create.
+
+## Outputs
+
+- `2-Confidential/Candidates/{Clean Name}/CV.pdf` — the candidate's extracted CV
+  (created only after the dry-run manifest is reviewed and confirmed).
+- A JSON manifest at `$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json`
+  — the reviewable mapping of every bookmark (page range, matched name, status).
+- Never overwrites an existing `CV.pdf`; a second CV for the same person is
+  staged as `CV-workday.pdf` / `CV-dup-N.pdf` and flagged for review.
+
+<do_confirm_checklist goal="Verify the split is complete, correctly named, and non-destructive">
+
+- [ ] Bundle page/bookmark counts sanity-checked; all parts of a multi-part
+      export passed together.
+- [ ] Roster parsed from the matching `.xlsx`; bookmark count reconciled against
+      roster count.
+- [ ] Dry-run manifest reviewed **before** any write; every `unmatched` bookmark
+      resolved to a candidate (or explicitly left staged).
+- [ ] Folder names equal the roster `cleanName` (annotation stripped) so they
+      match what `req-workday` produces.
+- [ ] Collisions (duplicate applications) and pre-existing `CV.pdf` files
+      handled without overwrite (`CV-dup-N.pdf` / `CV-workday.pdf`), each
+      flagged.
+- [ ] After commit, output CV count reconciles with matched bookmarks; a few
+      PDFs spot-opened to confirm the right, complete candidate.
+
+</do_confirm_checklist>
+
+## Procedure
+
+### 1. Set up
+
+Confirm the bundle PDF path(s) and the matching `.xlsx` (glob on the req number,
+not the timestamp — parts can carry different timestamps). Resolve `$HOME`
+(never pass a literal `~` to write tools). Ensure dependencies:
+
+```bash
+bun pm ls pdfjs-dist 2>/dev/null || bun install pdfjs-dist
+bun pm ls pdf-lib 2>/dev/null || bun install pdf-lib
+```
+
+### 2. Parse the roster
+
+Produce the canonical candidate list with `req-workday`'s parser (the single
+source of truth for `cleanName`s), saving the JSON for the split step:
+
+```bash
+node .claude/skills/req-workday/scripts/parse-workday.mjs "<path-to-requisition.xlsx>" --summary
+node .claude/skills/req-workday/scripts/parse-workday.mjs "<path-to-requisition.xlsx>" \
+  > "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json"
+```
+
+### 3. Dry-run the split
+
+Compute the mapping and manifest **without writing** any PDF. Pass every part of
+a multi-part bundle in one invocation:
+
+```bash
+node .claude/skills/req-bundle/scripts/split-bundle.mjs \
+  "<bundle_1_of_N.pdf>" "<bundle_2_of_N.pdf>" ... \
+  --roster "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json" \
+  --candidates-dir 2-Confidential/Candidates \
+  --manifest "$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json" \
+  --dry-run
+```
+
+The script prints a summary (bookmarks, matched, unmatched, collisions,
+existing-CV, roster-without-bookmark) and writes the full manifest. Matching
+rules and edge cases: [references/matching.md](references/matching.md).
+
+### 4. Reconcile and resolve
+
+Review the manifest. Confirm `bookmarks_total` reconciles with the roster count
+(expect a near-exact match). For each `unmatched` bookmark, use its `hints`
+(nearest roster names by shared tokens) to identify the candidate; note the
+correct `cleanName`. Investigate any `roster_unmatched_names` (applicants with
+no CV in the bundle — usually withdrawn/no-attachment). Do not proceed while
+unexpected mismatches remain unexplained.
+
+### 5. Confirm, then commit
+
+Summarize for the user: N CVs to write, M unmatched, K collisions/existing.
+**Get explicit confirmation** before writing. Re-run without `--dry-run` (same
+roster JSON) to create folders and write the CVs:
+
+```bash
+node .claude/skills/req-bundle/scripts/split-bundle.mjs \
+  "<bundle parts...>" \
+  --roster "$HOME/.cache/fit/outpost/state/req-bundle-roster-{Req ID}.json" \
+  --candidates-dir 2-Confidential/Candidates \
+  --manifest "$HOME/.cache/fit/outpost/state/req-bundle-{Req ID}.json"
+```
+
+For bookmarks that were `unmatched` but you resolved by hand in Step 4, move the
+staged file into the correct `2-Confidential/Candidates/{Clean Name}/CV.pdf`, or
+add the missing name variant and re-run — never hand-edit PDFs.
+
+### 6. Hand off and report
+
+Point `req-workday` at the same `.xlsx` to build briefs/`CV.md` and link the CV
+under each brief's `## CV` section. Flag every candidate that now has a `CV.pdf`
+for `req-screen`. Report `Split {matched}/{bookmarks_total} CVs for {Req ID}`,
+and list any unmatched bookmarks or roster applicants without a CV.

package/templates/.claude/skills/req-bundle/references/matching.md

@@ -0,0 +1,70 @@
+# Matching bookmarks to the roster, and edge cases
+
+How `split-bundle.mjs` maps each PDF bookmark to a canonical candidate folder,
+and how it handles duplicates, existing files, and misses. The goal: folder
+names identical to what `req-workday` produces, and **never** a destructive
+overwrite.
+
+## Why match at all
+
+The bookmark title is a clean name, but folder names must equal the roster
+`cleanName` — the applicant name from the `.xlsx` `Candidates` sheet with any
+trailing annotation (`(Internal)`, `(Prior Worker)`, …) stripped. That
+`cleanName` comes **directly from `req-workday`'s `parse-workday.mjs`** (the
+single source of truth this skill consumes as JSON), so the two skills agree by
+construction and never create duplicate folders. So: bookmark title → (match) →
+roster `cleanName` → folder.
+
+## Normalization (both sides)
+
+Before comparing, each name is folded with `normalize()`:
+
+1. Remove parentheticals — `(ΝΙΚΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ)`, `(Internal)`, `(Referral)`.
+2. Remove bare annotation tokens — internal / referral / prior worker /
+   external.
+3. Strip diacritics (NFKD) — `Geraño` → `gerano`.
+4. Lowercase, keep `[a-z0-9 ]`, collapse whitespace.
+
+## Match methods (conservative, deterministic)
+
+Applied in order; the method is recorded in the manifest:
+
+1. **`exact`** — normalized strings equal.
+2. **`token-set`** — same set of tokens regardless of order (handles
+   "First Last" ↔ "Last First" and dropped middle names).
+3. **`unmatched`** — no confident match. The script does **not** guess by
+   subset/Levenshtein (that risks merging two different "David …"s). Instead it
+   attaches `hints`: the nearest roster names by shared-token count, for a human
+   to resolve.
+
+## Edge cases & how the script handles them
+
+- **Duplicate applications (collisions).** The same person appears under two
+  bookmarks (e.g. across two parts of a multi-part bundle). Both resolve to one
+  folder. The first writes `CV.pdf`; the next becomes `CV-dup-2.pdf` (then
+  `-3`, …) with status `collision`. Review whether it's a true duplicate (keep
+  one) or a distinct newer packet (rename intentionally). Never silently
+  overwrite.
+- **Pre-existing `CV.pdf`.** A candidate who already arrived via email
+  (`req-track`) may already have `CV.pdf`. The script writes `CV-workday.pdf`
+  with status `existing-cv` and flags it, so the richer existing artifact is
+  preserved. Decide per candidate which to keep.
+- **Unmatched bookmark.** Staged in a folder named from the sanitized bookmark
+  title, status `unmatched`, with `hints`. Resolve by identifying the right
+  `cleanName` and moving the staged `CV.pdf` into that folder, or by adding the
+  missing name variant and re-running. A genuinely stray bookmark (someone not
+  on the roster) is worth flagging to the user.
+- **Roster applicant with no bookmark** (`roster_unmatched_names`). Applied but
+  no CV in the bundle — usually withdrawn or never attached a resume. Expected;
+  just report it. Not an error.
+- **No outline** (`no-outline` status for a file). The PDF has no bookmarks —
+  it is not a standard Workday bundle, or the outline was stripped. Do not
+  attempt a blind page-count split; stop and tell the user.
+
+## Reconciliation checklist
+
+- `bookmarks_total` ≈ roster count (small gaps explained by
+  `roster_unmatched_names`).
+- `unmatched_bookmarks` == 0 after Step 4 resolution (or each is explained).
+- `matched` + resolved unmatched == CVs you expect to write.
+- Known repeat applicants line up with the reported `collisions`.

package/templates/.claude/skills/req-bundle/references/pdf-structure.md

@@ -0,0 +1,74 @@
+# Workday CV Bundle — PDF anatomy
+
+What a Workday "Download resumes / attachments" bundle looks like, and why the
+PDF outline is the only reliable way to split it.
+
+## The shape of a bundle
+
+- A bundle is **one PDF that concatenates every applicant's attachments** — CV,
+  and often a cover letter and certificates too — back to back.
+- **Front matter:** page 1 (and sometimes 2–3) is a whole-bundle **Table of
+  Contents** titled with the req, e.g. `4951493 - Principal Software Engineer`,
+  listing `Candidate Name | Candidate ID | Attachments`. The TOC has **no page
+  numbers** in its extracted text, so it is not a usable split key — skip it.
+- **No per-candidate separator/cover page.** Each candidate's first attachment
+  begins directly on its own page. The TOC is the only inserted page.
+
+## The delimiter: the PDF outline (bookmarks)
+
+Every bundle carries a **flat, depth-0 PDF outline with exactly one bookmark per
+candidate**. The bookmark's destination is that candidate's **first page**, and
+its title is the **clean candidate name** (no `(Internal)` / `(Referral)`
+suffix). This is the split key:
+
+- Candidate *i* → pages `[bookmark(i).page, bookmark(i+1).page − 1]`.
+- Last candidate → `[bookmark(last).page, EOF]`.
+- A candidate's **multiple attachments are all under their single bookmark**, so
+  the page range captures the cover letter + CV + certs together. (This is fine
+  — a hiring manager wants the whole packet; `req-screen` reads the CV within.)
+- Bookmark counts match roster counts exactly (verified live: 75↔75 on a
+  single-part export; 366↔366 across the four parts of a large export).
+
+`split-bundle.mjs` reads this via `pdfjs-dist`: `doc.getOutline()` for the
+items, then `doc.getPageIndex(dest[0])` (resolving named destinations through
+`doc.getDestination()` first) to turn each bookmark into a 0-based page index,
+then sorts by page. Page ranges are extracted losslessly with `pdf-lib`
+(`copyPages`).
+
+## What NOT to rely on
+
+- **Separator-page detection** — there are none.
+- **Name text at the top of a page** — a CV's printed name is the candidate's
+  own styling and often differs from the roster name (bookmark "Vivian Chen" →
+  CV reads "Wei-Ling (Vivian) Chen, PhD"). Match the **bookmark title**, not
+  page text.
+- **Page-text extraction** — unnecessary and unreliable for boundary detection:
+  the outline gives exact boundaries and the `.xlsx` already carries the resume
+  text.
+
+## Multi-part bundles (`_1_of_N` … `_N_of_N`)
+
+When a req has many applicants, Workday emits several PDFs. Key facts:
+
+- **Each part is self-contained:** its own TOC, its own ~100-candidate subset in
+  its own internal order (parts are *not* sequential slices of one ordering).
+- **No candidate spans a part boundary** — every part's first bookmark is a
+  fresh candidate after its TOC, and its last candidate is fully contained.
+- Therefore **process each part independently** and union the results; pass all
+  parts to `split-bundle.mjs` in one call.
+- A person may legitimately appear in two parts (a genuine duplicate
+  application). That surfaces as a **collision** in the manifest (same folder
+  targeted twice) — handled per [matching.md](matching.md), not stitched.
+
+## Observed reference numbers (live exports)
+
+| Bundle                                   | Pages | Bookmarks |
+| ---------------------------------------- | ----- | --------- |
+| Principal SWE req (single file)           | 215   | 75        |
+| Sr. Director req `_1_of_4`                | 321   | 100       |
+| Sr. Director req `_2_of_4`                | 314   | 100       |
+| Sr. Director req `_3_of_4`                | 278   | 100       |
+| Sr. Director req `_4_of_4`                | 213   | 66        |
+
+Note: one part's filename carried a slightly different timestamp than its
+siblings — glob on the req number, not the timestamp.

package/templates/.claude/skills/req-bundle/scripts/split-bundle.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+/**
+ * Split a Workday CV-bundle PDF into per-candidate CV.pdf files.
+ *
+ * Workday's "bundle" export concatenates every candidate's attachments (CV,
+ * cover letter, certificates) into one PDF with NO per-candidate separator page.
+ * The only reliable delimiter is the PDF outline (bookmarks): exactly one flat,
+ * depth-0 bookmark per candidate whose destination is that candidate's first
+ * page. Candidate i occupies pages [bookmark(i), bookmark(i+1) - 1]; the last
+ * candidate runs to the end of the file. Everything before the first bookmark is
+ * the front-matter Table of Contents and is skipped.
+ *
+ * This script reads the outline (pdfjs-dist), matches each bookmark title to a
+ * canonical candidate name from the parsed Workday roster (so folder names agree
+ * with req-workday), extracts the page range losslessly (pdf-lib), and writes it
+ * to 2-Confidential/Candidates/{Clean Name}/CV.pdf.
+ *
+ * It ALWAYS emits a JSON manifest describing every mapping and never overwrites
+ * an existing CV.pdf. With --dry-run it computes the manifest without touching
+ * disk. Multi-part bundles (`..._1_of_4.pdf` … `_4_of_4.pdf`) are self-contained:
+ * pass all parts as positional arguments; each part is processed independently.
+ *
+ * The roster is the stdout JSON of req-workday/scripts/parse-workday.mjs
+ * ({ requisition, candidates: [{ name, cleanName, ... }] }) — the single source
+ * of truth for candidate names, so this script needs no XLSX parser of its own.
+ *
+ * Requires (bun install): pdfjs-dist, pdf-lib.
+ *
+ * Usage:
+ *   node split-bundle.mjs <bundle.pdf> [<bundle2.pdf> ...] \
+ *       --roster <roster.json> \
+ *       --candidates-dir <2-Confidential/Candidates> \
+ *       --manifest <out.json> \
+ *       [--dry-run]
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+let PDFDocument, pdfjs;
+try {
+  ({ PDFDocument } = await import("pdf-lib"));
+  pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+} catch {
+  console.error(
+    "Error: pdfjs-dist and/or pdf-lib not found. Install them first:\n  bun install pdfjs-dist pdf-lib",
+  );
+  process.exit(1);
+}
+
+// --- CLI parsing --------------------------------------------------------------
+
+if (
+  process.argv.includes("-h") ||
+  process.argv.includes("--help") ||
+  process.argv.length < 3
+) {
+  console.log(`split-bundle — split a Workday CV bundle into per-candidate CV.pdf by PDF bookmarks
+
+Usage:
+  node split-bundle.mjs <bundle.pdf> [<bundle2.pdf> ...] --roster <roster.json> \\
+       --candidates-dir <dir> --manifest <out.json> [--dry-run]
+
+  <roster.json> is the stdout of req-workday/scripts/parse-workday.mjs.`);
+  process.exit(process.argv.length < 3 ? 1 : 0);
+}
+
+function optValue(name) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && i + 1 < process.argv.length
+    ? process.argv[i + 1]
+    : undefined;
+}
+
+const dryRun = process.argv.includes("--dry-run");
+const rosterPath = optValue("--roster");
+const candidatesDir = optValue("--candidates-dir");
+const manifestPath = optValue("--manifest");
+const FLAGS_WITH_VALUE = new Set([
+  "--roster",
+  "--candidates-dir",
+  "--manifest",
+]);
+const bundles = process.argv.slice(2).filter((a, i, arr) => {
+  if (a.startsWith("--")) return false;
+  const prev = arr[i - 1];
+  return !(prev && FLAGS_WITH_VALUE.has(prev)); // drop values consumed by flags
+});
+
+if (!candidatesDir || !manifestPath || bundles.length === 0) {
+  console.error(
+    "Error: need <bundle.pdf...>, --candidates-dir, and --manifest.",
+  );
+  process.exit(1);
+}
+
+// --- Name normalization & matching -------------------------------------------
+
+const SUFFIX_RE = /\b(internal|referral|prior worker|external|contractor)\b/gi;
+const PAREN_RE = /\([^)]*\)/g;
+
+/** Fold a display name to a comparable key: no parentheticals, no diacritics,
+ * lowercase alphanumerics only, whitespace collapsed. */
+function normalize(name) {
+  let s = name || "";
+  s = s.replace(PAREN_RE, " ").replace(SUFFIX_RE, " ");
+  s = s.normalize("NFKD").replace(/\p{M}/gu, ""); // strip combining accents
+  s = s.toLowerCase().replace(/[^a-z0-9\s]/g, " ");
+  return s.replace(/\s+/g, " ").trim();
+}
+
+/** Make a bookmark title safe as a directory name (used only when unmatched). */
+function sanitizeFolder(title) {
+  const s = (title || "").replace(/[/\\]/g, "-").replace(/\s+/g, " ").trim();
+  return s || "UNKNOWN";
+}
+
+class Roster {
+  constructor(candidates) {
+    this.byExact = new Map(); // normalized name -> canonical cleanName
+    this.byTokens = new Map(); // sorted-token key -> canonical cleanName
+    this.all = []; // [{ key, clean }]
+    for (const c of candidates) {
+      const clean = (c.cleanName || c.name || "").trim();
+      if (!clean) continue;
+      const key = normalize(clean);
+      if (!key) continue;
+      if (!this.byExact.has(key)) this.byExact.set(key, clean);
+      const tkey = key.split(" ").sort().join(" ");
+      if (!this.byTokens.has(tkey)) this.byTokens.set(tkey, clean);
+      this.all.push({ key, clean });
+    }
+  }
+
+  /** Return { clean, method } — conservative: exact key, then token-set equality. */
+  match(title) {
+    const key = normalize(title);
+    if (!key) return { clean: null, method: "unmatched" };
+    if (this.byExact.has(key))
+      return { clean: this.byExact.get(key), method: "exact" };
+    const tkey = key.split(" ").sort().join(" ");
+    if (this.byTokens.has(tkey))
+      return { clean: this.byTokens.get(tkey), method: "token-set" };
+    return { clean: null, method: "unmatched" };
+  }
+
+  /** Nearest roster names by shared-token count — helps a human resolve a miss. */
+  hints(title, limit = 3) {
+    const tokens = new Set(normalize(title).split(" ").filter(Boolean));
+    const scored = [];
+    for (const { key, clean } of this.all) {
+      const shared = key.split(" ").filter((t) => tokens.has(t)).length;
+      if (shared) scored.push({ shared, clean });
+    }
+    scored.sort(
+      (a, b) => b.shared - a.shared || a.clean.localeCompare(b.clean),
+    );
+    const out = [];
+    for (const { clean } of scored) {
+      if (!out.includes(clean)) out.push(clean);
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+}
+
+// --- PDF outline handling -----------------------------------------------------
+
+/** Return [{ title, page }] (0-based page index) for every outline destination,
+ * in document order. pdfjs resolves both named and explicit destinations. */
+async function readOutline(doc) {
+  const outline = (await doc.getOutline()) || [];
+  const items = [];
+
+  async function pageIndex(dest) {
+    const explicit =
+      typeof dest === "string" ? await doc.getDestination(dest) : dest;
+    if (!Array.isArray(explicit) || !explicit[0]) return null;
+    try {
+      return await doc.getPageIndex(explicit[0]);
+    } catch {
+      return null;
+    }
+  }
+
+  // Flatten defensively (Workday bundles are flat, depth-0).
+  const stack = [...outline];
+  while (stack.length) {
+    const node = stack.shift();
+    const page = await pageIndex(node.dest);
+    if (node.title != null && page != null)
+      items.push({ title: String(node.title), page });
+    if (Array.isArray(node.items) && node.items.length)
+      stack.unshift(...node.items);
+  }
+  items.sort((a, b) => a.page - b.page);
+  return items;
+}
+
+function partLabel(path) {
+  const m = basename(path).match(/_(\d+)_of_(\d+)\b/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+// --- Main ---------------------------------------------------------------------
+
+let requisition = {};
+let rosterCandidates = [];
+if (rosterPath && existsSync(rosterPath)) {
+  const data = JSON.parse(readFileSync(rosterPath, "utf8"));
+  rosterCandidates = data.candidates || [];
+  requisition = data.requisition || {};
+}
+const roster = new Roster(rosterCandidates);
+
+const entries = [];
+const matchedClean = new Set(); // normalized cleanNames that got a bookmark
+const folderWritten = new Map(); // folder -> count (within this run, for collisions)
+
+for (const bundle of bundles) {
+  // pdfjs detaches the ArrayBuffer it's handed, so give each library its own copy.
+  const doc = await pdfjs.getDocument({
+    data: new Uint8Array(readFileSync(bundle)),
+    useSystemFonts: true,
+    verbosity: 0,
+  }).promise;
+  const outline = await readOutline(doc);
+  const part = partLabel(bundle);
+
+  if (outline.length === 0) {
+    entries.push({
+      bundle,
+      part,
+      status: "no-outline",
+      note: "No PDF bookmarks found — cannot split this file by candidate.",
+    });
+    continue;
+  }
+
+  // pdf-lib source (only loaded when we actually extract).
+  let src = null;
+  let total = 0;
+  if (!dryRun) {
+    src = await PDFDocument.load(new Uint8Array(readFileSync(bundle)));
+    total = src.getPageCount();
+  } else {
+    total = doc.numPages;
+  }
+
+  for (let i = 0; i < outline.length; i++) {
+    const start = outline[i].page;
+    const end = i + 1 < outline.length ? outline[i + 1].page - 1 : total - 1;
+    const title = outline[i].title;
+    const { clean, method } = roster.match(title);
+    const matched = clean != null;
+    let folder, status, hints;
+    if (matched) {
+      matchedClean.add(normalize(clean));
+      folder = clean;
+      status = "matched";
+      hints = [];
+    } else {
+      folder = sanitizeFolder(title);
+      status = "unmatched";
+      hints = roster.hints(title);
+    }
+
+    const destDir = join(candidatesDir, folder);
+    const cvPath = join(destDir, "CV.pdf");
+    const seen = folderWritten.get(folder) || 0;
+    const existingCv = existsSync(cvPath);
+    let outName;
+    if (seen > 0) {
+      outName = `CV-dup-${seen + 1}.pdf`;
+      if (matched) status = "collision";
+    } else if (existingCv) {
+      outName = "CV-workday.pdf";
+      if (matched) status = "existing-cv";
+    } else {
+      outName = "CV.pdf";
+    }
+    folderWritten.set(folder, seen + 1);
+    const outPath = join(destDir, outName);
+
+    let action = dryRun ? "would-write" : "pending";
+    if (!dryRun) {
+      try {
+        mkdirSync(destDir, { recursive: true });
+        const out = await PDFDocument.create();
+        const idxs = [];
+        for (let p = start; p <= end; p++) idxs.push(p);
+        const copied = await out.copyPages(src, idxs);
+        for (const pg of copied) out.addPage(pg);
+        writeFileSync(outPath, await out.save());
+        action = "wrote";
+      } catch (exc) {
+        action = `error: ${exc.message || exc}`;
+      }
+    }
+
+    entries.push({
+      bundle,
+      part,
+      order: i + 1,
+      title,
+      page_start: start + 1, // 1-based for humans
+      page_end: end + 1,
+      page_count: end - start + 1,
+      matched,
+      match_method: method,
+      clean_name: clean || "",
+      folder,
+      status,
+      out_path: outPath,
+      action,
+      hints,
+    });
+  }
+}
+
+const rosterUnmatched = [
+  ...new Set(
+    rosterCandidates
+      .map((c) => c.cleanName || c.name)
+      .filter((n) => n && !matchedClean.has(normalize(n))),
+  ),
+].sort();
+
+const bookmarkEntries = entries.filter((e) => "title" in e);
+const summary = {
+  bundles: bundles.length,
+  bookmarks_total: bookmarkEntries.length,
+  matched: bookmarkEntries.filter((e) => e.matched).length,
+  unmatched_bookmarks: bookmarkEntries.filter((e) => !e.matched).length,
+  collisions: bookmarkEntries.filter((e) => e.status === "collision").length,
+  existing_cv: bookmarkEntries.filter((e) => e.status === "existing-cv").length,
+  roster_total: rosterCandidates.length,
+  roster_unmatched: rosterUnmatched.length,
+};
+
+const manifest = {
+  generated_from: bundles,
+  requisition,
+  candidates_dir: candidatesDir,
+  dry_run: dryRun,
+  summary,
+  entries,
+  roster_unmatched_names: rosterUnmatched,
+};
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+// Human summary to stdout.
+const mode = dryRun ? "DRY RUN — nothing written" : "COMMIT";
+console.log(
+  `[${mode}] ${requisition.id || "?"} ${requisition.title || ""}`.trimEnd(),
+);
+console.log(`  bundles:            ${summary.bundles}`);
+console.log(`  bookmarks:          ${summary.bookmarks_total}`);
+console.log(`  matched → roster:   ${summary.matched}`);
+console.log(`  unmatched bookmark: ${summary.unmatched_bookmarks}`);
+console.log(`  collisions (dupes): ${summary.collisions}`);
+console.log(`  existing CV.pdf:    ${summary.existing_cv}`);
+console.log(
+  `  roster w/o bookmark:${summary.roster_unmatched} (of ${summary.roster_total})`,
+);
+console.log(`  manifest:           ${manifestPath}`);
+if (summary.unmatched_bookmarks) {
+  console.log("  ⚠ unmatched bookmarks (resolve in the manifest):");
+  for (const e of bookmarkEntries) {
+    if (!e.matched) {
+      const hint = e.hints.length ? `  ~ ${e.hints.join(", ")}` : "";
+      console.log(
+        `      - "${e.title}" (p${e.page_start}-${e.page_end})${hint}`,
+      );
+    }
+  }
+}