job-forge 2.0.0

package/README.md

@@ -0,0 +1,195 @@
+# JobForge
+
+> AI-powered job search pipeline built on opencode. Evaluate offers, generate tailored CVs, scan portals, negotiate offers, and track everything -- powered by AI agents.
+
+![opencode](https://img.shields.io/badge/opencode-000?style=flat&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white)
+![Geometra](https://img.shields.io/badge/Geometra_MCP-4A90D9?style=flat&logoColor=white)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![Made in USA](https://img.shields.io/badge/Made_in-USA_%F0%9F%87%BA%F0%9F%87%B8-red?style=flat)
+
+<p align="center">
+  <img src="demo/demo.gif" alt="JobForge Demo" width="800">
+</p>
+
+<p align="center"><em>Paste a job URL. Get a scored evaluation, tailored CV, and tracked application — in seconds.</em></p>
+
+---
+
+## Quick Start
+
+```bash
+npx github:razroo/JobForge create-job-forge my-job-search
+cd my-job-search
+npm install
+opencode
+```
+
+The scaffolded `opencode.json` already has the Geometra MCP (browser automation + PDF) and Gmail MCP (reading replies) wired up — they launch automatically the first time opencode starts.
+
+Then fill in `cv.md`, `config/profile.yml`, and `portals.yml` with your personal data, paste a job URL into opencode, and JobForge evaluates + tracks it.
+
+**Upgrade later:** `npm run update-harness` (pulls latest harness + fallback plugin, re-syncs symlinks, prints the resolved commit)
+
+Full setup guide and alternative install paths (including contributing to the harness itself): **[docs/SETUP.md](docs/SETUP.md)**.
+
+---
+
+## What Is This
+
+JobForge turns opencode into a full job search command center. Instead of manually tracking applications in a spreadsheet, you get an AI-powered pipeline that:
+
+- **Evaluates offers** with a unified 10-dimension weighted scoring system
+- **Generates tailored PDFs** -- ATS-optimized CVs with anti-AI-detection writing rules
+- **Scans portals** with fuzzy dedup (catches reposts with new URLs)
+- **Processes in batch** -- evaluate 10+ offers in parallel with sub-agents
+- **Tracks everything** with pipeline integrity checks and canonical state management
+- **Manages follow-ups** -- timing-based nudges so you never miss a window
+- **Learns from rejections** -- pattern analysis across all rejections by stage, archetype, and score
+- **Negotiates offers** -- structured comp breakdown, leverage assessment, counter-offer strategy
+
+> **Important: This is NOT a spray-and-pray tool.** The whole point is to apply only where there's a real match. The scoring system helps you focus on high-fit opportunities instead of wasting everyone's time. Always review before submitting.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Auto-Pipeline** | Paste a URL, get a full evaluation + PDF + tracker entry |
+| **Unified Scoring** | 10 weighted dimensions, consistent across all modes, with calibration anchors |
+| **Anti-AI-Detection CVs** | Writing rules that avoid ATS filters on Indeed, LinkedIn, Workday |
+| **6-Block Evaluation** | Role summary, CV match, level strategy, comp research, personalization, interview prep (STAR+R) |
+| **Interview Story Bank** | Curated bank of 10-12 stories with match counts, archetype tags, and automatic pruning |
+| **Follow-Up System** | Timing-based nudges: Applied 7+ days ago nudge, Interviewed 1 day ago thank-you note, email scanning via Gmail MCP |
+| **Gmail Integration** | MCP server configured to retrieve emails for interview callbacks, offer responses, and application status updates |
+| **Rejection Analysis** | Captures stage + reason, surfaces patterns (archetype gaps, scoring miscalibration) |
+| **Offer Negotiation** | Total comp breakdown, equity valuation, leverage from pipeline, counter-offer scripts |
+| **Deep Research** | Company research that feeds back into scores and interview prep |
+| **Smart LinkedIn Outreach** | Reads evaluation reports to craft targeted messages using top proof points |
+| **Portal Scanner** | 45+ companies pre-configured with fuzzy dedup for reposts |
+| **Batch Processing** | Parallel evaluation with `opencode run` workers, with honest verification flagging |
+| **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
+| **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task model tiers; procedural work runs on free-tier models, quality-sensitive work on paid. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
+| **Automatic Model Fallback** | When a model rate-limits or 5xx's, [`@razroo/opencode-model-fallback`](https://www.npmjs.com/package/@razroo/opencode-model-fallback) rotates the agent through a configured `fallback_models` chain and replays the request. Ships with sensible defaults: free-tier agents fall back to another free model then to paid as an escape hatch, paid agents fall back to a different paid provider. |
+| **Token Cost Visibility** | `job-forge tokens --days 1` for per-session breakdown; `job-forge session-report --since-minutes 60 --log` to flag sessions over budget and append history to `data/token-usage.tsv`. Auto-logged after every batch run. |
+
+## Usage
+
+```
+/job-forge                → Show all available commands
+/job-forge {paste a JD}   → Full auto-pipeline (evaluate + PDF + tracker)
+/job-forge scan           → Scan portals for new offers
+/job-forge pdf            → Generate ATS-optimized CV
+/job-forge batch          → Batch evaluate multiple offers
+/job-forge tracker        → View application status
+/job-forge apply          → Fill application forms with AI
+/job-forge pipeline       → Process pending URLs
+/job-forge contact        → LinkedIn outreach (uses evaluation report)
+/job-forge deep           → Deep company research (feeds back into scores)
+/job-forge followup       → Check what needs follow-up action
+/job-forge rejection      → Record/analyze rejection patterns
+/job-forge negotiation    → Structured offer negotiation
+/job-forge training       → Evaluate a course/cert
+/job-forge project        → Evaluate a portfolio project
+```
+
+Or just paste a job URL or description directly -- JobForge auto-detects it and runs the full pipeline.
+
+> **The system is designed to be customized by opencode itself.** Modes, archetypes, scoring weights, negotiation scripts -- just ask opencode to change them: "Change the archetypes to backend engineering roles", "Add these 5 companies to portals.yml", "Update my profile with this CV I'm pasting".
+
+## How It Works
+
+```
+You paste a job URL or description
+        │
+        ▼
+┌──────────────────┐
+│  Archetype       │  Classifies: LLMOps / Agentic / PM / SA / FDE / Transformation
+│  Detection       │
+└────────┬─────────┘
+         │
+┌────────▼─────────┐
+│  A-F Evaluation   │  Match, gaps, comp research, STAR stories
+│  (reads cv.md)    │  Unified 10-dimension scoring model
+└────────┬─────────┘
+         │
+    ┌────┼────┐
+    ▼    ▼    ▼
+ Report  PDF  Tracker
+  .md   .pdf   .tsv
+         │
+    ┌────┼────┐
+    ▼    ▼    ▼
+ Apply  Follow  Negotiate
+        up      (if offer)
+```
+
+## Project Structure
+
+**Your personal project** (after `npx create-job-forge my-search`):
+
+```
+my-search/
+├── package.json                 # depends on "job-forge" (github:razroo/JobForge)
+├── opencode.json                # thin config — enables MCPs + states.yml
+├── cv.md                        # your CV (personal)
+├── article-digest.md            # your proof points (optional, personal)
+├── portals.yml                  # companies you want to scan (personal)
+├── config/profile.yml           # your identity, target roles (personal)
+├── data/                        # applications, pipeline, scan history (personal, gitignored)
+├── reports/                     # generated evaluation reports (personal, gitignored)
+├── batch/
+│   ├── batch-input.tsv          # URLs to batch-evaluate (personal)
+│   ├── batch-state.tsv          # resumable batch state (personal)
+│   ├── tracker-additions/       # TSVs waiting to merge (personal)
+│   ├── logs/                    # per-worker logs (personal, gitignored)
+│   ├── batch-prompt.md          # → symlink to node_modules/job-forge/
+│   └── batch-runner.sh          # → symlink to node_modules/job-forge/
+├── modes/                       # → symlink to node_modules/job-forge/modes/
+├── templates/                   # → symlink to node_modules/job-forge/templates/
+├── .opencode/skills/job-forge.md  # → symlink to node_modules/job-forge/
+└── node_modules/job-forge/      # the harness (fetched from github:razroo/JobForge)
+```
+
+Symlinks are regenerated on every `npm install` via the package's `postinstall` hook. You never have to know about harness internals — just edit `cv.md`, `portals.yml`, and `config/profile.yml`.
+
+**The harness itself** (this repo, what gets installed into `node_modules/job-forge/`):
+
+```
+JobForge/
+├── package.json                # bin: job-forge, create-job-forge
+├── bin/
+│   ├── job-forge.mjs           # CLI dispatcher (merge/verify/pdf/tokens/sync/...)
+│   ├── sync.mjs                # postinstall: creates symlinks in consumer project
+│   └── create-job-forge.mjs    # npx create-job-forge scaffolder
+├── .opencode/skills/job-forge.md  # the skill router
+├── modes/                      # _shared.md + 16 skill modes
+├── templates/                  # cv-template.html, portals.example.yml, states.yml
+├── config/profile.example.yml  # template for consumer's profile.yml
+├── batch/batch-prompt.md       # batch worker prompt template
+├── batch/batch-runner.sh       # parallel orchestrator
+├── scripts/token-usage-report.mjs   # opencode cost analyzer
+├── tracker-lib.mjs             # shared tracker read/write helper
+├── merge-tracker.mjs           # merge batch TSVs → tracker
+├── dedup-tracker.mjs           # remove dupes
+├── verify-pipeline.mjs         # pipeline integrity checks
+├── normalize-statuses.mjs      # canonicalize status values
+├── generate-pdf.mjs            # CV PDF generator
+├── cv-sync-check.mjs           # setup lint
+├── dashboard/                  # optional Go TUI
+├── fonts/                      # Space Grotesk + DM Sans (for PDF)
+└── docs/                       # architecture, setup, customization
+```
+
+## Documentation
+
+Index and cross-links: [docs/README.md](docs/README.md).
+
+- [Setup](docs/SETUP.md) — both install paths, profile, CV, portals, verify, token tracking, troubleshooting
+- [Architecture](docs/ARCHITECTURE.md) — package architecture, modes, evaluation flow, batch runner, pipeline scripts
+- [Customization](docs/CUSTOMIZATION.md) — archetypes, scanner keywords, CV template, states, customizing symlinked modes
+- [Model Routing](docs/MODEL-ROUTING.md) — the three cost-tiered subagents, why the architecture exists, and how to swap models or add your own
+- [Contributing](CONTRIBUTING.md) — branch workflow, quality gate, and ideas for PRs
+
+## License
+
+MIT

package/batch/README.md

@@ -0,0 +1,60 @@
+# Batch evaluation
+
+The `batch/` folder holds the **parallel batch runner** for processing 10+ job URLs with headless `opencode run` workers. For how batch fits into the rest of JobForge, see [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
+
+## What ships in git
+
+| Path | Role |
+|------|------|
+| `batch-runner.sh` | Orchestrator: parallelism, state, retries, resume |
+| `batch-prompt.md` | Prompt template passed to each worker (keep evaluation and scoring instructions aligned with the canonical model in [`modes/_shared.md`](../modes/_shared.md) so batch scores match single-offer runs) |
+| `README.md` | This file |
+
+## Local-only files (gitignored when present)
+
+Per [`.gitignore`](../.gitignore): `batch-input.tsv`, `batch-state.tsv`, `logs/*`, and `tracker-additions/*.tsv`. Empty dirs (`logs/`, `tracker-additions/`) use `.gitkeep` so the tree exists in a fresh clone.
+
+## Input: `batch-input.tsv`
+
+Tab-separated UTF-8 text, with a **header row** (the runner skips the literal `id` header):
+
+| Column | Required | Description |
+|--------|----------|-------------|
+| `id` | Yes | Numeric offer id (used for state and ordering) |
+| `url` | Yes | Job posting URL |
+| `source` | No | Short label (e.g. board or company) |
+| `notes` | No | Free text for your own context |
+
+Example:
+
+```text
+id	url	source	notes
+1	https://jobs.example.com/123	greenhouse	Staff engineer
+2	https://boards.example.com/456	ashby	Remote OK
+```
+
+Create this file in **`batch/`** next to the runner (see `batch-runner.sh` constants). Then:
+
+```bash
+./batch/batch-runner.sh --dry-run   # from repo root
+./batch/batch-runner.sh
+```
+
+Options and file layout: `./batch/batch-runner.sh --help`.
+
+## After a batch run
+
+Workers write one-line TSV rows under `batch/tracker-additions/`. Merge them into your tracker from the repo root:
+
+```bash
+npm run merge
+npm run verify   # optional: pipeline health after merge (report links, statuses, pending TSVs)
+```
+
+(`node merge-tracker.mjs` — same as `npm run merge`; see [CONTRIBUTING.md](../CONTRIBUTING.md#development).)
+
+After a successful merge, each processed file is moved to **`batch/tracker-additions/merged/`** (created on first merge when the directory does not yet exist). `npm run verify` only looks for `*.tsv` files in the **top level** of `batch/tracker-additions/`, so rows already merged and archived under `merged/` do not trigger the “pending TSVs” warning.
+
+## Prerequisites
+
+The runner expects the `opencode` CLI on `PATH` and a valid `batch-prompt.md`. It creates `reports/` and tracker paths when they do not exist; ensure your usual JobForge setup (`cv.md`, `config/profile.yml`, `portals.yml`) matches what `batch-prompt.md` assumes.

package/batch/batch-prompt.md

@@ -0,0 +1,399 @@
+# job-forge Batch Worker — Full Evaluation + PDF + Tracker Line
+
+You are a job offer evaluation worker for the candidate (read name from config/profile.yml). You may receive either a **single offer** or a **bundle of offers** (the orchestrator chooses based on `--bundle-size`). For each offer you produce:
+
+1. Full A-F evaluation (report .md)
+2. Personalized ATS-optimized PDF
+3. Tracker line for later merge
+
+## Bundled mode (when the user message contains a JSON array of offers)
+
+If the user message carries an `Offers: [ ... ]` JSON array, process each offer **fully and sequentially** — do not interleave steps across offers. For each offer in order:
+
+1. Run the full pipeline below (Steps 1-6) using its `id`, `url`, `jd_file`, `report_num`, `date`.
+2. After finishing that offer, emit **exactly one single-line JSON status** to stdout with this shape:
+   ```
+   {"id":"<id>","status":"completed|failed","report_num":"<num>","company":"...","role":"...","score":<num-or-null>,"pdf":"<path-or-null>","report":"<path-or-null>","error":"<msg-or-null>"}
+   ```
+3. Move to the next offer. **Do NOT stop the bundle if one offer fails** — mark it failed and continue.
+4. The orchestrator (`batch-runner.sh`) parses these status lines to update `batch-state.tsv`. Missing status = worker didn't reach that offer = counts as failed.
+
+## Single-offer mode (legacy, when no Offers array)
+
+Read `{{URL}}`, `{{JD_FILE}}`, `{{REPORT_NUM}}`, `{{DATE}}`, `{{ID}}` from the user message and run the pipeline once. Emit the same single-line status JSON at the end.
+
+**IMPORTANT**: This prompt is self-contained. You have EVERYTHING you need here. You do not depend on any other skill or system.
+
+---
+
+## Sources of Truth (READ before evaluating)
+
+| File | Absolute path | When |
+|------|---------------|------|
+| cv.md | `cv.md (project root)` | ALWAYS |
+| llms.txt | `llms.txt (if exists)` | ALWAYS |
+| article-digest.md | `article-digest.md (project root)` | ALWAYS (proof points) |
+| i18n.ts | `i18n.ts (if exists, optional)` | Only for interviews/deep |
+| cv-template.html | `templates/cv-template.html` | For PDF |
+| generate-pdf.mjs | `generate-pdf.mjs` | For PDF |
+
+**RULE: NEVER write to cv.md or i18n.ts.** They are read-only.
+**RULE: NEVER hardcode metrics.** Read them from cv.md + article-digest.md at evaluation time.
+**RULE: For article metrics, article-digest.md takes precedence over cv.md.** cv.md may have older numbers — that's normal.
+
+---
+
+## Job-Specific Parameters (read from user message)
+
+The orchestrator passes the concrete values for this job **in the user message**, not in this prompt. This prompt is a static template shared across all workers so the opencode prompt cache can be reused — resolving per-job values here would bust the cache on every run.
+
+Look in the user message for:
+
+| Parameter | Description |
+|-----------|-------------|
+| URL | Offer URL |
+| JD file | Path to the file containing the JD text |
+| Report number | 3 digits, zero-padded (001, 002...) |
+| Date | YYYY-MM-DD |
+| Batch ID | Unique offer ID from batch-input.tsv |
+
+Everywhere this prompt writes `{{URL}}`, `{{JD_FILE}}`, `{{REPORT_NUM}}`, `{{DATE}}`, `{{ID}}`, substitute the values from the user message.
+
+---
+
+## Pipeline (execute in order)
+
+### Step 1 — Retrieve JD
+
+**Note: Batch workers do NOT have Geometra MCP/browser access.** Use WebFetch only, and fetch each URL at most once.
+
+1. Read the JD file at `{{JD_FILE}}` (provided by orchestrator)
+2. If the JD file has content, use it directly — do NOT also WebFetch the URL (the file is the source of truth)
+3. If the JD file is empty or missing, WebFetch `{{URL}}` **once**
+4. If WebFetch returns content but it looks like a shell page (no JD text, just navbar/footer), add `**Verification: unconfirmed**` to the report header and proceed — the conductor or user will verify later
+5. If both the file and WebFetch fail, report an error and stop
+
+**Never chain WebFetch + file read + second WebFetch for the same URL** — each fetch re-pulls the same tokens into context.
+
+### Step 2 — A-F Evaluation
+
+`cv.md` is already in your context via `opencode.json:instructions` — use it directly, do NOT Read it again. Execute ALL blocks:
+
+#### Step 0 — Archetype Detection
+
+Classify the offer into one of the 6 archetypes. If it's a hybrid, indicate the 2 closest ones.
+
+**The 6 archetypes (all equally valid):**
+
+| Archetype | Key themes | What they're buying |
+|-----------|------------|---------------------|
+| **AI Platform / LLMOps Engineer** | Evaluation, observability, reliability, pipelines | Someone who puts AI into production with metrics |
+| **Agentic Workflows / Automation** | HITL, tooling, orchestration, multi-agent | Someone who builds reliable agent systems |
+| **Technical AI Product Manager** | GenAI/Agents, PRDs, discovery, delivery | Someone who translates business → AI product |
+| **AI Solutions Architect** | Hyperautomation, enterprise, integrations | Someone who designs end-to-end AI architectures |
+| **AI Forward Deployed Engineer** | Client-facing, fast delivery, prototyping | Someone who delivers AI solutions to clients fast |
+| **AI Transformation Lead** | Change management, adoption, org enablement | Someone who leads AI transformation in an organization |
+
+**Adaptive framing:**
+
+> **Concrete metrics are read from `cv.md` + `article-digest.md` at each evaluation. NEVER hardcode numbers here.**
+
+| If the role is... | Emphasize about the candidate... | Proof point sources |
+|-------------------|--------------------------|--------------------------|
+| Platform / LLMOps | Production systems builder, observability, evals, closed-loop | article-digest.md + cv.md |
+| Agentic / Automation | Multi-agent orchestration, HITL, reliability, cost | article-digest.md + cv.md |
+| Technical AI PM | Product discovery, PRDs, metrics, stakeholder mgmt | cv.md + article-digest.md |
+| Solutions Architect | System design, integrations, enterprise-ready | article-digest.md + cv.md |
+| Forward Deployed Engineer | Fast delivery, client-facing, prototype → prod | cv.md + article-digest.md |
+| AI Transformation Lead | Change management, team enablement, adoption | cv.md + article-digest.md |
+
+**Cross-cutting advantage**: Frame the candidate's profile as a **"Technical builder"** who adapts their framing to the role.
+
+- For PM: "builder who reduces uncertainty with prototypes and then productionizes with discipline".
+- For FDE: "builder who delivers fast with observability and metrics from day 1".
+- For SA: "builder who designs end-to-end systems with real integration experience".
+- For LLMOps: "builder who puts AI into production with closed-loop quality systems — read metrics from article-digest.md".
+
+Turn "builder" into a professional signal, not a "hobby maker" label. The framing changes, the truth stays the same.
+
+#### Block A — Role Summary
+
+Table with: Detected archetype, Domain, Function, Seniority, Remote, Team size, TL;DR.
+
+#### Block B — CV Match
+
+`cv.md` is already in context (via `instructions`) — use it directly, do NOT Read it again. Table with each JD requirement mapped to exact CV lines or i18n.ts keys.
+
+**Adapted to archetype:**
+
+- FDE → prioritize fast delivery and client-facing.
+- SA → prioritize system design and integrations.
+- PM → prioritize product discovery and metrics.
+- LLMOps → prioritize evals, observability, pipelines.
+- Agentic → prioritize multi-agent, HITL, orchestration.
+- Transformation → prioritize change management, adoption, scaling.
+
+**Gaps** section with mitigation strategy for each one:
+1. Is it a hard blocker or a preference-only requirement?
+2. Can the candidate demonstrate adjacent experience?
+3. Is there a portfolio project that covers this gap?
+4. Concrete mitigation plan
+
+#### Block C — Level and Strategy
+
+1. **Detected level** in the JD vs **candidate's current level** (staff / senior / mid, based on title history in cv.md)
+2. **"Sell senior without lying" plan**: specific phrases, concrete achievements, founder experience as an advantage
+3. **"If I get downleveled" plan**: accept if comp is fair, 6-month review, clear criteria
+
+#### Block D — Comp and Demand
+
+Use WebSearch for current salaries (Glassdoor, Levels.fyi, Blind), company comp reputation, demand trends. Table with data and cited sources. If no data available, say so.
+
+Comp score (1-5): 5=top quartile, 4=above market, 3=median, 2=slightly below, 1=well below.
+
+#### Block E — Personalization Plan
+
+| # | Section | Current state | Proposed change | Why |
+|---|---------|---------------|-----------------|-----|
+
+Top 5 CV changes + Top 5 LinkedIn changes.
+
+#### Block F — Interview Plan
+
+6-10 STAR stories mapped to JD requirements:
+
+| # | JD Requirement | STAR Story | S | T | A | R |
+
+**Selection adapted to archetype.** Also include:
+- 1 recommended case study (which project to present and how)
+- Red-flag questions and how to answer them
+
+#### Global Score
+
+**Use the Canonical Scoring Model from `modes/_shared.md`.** All 10 dimensions, weighted exactly as defined there. This ensures scores from batch workers are directly comparable to scores from interactive evaluations and the `compare` comparison mode.
+
+**Emit the score as a single JSON block** per `_shared.md` → "Score Emission — EMIT-ONCE JSON". Do NOT also write a prose scoring table — the JSON is the only representation. The report `.md` embeds this JSON verbatim under a `## Score` section, and Blocks A-F reference it by key instead of re-enumerating the 10 dimensions.
+
+### Step 3 — Save Report .md
+
+Save the full evaluation to:
+```
+reports/{{REPORT_NUM}}-{company-slug}-{{DATE}}.md
+```
+
+Where `{company-slug}` is the company name in lowercase, no spaces, with hyphens.
+
+**Report format:**
+
+```markdown
+# Evaluation: {Company} — {Role}
+
+**Date:** {{DATE}}
+**Archetype:** {detected}
+**Score:** {X.X/5}
+**URL:** {original offer URL}
+**PDF:** job-forge/output/cv-candidate-{company-slug}-{{DATE}}.pdf
+**Batch ID:** {{ID}}
+
+---
+
+## Score
+
+{the Score JSON block from _shared.md, verbatim, inside a fenced ```json block}
+
+---
+
+## A) Role Summary
+(full content — reference scores by key, do not re-enumerate the 10 dimensions)
+
+## B) CV Match
+(full content)
+
+## C) Level and Strategy
+(full content)
+
+## D) Comp and Demand
+(full content)
+
+## E) Personalization Plan
+(full content)
+
+## F) Interview Plan
+(full content)
+
+---
+
+## Extracted Keywords
+(15-20 JD keywords for ATS)
+```
+
+### Step 4 — Generate PDF
+
+1. Read `cv.md` + `i18n.ts`
+2. Extract 15-20 keywords from the JD
+3. Detect JD language → CV language (EN default)
+4. Detect company location → paper format: US/Canada → `letter`, rest → `a4`
+5. Detect archetype → adapt framing
+6. Rewrite Professional Summary injecting keywords
+7. Select top 3-4 most relevant projects
+8. Reorder experience bullets by relevance to JD
+9. Build competency grid (6-8 keyword phrases)
+10. Inject keywords into existing achievements (**NEVER fabricate**)
+11. Generate full HTML from template (read `templates/cv-template.html`)
+12. Write HTML to `/tmp/cv-candidate-{company-slug}.html`
+13. Run:
+```bash
+node generate-pdf.mjs \
+  /tmp/cv-candidate-{company-slug}.html \
+  output/cv-candidate-{company-slug}-{{DATE}}.pdf \
+  --format={letter|a4}
+```
+14. Report: PDF path, page count, keyword coverage %
+
+**ATS rules:**
+- Single-column (no sidebars)
+- Standard headers: "Professional Summary", "Work Experience", "Education", "Skills", "Certifications", "Projects"
+- No text in images/SVGs
+- No critical info in headers/footers
+- UTF-8, selectable text
+- Keywords distributed: Summary (top 5), first bullet of each role, Skills section
+
+**Design:**
+- Fonts: Space Grotesk (headings, 600-700) + DM Sans (body, 400-500)
+- Fonts self-hosted: `fonts/`
+- Header: Space Grotesk 24px bold + cyan→purple 2px gradient + contact info
+- Section headers: Space Grotesk 13px uppercase, cyan color `hsl(187,74%,32%)`
+- Body: DM Sans 11px, line-height 1.5
+- Company names: purple `hsl(270,70%,45%)`
+- Margins: 0.6in
+- Background: white
+
+**Keyword injection strategy (ethical):**
+- Reformulate real experience using the exact vocabulary from the JD
+- NEVER add skills the candidate doesn't have
+- Example: JD says "RAG pipelines" and CV says "LLM workflows with retrieval" → "RAG pipeline design and LLM orchestration workflows"
+
+**Writing style — Anti-AI-detection (CRITICAL):**
+ATS platforms (Indeed, LinkedIn, Workday) flag AI-generated CVs. All generated text MUST read as human-written:
+- **Vary sentence length.** Mix short fragments with longer sentences. Don't make every bullet the same length.
+- **Start bullets differently.** Bullets MUST NOT all begin with a past-tense action verb — mix in noun-led and metric-led openings.
+- **Use the candidate's own phrasing from cv.md when possible.** Reformulate for keywords, but preserve their voice.
+- **NEVER use these AI-hallmark words:** "leveraged", "utilized", "spearheaded", "orchestrated" (as metaphor), "cutting-edge", "passionate about", "drive innovation", "synergy", "holistic approach", "navigate complex", "foster collaboration".
+- **Use plain, specific verbs.** "Built" not "architected". "Ran" not "orchestrated". "Fixed" not "remediated".
+- **Don't over-polish.** Real CVs have minor asymmetries — one job has 4 bullets, another has 3. Don't normalize everything.
+- **Self-check before generating HTML:** (1) Do 3+ bullets start with same word? Fix. (2) Are all bullets same length? Vary. (3) Any AI-hallmark words? Rewrite.
+
+**Template placeholders (in cv-template.html):**
+
+| Placeholder | Content |
+|-------------|---------|
+| `{{LANG}}` | `en` or `es` |
+| `{{PAGE_WIDTH}}` | `8.5in` (letter) or `210mm` (A4) |
+| `{{NAME}}` | (from profile.yml) |
+| `{{EMAIL}}` | (from profile.yml) |
+| `{{LINKEDIN_URL}}` | (from profile.yml) |
+| `{{LINKEDIN_DISPLAY}}` | (from profile.yml) |
+| `{{PORTFOLIO_URL}}` | (from profile.yml) |
+| `{{PORTFOLIO_DISPLAY}}` | (from profile.yml) |
+| `{{LOCATION}}` | (from profile.yml) |
+| `{{SECTION_SUMMARY}}` | Professional Summary / Resumen Profesional |
+| `{{SUMMARY_TEXT}}` | Personalized summary with keywords |
+| `{{SECTION_COMPETENCIES}}` | Core Competencies / Competencias Core |
+| `{{COMPETENCIES}}` | `<span class="competency-tag">keyword</span>` × 6-8 |
+| `{{SECTION_EXPERIENCE}}` | Work Experience / Experiencia Laboral |
+| `{{EXPERIENCE}}` | HTML for each job with reordered bullets |
+| `{{SECTION_PROJECTS}}` | Projects / Proyectos |
+| `{{PROJECTS}}` | HTML for top 3-4 projects |
+| `{{SECTION_EDUCATION}}` | Education / Formacion |
+| `{{EDUCATION}}` | HTML for education |
+| `{{SECTION_CERTIFICATIONS}}` | Certifications / Certificaciones |
+| `{{CERTIFICATIONS}}` | HTML for certifications |
+| `{{SECTION_SKILLS}}` | Skills / Competencias |
+| `{{SKILLS}}` | HTML for skills |
+
+### Step 5 — Tracker Line
+
+Write a single TSV line to:
+```
+batch/tracker-additions/{{ID}}.tsv
+```
+
+TSV format (single line, no header, 9 tab-separated columns):
+```
+{next_num}\t{{DATE}}\t{company}\t{role}\t{status}\t{score}/5\t{pdf_emoji}\t[{{REPORT_NUM}}](reports/{{REPORT_NUM}}-{company-slug}-{{DATE}}.md)\t{one_line_note}
+```
+
+**TSV columns (exact order):**
+
+| # | Field | Type | Example | Validation |
+|---|-------|------|---------|------------|
+| 1 | num | int | `647` | Sequential, max existing + 1 |
+| 2 | date | YYYY-MM-DD | `2026-03-14` | Evaluation date |
+| 3 | company | string | `Datadog` | Short company name |
+| 4 | role | string | `Staff AI Engineer` | Role title |
+| 5 | status | canonical | `Evaluated` | MUST be canonical (see states.yml) |
+| 6 | score | X.XX/5 | `4.55/5` | Or `N/A` if not scorable |
+| 7 | pdf | emoji | `✅` or `❌` | Whether PDF was generated |
+| 8 | report | md link | `[647](reports/647-...)` | Link to report |
+| 9 | notes | string | `APPLY HIGH...` | 1-sentence summary |
+
+**IMPORTANT:** The TSV order has status BEFORE score (col 5→status, col 6→score). In the tracker day files the order is reversed (col 5→score, col 6→status). merge-tracker.mjs handles the conversion.
+
+**Valid canonical states:** `Evaluated`, `Applied`, `Responded`, `Interview`, `Offer`, `Rejected`, `Discarded`, `SKIP`
+
+Where `{next_num}` is calculated by reading all entries across day files in `data/applications/` and taking the max entry number.
+
+### Step 6 — Final Output
+
+When finished, print a JSON summary to stdout for the orchestrator to parse (template uses `{{ID}}` / `{company}` placeholders — substitute before emitting):
+
+```
+{
+  "status": "completed",
+  "id": "{{ID}}",
+  "report_num": "{{REPORT_NUM}}",
+  "company": "{company}",
+  "role": "{role}",
+  "score": {score_num},
+  "pdf": "{pdf_path}",
+  "report": "{report_path}",
+  "error": null
+}
+```
+
+If something fails:
+```
+{
+  "status": "failed",
+  "id": "{{ID}}",
+  "report_num": "{{REPORT_NUM}}",
+  "company": "{company_or_unknown}",
+  "role": "{role_or_unknown}",
+  "score": null,
+  "pdf": null,
+  "report": "{report_path_if_exists}",
+  "error": "{error_description}"
+}
+```
+
+---
+
+## Global Rules
+
+### NEVER
+1. Fabricate experience or metrics
+2. Modify cv.md, i18n.ts, or portfolio files
+3. Share the phone number in generated messages
+4. Recommend comp below market rate
+5. Generate a PDF without reading the JD first
+6. Use corporate-speak
+7. Use AI-hallmark words: "leveraged", "utilized", "spearheaded", "orchestrated" (as metaphor), "cutting-edge", "passionate about", "drive innovation", "synergy", "holistic approach". ATS platforms flag these.
+
+### ALWAYS
+1. Read cv.md, llms.txt, and article-digest.md before evaluating
+2. Detect the role's archetype and adapt the framing
+3. Cite exact CV lines when there's a match
+4. Use WebSearch for comp and company data
+5. Generate content in the JD's language (EN default)
+6. Be direct and actionable — no fluff
+7. When generating English text (PDF summaries, bullets, STAR stories), use native tech English: short sentences, action verbs, no unnecessary passive voice, no "in order to" or "utilized"