# Job Automation Agent

ATS resume tailoring system: Chrome extension + HuggingFace server pipeline.
Extracts JDs from job boards, generates tailored resumes via LLM pool, returns compiled PDFs.

## Scope Lock

Do NOT redesign the ATS extractor, scorer, evidence gate, or rewriting architecture.
Do NOT work on V2 (multi-agent natural tailoring). Current work is V3 bulk generation.

## Security

- Never hard-code API tokens into committed JS/manifest/packaged assets
- Never expose server filesystem paths to the client
- Sanitize compiler output before returning it
- Disable shell escape in LaTeX, use unique temp dirs, apply strict compilation timeouts

## Extension Architecture (MV3)

### Files

| File | Role |
|------|------|
| `extension/manifest.json` | MV3 manifest, `<all_urls>` content script, side panel |
| `extension/content.js` | JD extraction + job card scanning, runs on every page |
| `extension/popup/popup.js` | Side panel UI: single gen, bulk gen, results, editors |
| `extension/popup/popup.html` | Side panel markup (380px popup, 100% sidepanel) |
| `extension/background.js` | Service worker: generation lifecycle, SSE streaming, storage persistence |
| `extension/options/options.html` | Settings: API URL/token, resume LaTeX, gen version, autofill profile |
| `extension/default_resume.js` | Fallback LaTeX resume (`self.DEFAULT_RESUME_LATEX`) |

### Content Script Message Types

| Message | Handler | Async |
|---------|---------|-------|
| `EXTRACT_JD` | `extractJD()` platform router | no |
| `SCAN_JOB_CARDS` | `scanJobCards()` / `scanJobCardsLinkedIn()` | no |
| `NAVIGATE_EXTRACT_JOB` | `navigateAndExtractJD(jobId)` — LinkedIn pushState | yes (`return true`) |
| `FETCH_EXTRACT_JOB` | `fetchExtractJD(url)` — background fetch+parse | yes |
| `CLICK_AND_EXTRACT_JOB` | `clickAndExtractJob(index)` — click card fallback | yes |
| `SCAN_FORM` | `scanApplicationFields()` | no |
| `APPLY_FORM_FILL` | `applyAutofillAnswers(answers)` | no |

### LinkedIn Bulk Extraction (V3)

LinkedIn uses SDUI (Server-Driven UI) with virtualized rendering:
- `li[data-occludable-job-id]` elements exist for all 25 jobs but only ~7 visible ones have content
- Programmatic scroll does NOT trigger hydration
- **Solution:** `scanJobCardsLinkedIn()` reads job IDs from ALL `<li>` elements (even empty placeholders).
  `navigateAndExtractJD(jobId)` uses `history.pushState` to set `currentJobId` in the URL +
  `dispatchEvent(popstate)` to trigger LinkedIn's SPA router. Detail pane updates with full JD.
- No clicking, no navigation, no profile redirects.
- `#job-details` element contains the full JD text in the detail pane.
- `expandDetailPane()` clicks only `<button>` "show more" elements (never `<a>` links — those navigate to company pages).

### Bulk Generation Flow (popup.js)

1. `checkBulkAvailable()` runs on init — requires `genVersionDefault === 'v3'` AND URL matches `BULK_HOSTS`
2. Sends `SCAN_JOB_CARDS` to content script; shows button if `jobs.length > 1`
3. `handleBulkGenerate()` processes jobs sequentially:
   - LinkedIn (has `job_id`): `NAVIGATE_EXTRACT_JOB`
   - Others: `FETCH_EXTRACT_JOB` then `CLICK_AND_EXTRACT_JOB` fallback
4. Each extracted JD → `generateForBulkJob()` → SSE stream → result saved
5. Bulk history persisted in `ats_bulk_history` (max 5 runs, LaTeX/PDF stripped for quota)

### Platform Support

| Platform | Scan | Extract | Method |
|----------|------|---------|--------|
| LinkedIn | `data-occludable-job-id` | pushState + `#job-details` | SPA router |
| Indeed | CSS card selectors | `#jobDescriptionText` | fetch or click |
| Naukri | CSS card selectors | `.job-desc` | fetch or click |
| Glassdoor | CSS card selectors | `[data-test="job-details-container"]` | fetch |
| IIMJobs | CSS card selectors | generic | fetch |
| Generic | text-density heuristic | densest block | direct |

### Server Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/health` | GET | Connection check |
| `/api/generate-application-stream` | POST (multipart) | SSE resume generation |
| `/api/generate-stream` | POST | SSE generation (background.js) |
| `/api/generate` | POST | Blocking fallback |
| `/api/compile-resume` | POST | LaTeX recompile |
| `/api/compile-cover-letter` | POST | CL LaTeX recompile |
| `/api/repair-with-feedback` | POST | Feedback-based repair |
| `/api/form-assist` | POST | AI form field answers |

### Storage Keys

| Key | Purpose |
|-----|---------|
| `api_url`, `api_token` | Server connection |
| `resume_latex`, `resume_b64` | User's resume (LaTeX preferred, PDF fallback) |
| `default_cover_letter_latex` | CL template |
| `gen_version_default` | `v3`/`v2`/`v1` — controls bulk visibility |
| `ats_app_results` | Per-URL result cache (max 10) |
| `ats_bulk_history` | Bulk run history (max 5) |
| `autofill_profile_json` | 16-field profile for form autofill |

## Scoring & Honesty Contract (V1)

The score is a **percentage of what the JD actually asks for**. Invariants — breaking
any of these is how the pipeline previously reported a fabricated 90–100:

1. **Denominators include gaps.** Coverage is `present_in_final / ALL_JD_criteria`, never
   `/ supported_subset`. Dividing by the supported subset made "2 of 26 must-haves" = 100%.
2. **No free points.** A category the JD does not mention is dropped and its weight
   redistributed — never scored `1.0`. Never default a missing component to full marks.
3. **Criticality comes from the JD**, not from our `calibration_weight`. Calibration
   up-ranks what the résumé already evidences, so scoring off it is self-grading.
4. **Tool gaps are never written; competency gaps go to Skills.** Claiming a specific
   tool/platform the resume never mentions IS fabrication (the old "LinkedIn Ads" bug).
   But soft skills, responsibilities, domain knowledge, and core competencies are placed
   into the Skills section — a senior PM/founder has these skills even if the resume
   doesn't list every one. Years, degrees, and certifications stay blocked.
5. **Never re-calibrate on post-placement text.** An inserted keyword is not evidence.
   Calibration stays anchored to the ORIGINAL résumé.
6. **Truthful ≠ readable.** `verify_rewrite` runs `_reads_naturally()`; a rewrite whose
   tokens are all legitimate can still be nonsense ("communication **skills** cadence").
7. **Never round-trip LaTeX through plain text.** Use `_surgical_latex_edit()`; re-escaping
   stripped text turns `\textrightarrow` into `\textbackslash{}` and loses `\textbf{}`.
8. **Partial evidence needs same-statement co-occurrence.** Whole-document token matching
   combined `linkedin.com` (contact line) + "Ads" into a fabricated "LinkedIn Ads".

With competency gap placement, an honest score lands in the 65–85 band. Remaining gaps
are tool/platform-specific skills and hard constraints (years, degrees). The ceiling
reflects the max reachable score; score == ceiling means the résumé is maxed out.

Keyword extraction must yield **searchable noun phrases**. `_is_ats_keyword()` rejects by
shape (parentheticals, clause markers, pronouns, weak/verb heads, dangling function words),
never by topic, so unfamiliar real skills still pass.

## Development

### Build Extension Zip

```powershell
Compress-Archive -Path "extension\*" -DestinationPath "resume-tailor-extension-v{VERSION}.zip" -Force
```

### Version Bump Checklist

1. `extension/manifest.json` — bump `version`
2. `HISTORY.md` — add entry at top
3. Build zip with new version number

### Key Gotchas

- LinkedIn SDUI: CSS classes are hashed/random, never rely on them. Use `data-*` attributes and semantic selectors.
- `expandDetailPane()` must NEVER click `<a>` tags — LinkedIn "Show more" links navigate to company pages.
- Content script double-injection guard: `window.__atsContentScriptLoaded` prevents duplicate listeners.
- Service worker keepalive: `startKeepAlive()` pings every 20s during long SSE fetches to prevent MV3 suspension.
- `fetchExtractJD()` returns SPA shell for LinkedIn (not full JD) — that's why LinkedIn uses pushState instead.