huntpilot 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jawad Ul Hadi
+
+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

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# HuntPilot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A referral-first AI job search copilot.** It finds roles, scores your fit, writes tailored resumes and cover letters, asks for a referral before you apply cold, and keeps your tracker up to date. It drafts everything and sends nothing.
+
+HuntPilot is a set of agent templates plus a small TypeScript CLI. You fill in one profile file and render paste-ready files for **Microsoft Copilot Studio**, a **Claude Project** or a **custom GPT**.
+
+[![CI](https://github.com/JawadulHadi/job_hunt/actions/workflows/ci.yml/badge.svg)](https://github.com/JawadulHadi/job_hunt/actions/workflows/ci.yml)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+
+## What it does
+
+
+| Mode           | What you get                                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Find jobs      | Fresh roles from company boards (Greenhouse, Lever, Ashby) and remote boards, opened, scored and de-duplicated against your tracker |
+| Analyse a JD   | Requirement-by-requirement fit table, a 0–100 score, the resume variant to use, and a verdict: Apply, Referral first or Skip       |
+| Hard filters   | Skips roles you can't take (work authorization, onsite only, unpaid trials) and quotes the line that blocks you                     |
+| Tailor         | Resume bullets reordered for the role, from your facts only, in an ATS-safe single column                                           |
+| Referral first | Finds a warm route in (maintainers, blog authors, community members) and drafts a 90-word ask                                       |
+| Write          | Cover letters capped at 250 words with your one headline metric, word for word                                                      |
+| Interview prep | Likely questions, STAR outlines from your real experience, and mock interviews one question at a time                               |
+| Tracker        | Logs and updates an Excel table with stable IDs, statuses and follow-up dates                                                       |
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    P[profile.yaml<br/>your facts and targets] --> R[huntpilot render]
+    T[templates/agent<br/>instructions + 3 skills] --> R
+    R --> CS[Copilot Studio files]
+    R --> CP[Claude Project files]
+    R --> GPT[Custom GPT files]
+    R --> C[huntpilot check]
+    JD[job description] --> S[huntpilot score] --> V[score, variant, verdict, blockers]
+    X[huntpilot tracker] --> XL[JobTracker.xlsx]
+    E[evals/cases.yaml] --> EV[huntpilot evals] --> TR[test-run checklist]
+```
+
+The agent does the reading and writing. The CLI keeps the setup consistent: one profile, the same facts on every platform, and a deterministic pre-score you can run on any job description.
+
+## Quick start
+
+Requires Node.js 20 or newer.
+
+```bash
+git clone https://github.com/JawadulHadi/job_hunt.git
+cd job_hunt
+npm install
+
+cp examples/profile.example.yaml profile.yaml   # git-ignored; edit it with your own facts
+npm run render                                   # writes out/<platform>/
+npm run check                                    # unfilled placeholders, banned words, length limits
+npm run tracker                                  # writes out/JobTracker.xlsx
+npm run evals                                    # writes out/test-run.md
+npm run score -- path/to/job-description.txt     # pre-score one JD
+```
+
+Then follow the setup guide for your platform:
+
+- [Microsoft Copilot Studio](docs/setup-copilot-studio.md)
+- [Claude Project](docs/setup-claude-project.md)
+- [Custom GPT](docs/setup-custom-gpt.md)
+
+## Scoring a job description
+
+```text
+$ npm run score -- tests/fixtures/jd-us-only.txt
+Score: 75/100   Verdict: Skip   Variant: C
+
+| Area | Points | Matched |
+| --- | --- | --- |
+| Core stack | 30/30 | nestjs, typescript, postgresql |
+| Seniority | 20/20 | staff |
+| AI / LLM | 0/15 | none |
+| Supporting stack | 10/10 | graphql, redis |
+| Remote fit | 15/15 | remote |
+| Company signal | 0/10 | none |
+
+Blockers:
+- Requires US work authorization: "Candidates must be authorized to work in the United States."
+```
+
+A 75 would normally be Apply. The work-authorization line turns it into Skip, before you spend time tailoring.
+
+The rubric, thresholds and hard filters all live in your profile. See [docs/fit-scoring.md](docs/fit-scoring.md).
+
+## Test before you trust it
+
+Run the 14 cases in [evals/cases.yaml](evals/cases.yaml) against your deployed agent with your own resume and real job descriptions. `npm run evals` turns them into a checklist with your details filled in. Go live only when every critical case passes. See [docs/testing.md](docs/testing.md).
+
+## Safety rules built in
+
+- Drafts only. It never sends email or messages, and never submits applications.
+- It never overwrites your resume or any file it didn't create.
+- It never invents employers, dates, metrics or certifications. Missing facts go to a "Needs your input" list.
+- It won't guarantee legal, immigration, tax or salary outcomes.
+
+**Keep your configured agent private.** It holds your resume and can reach your files and email. Share this template, not your instance. See [docs/publishing.md](docs/publishing.md).
+
+## Repository layout
+
+```text
+templates/agent/   instructions, skills and prompts with {{profile.tokens}}
+examples/          a fictional example profile
+evals/             test cases
+src/               the huntpilot CLI (TypeScript)
+tests/             unit tests (Vitest)
+docs/              setup, scoring, testing and publishing guides
+```
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Jawad Ul Hadi

package/dist/check.js

@@ -0,0 +1,44 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { mentions } from "./score.js";
+/** Instruction field limits. Both platforms cap instructions at 8,000 characters. */
+export const INSTRUCTION_LIMITS = {
+    "copilot-studio": 8000,
+    "custom-gpt": 8000,
+};
+function walk(dir) {
+    return readdirSync(dir).flatMap((name) => {
+        const path = join(dir, name);
+        return statSync(path).isDirectory() ? walk(path) : [path];
+    });
+}
+export function checkText(file, text, bannedWords) {
+    const findings = [];
+    const leftovers = text.match(/\{\{\s*[a-zA-Z0-9_.]+\s*\}\}/g);
+    if (leftovers) {
+        findings.push({ file, level: "error", message: `Unfilled placeholders: ${[...new Set(leftovers)].join(", ")}` });
+    }
+    const bannedLine = /banned words?:/i;
+    // The line that lists the banned words is the one place they're allowed.
+    const body = text.split("\n").filter((l) => !bannedLine.test(l)).join("\n");
+    const banned = bannedWords.filter((w) => mentions(body, w));
+    if (banned.length > 0) {
+        findings.push({ file, level: "warning", message: `Uses banned words: ${banned.join(", ")}` });
+    }
+    return findings;
+}
+/** Checks rendered output under outDir: placeholders, banned words and instruction length per platform. */
+export function checkOutput(outDir, bannedWords) {
+    const findings = [];
+    for (const path of walk(outDir).filter((p) => p.endsWith(".md"))) {
+        const text = readFileSync(path, "utf8");
+        const file = relative(outDir, path);
+        findings.push(...checkText(file, text, bannedWords));
+        const [platform, name] = file.split(/[\\/]/);
+        const limit = INSTRUCTION_LIMITS[platform];
+        if (name === "instructions.md" && limit && text.length > limit) {
+            findings.push({ file, level: "error", message: `Instructions are ${text.length} characters; ${platform} allows ${limit}` });
+        }
+    }
+    return findings;
+}

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { checkOutput } from "./check.js";
+import { casesToChecklist, loadCases } from "./evals.js";
+import { loadProfile } from "./profile.js";
+import { loadAgent, PLATFORMS, renderPlatform } from "./render.js";
+import { formatResult, scoreJob } from "./score.js";
+import { buildTracker } from "./tracker.js";
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const HELP = `HuntPilot: a referral-first job search copilot
+
+Usage: huntpilot <command> [options]
+
+Commands:
+  render   Fill the agent templates with your profile, one folder per platform
+  check    Check rendered files for unfilled placeholders, banned words and length limits
+  score    Pre-score a job description file against your profile
+  tracker  Create the Excel tracker (table "Applications", key column "ID")
+  evals    Write the test checklist for your profile
+
+Options:
+  -p, --profile <file>   Profile YAML (default: profile.yaml, else examples/profile.example.yaml)
+  -o, --out <dir>        Output folder (default: out)
+  --platform <name>      ${PLATFORMS.join(" | ")} (render only; default: all)
+  --json                 Print the score as JSON (score only)
+  -h, --help             Show this help
+`;
+function defaultProfile() {
+    try {
+        readFileSync("profile.yaml");
+        return "profile.yaml";
+    }
+    catch {
+        return join(ROOT, "examples", "profile.example.yaml");
+    }
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            profile: { type: "string", short: "p" },
+            out: { type: "string", short: "o", default: "out" },
+            platform: { type: "string" },
+            json: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    const [command, arg] = positionals;
+    if (values.help || !command) {
+        console.log(HELP);
+        return 0;
+    }
+    const profilePath = values.profile ?? defaultProfile();
+    const out = values.out;
+    switch (command) {
+        case "render": {
+            const profile = loadProfile(profilePath);
+            const agent = loadAgent(join(ROOT, "templates", "agent"), profile);
+            const platforms = values.platform ? [values.platform] : PLATFORMS;
+            for (const p of platforms) {
+                if (!PLATFORMS.includes(p))
+                    throw new Error(`Unknown platform "${p}"`);
+                for (const file of renderPlatform(agent, p, out))
+                    console.log(`wrote ${file}`);
+            }
+            return 0;
+        }
+        case "check": {
+            const profile = loadProfile(profilePath);
+            const findings = checkOutput(out, profile.writing.banned_words);
+            for (const f of findings)
+                console.log(`${f.level.toUpperCase()} ${f.file}: ${f.message}`);
+            const errors = findings.filter((f) => f.level === "error").length;
+            console.log(errors ? `${errors} error(s)` : "All checks passed");
+            return errors ? 1 : 0;
+        }
+        case "score": {
+            if (!arg)
+                throw new Error("Give a job description file: huntpilot score jd.txt");
+            const result = scoreJob(readFileSync(arg, "utf8"), loadProfile(profilePath));
+            console.log(values.json ? JSON.stringify(result, null, 2) : formatResult(result));
+            return 0;
+        }
+        case "tracker": {
+            mkdirSync(out, { recursive: true });
+            const file = join(out, "JobTracker.xlsx");
+            await buildTracker(file);
+            console.log(`wrote ${file}`);
+            return 0;
+        }
+        case "evals": {
+            const profile = loadProfile(profilePath);
+            mkdirSync(out, { recursive: true });
+            const file = join(out, "test-run.md");
+            writeFileSync(file, casesToChecklist(loadCases(join(ROOT, "evals", "cases.yaml")), profile));
+            console.log(`wrote ${file}`);
+            return 0;
+        }
+        default:
+            console.error(`Unknown command "${command}"\n`);
+            console.log(HELP);
+            return 1;
+    }
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/dist/evals.js

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+import { fill } from "./render.js";
+export function loadCases(file) {
+    const data = parse(readFileSync(file, "utf8"));
+    return data.cases;
+}
+/** A markdown checklist to run by hand against the deployed agent, with the profile filled in. */
+export function casesToChecklist(cases, profile) {
+    const rows = cases.map((c) => `| [ ] | ${c.id} | ${c.critical ? "Yes" : ""} | ${fill(c.prompt, profile)} | ${fill(c.pass_when, profile)} |`);
+    return [
+        "# HuntPilot test run",
+        "",
+        "Run each prompt in the deployed agent. Tick the box when the answer meets the pass rule.",
+        "Go live only when every critical case passes and no more than 2 others fail.",
+        "",
+        "| Pass | ID | Critical | Prompt | Passes when |",
+        "| --- | --- | --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+}

package/dist/profile.js

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+const REQUIRED_PATHS = [
+    "candidate.name",
+    "candidate.title",
+    "candidate.years",
+    "candidate.core_stack",
+    "candidate.timezone",
+    "candidate.headline_metric",
+    "candidate.current_role.employer",
+    "targeting.roles",
+    "targeting.region",
+    "targeting.variants.A.name",
+    "targeting.variants.B.name",
+    "targeting.variants.C.name",
+    "scoring.areas",
+    "scoring.thresholds.apply",
+    "scoring.thresholds.referral",
+    "tracker.path",
+    "tracker.table",
+];
+export function getPath(obj, path) {
+    return path.split(".").reduce((node, key) => {
+        if (node && typeof node === "object" && key in node) {
+            return node[key];
+        }
+        return undefined;
+    }, obj);
+}
+export function validateProfile(raw) {
+    const missing = REQUIRED_PATHS.filter((p) => {
+        const value = getPath(raw, p);
+        return value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0);
+    });
+    if (missing.length > 0) {
+        throw new Error(`Profile is missing: ${missing.join(", ")}`);
+    }
+    const profile = raw;
+    const { apply, referral } = profile.scoring.thresholds;
+    if (referral > apply) {
+        throw new Error("scoring.thresholds.referral must be at or below scoring.thresholds.apply");
+    }
+    const total = profile.scoring.areas.reduce((sum, a) => sum + a.points, 0);
+    if (total !== 100) {
+        throw new Error(`scoring.areas points must add up to 100 (they add up to ${total})`);
+    }
+    profile.scoring.hard_filters ??= [];
+    profile.targeting.target_companies ??= [];
+    profile.candidate.links ??= [];
+    return profile;
+}
+export function loadProfile(file) {
+    return validateProfile(parse(readFileSync(file, "utf8")));
+}

package/dist/render.js

@@ -0,0 +1,53 @@
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getPath } from "./profile.js";
+export const PLATFORMS = ["copilot-studio", "claude-project", "custom-gpt"];
+const TOKEN = /\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g;
+function asText(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value.length ? value.map(String).join(", ") : "none listed";
+    return String(value);
+}
+/** Replaces {{dotted.path}} tokens with profile values. Unknown tokens are left in place for `check` to report. */
+export function fill(template, profile) {
+    return template.replace(TOKEN, (token, path) => asText(getPath(profile, path)) ?? token);
+}
+export function loadAgent(templateDir, profile) {
+    const read = (rel) => fill(readFileSync(join(templateDir, rel), "utf8").replace(/\r\n/g, "\n"), profile);
+    const skillDir = join(templateDir, "skills");
+    const skills = readdirSync(skillDir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => ({ name: f.replace(/\.md$/, ""), body: read(join("skills", f)) }));
+    return { instructions: read("instructions.md"), skills, prompts: read("prompts.md") };
+}
+/** Drops the YAML front matter, for platforms that take skills as plain knowledge text. */
+export function stripFrontMatter(md) {
+    return md.replace(/^---\n[\s\S]*?\n---\n+/, "");
+}
+export function renderPlatform(agent, platform, outDir) {
+    const dir = join(outDir, platform);
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    const write = (name, body) => {
+        writeFileSync(join(dir, name), body.endsWith("\n") ? body : `${body}\n`);
+        written.push(join(dir, name));
+    };
+    write("instructions.md", agent.instructions);
+    write("suggested-prompts.md", agent.prompts);
+    if (platform === "copilot-studio") {
+        // Copilot Studio skills keep their front matter: name and description decide when they trigger.
+        for (const s of agent.skills)
+            write(`skill-${s.name}.md`, s.body);
+    }
+    else {
+        // Claude Projects and custom GPTs read skills as one knowledge file.
+        const playbook = agent.skills
+            .map((s) => stripFrontMatter(s.body).trim())
+            .join("\n\n---\n\n");
+        write("skills-playbook.md", playbook);
+    }
+    return written;
+}

package/dist/score.js

@@ -0,0 +1,67 @@
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Whole-word, case-insensitive keyword match. "Node.js" and "C#" style tokens are matched literally. */
+export function mentions(text, keyword) {
+    const re = new RegExp(`(^|[^a-z0-9])${escape(keyword.toLowerCase())}($|[^a-z0-9])`, "i");
+    return re.test(text.toLowerCase());
+}
+function scoreArea(text, area) {
+    const matched = area.keywords.filter((k) => mentions(text, k));
+    const share = Math.min(matched.length / Math.max(area.need, 1), 1);
+    return { label: area.label, points: Math.round(area.points * share), max: area.points, matched };
+}
+function findBlockers(text, profile) {
+    const lines = text.split(/\r?\n/);
+    const blockers = [];
+    for (const filter of profile.scoring.hard_filters) {
+        const re = new RegExp(filter.pattern, "i");
+        const line = lines.find((l) => re.test(l));
+        if (line)
+            blockers.push({ filter: filter.name, line: line.trim() });
+    }
+    return blockers;
+}
+function pickVariant(text, profile) {
+    const { variants } = profile.targeting;
+    const ranked = ["A", "B", "C"]
+        .map((key) => ({ key, hits: variants[key].keywords.filter((k) => mentions(text, k)).length }))
+        .sort((x, y) => y.hits - x.hits);
+    // Ties keep the A, B, C order, so the lead variant wins when nothing stands out.
+    return ranked[0].key;
+}
+function companyIsTarget(text, profile) {
+    return profile.targeting.target_companies.some((c) => mentions(text, c));
+}
+/**
+ * A deterministic pre-score for a job description. The agent does the real reading;
+ * this gives the same answer every time, so you can compare roles and catch blockers fast.
+ */
+export function scoreJob(text, profile) {
+    const areas = profile.scoring.areas.map((a) => scoreArea(text, a));
+    const score = areas.reduce((sum, a) => sum + a.points, 0);
+    const blockers = findBlockers(text, profile);
+    const { apply, referral } = profile.scoring.thresholds;
+    let verdict;
+    if (blockers.length > 0 || score < referral)
+        verdict = "Skip";
+    else if (score >= apply && !companyIsTarget(text, profile))
+        verdict = "Apply";
+    else
+        verdict = "Referral first";
+    return { score, verdict, variant: pickVariant(text, profile), areas, blockers };
+}
+export function formatResult(result) {
+    const rows = result.areas.map((a) => `| ${a.label} | ${a.points}/${a.max} | ${a.matched.join(", ") || "none"} |`);
+    const blockers = result.blockers.length
+        ? result.blockers.map((b) => `- ${b.filter}: "${b.line}"`).join("\n")
+        : "- none";
+    return [
+        `Score: ${result.score}/100   Verdict: ${result.verdict}   Variant: ${result.variant}`,
+        "",
+        "| Area | Points | Matched |",
+        "| --- | --- | --- |",
+        ...rows,
+        "",
+        "Blockers:",
+        blockers,
+    ].join("\n");
+}

package/dist/tracker.js

@@ -0,0 +1,82 @@
+import ExcelJS from "exceljs";
+export const TRACKER_COLUMNS = [
+    "ID",
+    "Date Found",
+    "Company",
+    "Role",
+    "Link",
+    "Source",
+    "Location / Remote",
+    "Work Auth Rule",
+    "Fit Score",
+    "Verdict",
+    "Variant",
+    "Referral Contact",
+    "Referral Asked On",
+    "Status",
+    "Applied On",
+    "Follow-up Date",
+    "Last Update",
+    "Notes",
+];
+export const STATUSES = [
+    "Found",
+    "Referral asked",
+    "Applied",
+    "Screen",
+    "Interview",
+    "Offer",
+    "Rejected",
+    "Withdrawn",
+    "Ghosted",
+];
+const LISTS = {
+    Source: ["Manual", "Job board", "Referral", "Recruiter", "HN Who is hiring", "Company site"],
+    Verdict: ["Apply", "Referral first", "Skip"],
+    Variant: ["A", "B", "C"],
+    Status: STATUSES,
+};
+const README = [
+    "HuntPilot tracker",
+    "Keep this file where your agent's Excel tools point (default /JobSearch/JobTracker.xlsx). Table name: Applications. Key column: ID.",
+    "IDs: JS-0001, JS-0002 ... The agent lists rows, reads the highest ID and adds 1.",
+    "Verdict: Apply (score at or above your apply threshold), Referral first (between thresholds, or a target company), Skip (below, or a hard filter).",
+    "Status: Found > Referral asked > Applied > Screen > Interview > Offer, or Rejected / Withdrawn / Ghosted.",
+    "Follow-up Date: Referral asked +5 days; Applied +7 days; Interview +2 days (thank-you note).",
+    "Dates are text in YYYY-MM-DD so every connector reads them the same way.",
+    "Delete the sample row once your 'log this job' test passes.",
+];
+export async function buildTracker(file, today = new Date().toISOString().slice(0, 10)) {
+    const wb = new ExcelJS.Workbook();
+    const ws = wb.addWorksheet("Applications");
+    const sample = [
+        "JS-0001", today, "Example Co (delete me)", "Senior Backend Engineer", "https://example.com/job",
+        "Manual", "Remote - Americas", "Contractor OK", 82, "Referral first", "C", "", "", "Found", "", "", today,
+        "Sample row to test the tracker",
+    ];
+    ws.addTable({
+        name: "Applications",
+        ref: "A1",
+        headerRow: true,
+        style: { theme: "TableStyleMedium2", showRowStripes: true },
+        columns: TRACKER_COLUMNS.map((name) => ({ name, filterButton: true })),
+        rows: [sample],
+    });
+    TRACKER_COLUMNS.forEach((name, i) => {
+        ws.getColumn(i + 1).width = Math.max(10, name.length + 4);
+        const list = LISTS[name];
+        if (!list)
+            return;
+        for (let row = 2; row <= 1000; row++) {
+            ws.getCell(row, i + 1).dataValidation = {
+                type: "list",
+                allowBlank: true,
+                formulae: [`"${list.join(",")}"`],
+            };
+        }
+    });
+    const readme = wb.addWorksheet("Readme");
+    README.forEach((line) => readme.addRow([line]));
+    readme.getColumn(1).width = 120;
+    await wb.xlsx.writeFile(file);
+}

package/docs/fit-scoring.md

@@ -0,0 +1,43 @@
+# Fit scoring
+
+`huntpilot score` gives every job description a 0–100 pre-score, a resume variant and a verdict. It's deterministic: the same job description gets the same answer every time, so you can compare roles side by side. The agent uses the same rubric when it reads a job description in full.
+
+## How the score works
+
+Each rubric area in `scoring.areas` has points, keywords and `need`, the number of keyword matches for full points. Fewer matches earn a share of the points.
+
+```text
+area points = points × min(matches / need, 1)
+score       = sum of area points
+```
+
+Keywords match whole words, ignoring case, so `redis` doesn't match "rediscover".
+
+The example profile uses:
+
+| Area | Points | Need |
+| --- | --- | --- |
+| Core stack | 30 | 3 |
+| Seniority | 20 | 1 |
+| AI / LLM | 15 | 2 |
+| Supporting stack | 10 | 2 |
+| Remote fit | 15 | 1 |
+| Company signal | 10 | 2 |
+
+Points must add up to 100. The profile won't load if they don't.
+
+## Verdicts
+
+| Verdict | When |
+| --- | --- |
+| Skip | Any hard filter matches, or the score is below `thresholds.referral` |
+| Referral first | Score between the thresholds, or at least `thresholds.apply` at a company in `target_companies` |
+| Apply | Score at least `thresholds.apply`, with no blockers |
+
+## Hard filters
+
+Each filter is a case-insensitive regular expression tested line by line. The first matching line is quoted back, so you can see exactly why a role was skipped. Edit the filters to match your own situation. If you hold US work authorization, delete that filter.
+
+## Variants
+
+The variant with the most keyword matches wins. On a tie, A wins over B, and B wins over C, so your lead variant is the default.

package/docs/publishing.md

@@ -0,0 +1,29 @@
+# Publishing: private instance, public template
+
+HuntPilot has two lives, and they're published differently.
+
+| | Your instance | This template |
+| --- | --- | --- |
+| What it is | The agent with your resume, facts and tools | This repository: templates, CLI, docs, tests |
+| Who sees it | Only you | Anyone |
+| Where | Teams / Microsoft 365 Copilot with sign-in, your Claude Project, or a GPT set to "Only me" | GitHub |
+| Personal data | Yes | None. The example profile is fictional |
+
+## Why your instance stays private
+
+Your instance can read your resume and, depending on the platform, write to your tracker and draft emails. In Copilot Studio, an agent set to **No authentication** can be used by anyone who has the link and can't run tools that need user sign-in ([Microsoft Learn](https://learn.microsoft.com/microsoft-copilot-studio/publication-fundamentals-publish-channels)). The demo website is for testers only, and Microsoft says not to share its URL with customers ([Microsoft Learn](https://learn.microsoft.com/microsoft-copilot-studio/publication-connect-bot-to-web-channels)).
+
+## Rollout order
+
+1. **Build:** fill in your profile, render, check.
+2. **Private test:** run the test checklist with your own documents ([testing.md](testing.md)).
+3. **Pilot:** use it for your own applications for a week. Ask one friend to set it up from this README alone.
+4. **Publish the template:** make the repository public, pin it, and link it from your profile.
+
+## Before making the repository public
+
+- [ ] `git grep` for your name, email, employers and metrics, and confirm none of them appear
+- [ ] `profile.yaml`, `private/` and `knowledge/` are git-ignored and were never committed
+- [ ] CI is green
+- [ ] A friend completed setup from the README in under 30 minutes
+- [ ] The README's safety rules match the templates

package/docs/setup-claude-project.md

@@ -0,0 +1,29 @@
+# Set up HuntPilot as a Claude Project
+
+This takes about 10 minutes on any Claude plan that supports Projects.
+
+## 1. Render your files
+
+```bash
+cp examples/profile.example.yaml profile.yaml   # then edit it
+npm run render -- --platform claude-project
+npm run check
+```
+
+## 2. Create the project
+
+1. In Claude, select **Projects → New project** and name it **HuntPilot**.
+2. Paste `out/claude-project/instructions.md` into the project instructions.
+3. Add these to project knowledge:
+   - `out/claude-project/skills-playbook.md`
+   - your resume, base cover letter and `facts.md`
+
+## 3. Tools
+
+- Turn on **web search** for job discovery.
+- The tracker: connect a spreadsheet connector if you have one, or keep `JobTracker.xlsx` yourself and ask HuntPilot for the row to paste in.
+- Email: if you connect an email connector, keep the drafts-only rule. HuntPilot's instructions never send.
+
+## 4. Test
+
+Run `npm run evals` and work through `out/test-run.md` in a new chat in the project. See [testing.md](testing.md).

package/docs/setup-copilot-studio.md

@@ -0,0 +1,56 @@
+# Set up HuntPilot in Microsoft Copilot Studio
+
+This takes about 20 minutes. You need a Copilot Studio license that can publish agents, plus OneDrive for Business and Outlook in the same Microsoft 365 tenant.
+
+## 1. Render your files
+
+```bash
+cp examples/profile.example.yaml profile.yaml   # then edit it
+npm run render -- --platform copilot-studio
+npm run check
+npm run tracker
+```
+
+You get `out/copilot-studio/` and `out/JobTracker.xlsx`.
+
+## 2. Create the agent
+
+1. In [Copilot Studio](https://copilotstudio.microsoft.com), select **Create → New agent**, then skip the conversational setup.
+2. Name it **HuntPilot** and add a one-line description.
+3. Paste `out/copilot-studio/instructions.md` into **Instructions**. `npm run check` fails if it's over the 8,000-character limit.
+
+## 3. Add knowledge
+
+Upload your own files under **Knowledge**:
+
+- Resume (.docx or .pdf)
+- A base cover letter
+- `facts.md`: employers and dates, metrics, certifications, work authorization, comp floor, relocation. The agent uses only these facts.
+- Optional: your portfolio or case-study URL as a public website source.
+
+Don't add LinkedIn as a website source. LinkedIn blocks crawlers, so it returns nothing.
+
+## 4. Add the skills
+
+In the agent's skills section, add one skill for each `skill-*.md` file and paste in the whole file, front matter included. The `name` and `description` lines decide when each skill runs.
+
+## 5. Connect the tracker
+
+1. Upload `JobTracker.xlsx` to OneDrive at the path in your profile (default `/JobSearch/JobTracker.xlsx`).
+2. Under **Tools**, add these Excel Online (Business) actions: **List rows present in a table**, **Add a row into a table**, **Get a row**, **Update a row**.
+3. On each one, set **File** to the tracker and **Table** to `Applications`. On Get and Update, set **Key column** to `ID`. Fixed values stop the agent from guessing a file.
+4. Add **Office 365 Outlook → Draft an email message**. Don't add any "Send" action.
+5. Optional: add **OneDrive → Create file** for saving drafts. Don't add "Update file". The instructions forbid overwriting, and leaving the tool out makes that a hard rule.
+
+## 6. Turn on search and prompts
+
+- **Web search: On.** It's under the agent's knowledge or generative AI settings, depending on your Copilot Studio version. The job-discovery skill needs it.
+- **Overview → Suggested prompts:** paste the rows from `suggested-prompts.md`.
+
+## 7. Test, then publish to yourself
+
+1. Use the **Test** panel for a first pass.
+2. Select **Publish**, then **Channels → Teams and Microsoft 365 Copilot → Open the agent in Teams**. Keep **Authenticate with Microsoft** on.
+3. Run `out/test-run.md` (from `npm run evals`) in Teams. See [testing.md](testing.md).
+
+Don't switch to **No authentication**. Anyone with the link could then use your agent, and tools that need your sign-in stop working ([Microsoft Learn](https://learn.microsoft.com/microsoft-copilot-studio/publication-fundamentals-publish-channels)).

package/docs/setup-custom-gpt.md

@@ -0,0 +1,27 @@
+# Set up HuntPilot as a custom GPT
+
+This takes about 10 minutes and needs a ChatGPT plan that can create GPTs.
+
+## 1. Render your files
+
+```bash
+cp examples/profile.example.yaml profile.yaml   # then edit it
+npm run render -- --platform custom-gpt
+npm run check
+```
+
+## 2. Create the GPT
+
+1. Select **Explore GPTs → Create → Configure**.
+2. Name it **HuntPilot** and paste `out/custom-gpt/instructions.md` into **Instructions**. `npm run check` keeps it under the 8,000-character limit.
+3. Under **Knowledge**, upload `skills-playbook.md`, your resume, base cover letter and `facts.md`.
+4. Under **Capabilities**, turn on **Web search**.
+5. Add the rows from `suggested-prompts.md` as conversation starters.
+
+## 3. Sharing
+
+Set the GPT to **Only me**. It contains your resume and facts. To share HuntPilot, share this repository instead.
+
+## 4. Test
+
+Run `npm run evals` and work through `out/test-run.md`. See [testing.md](testing.md).

package/docs/testing.md

@@ -0,0 +1,34 @@
+# Testing HuntPilot with your own documents
+
+Test privately before you rely on HuntPilot for real applications. The unit tests (`npm test`) cover the CLI. This guide covers the agent itself.
+
+## What you need
+
+- Your real resume, cover letter and `facts.md`, uploaded to the agent
+- Five real job descriptions:
+  - 2 strong fits for Variant A or C
+  - 2 strong fits for Variant B
+  - 1 role with a hard-filter blocker, such as a work-authorization line you don't meet
+
+## Run it
+
+```bash
+npm run evals   # writes out/test-run.md with your profile filled in
+```
+
+Work through `out/test-run.md` in the deployed agent, in a fresh conversation for each area. Tick each case that meets its pass rule.
+
+## Pass rule
+
+- **Every critical case passes.** These cover invented facts, hard filters, the tracker, file safety and never sending email.
+- **At most 2 other cases miss.** Fix the profile or a template, render again, and re-run those cases.
+
+## What to look for beyond the checklist
+
+- Any number, date or employer you can't find in your own files. That's an invented fact, and it fails J6 even if J6 passed.
+- The headline metric worded differently anywhere.
+- Job discovery listing a role whose page it didn't open.
+
+## After launch
+
+For the first two weeks, review 10 conversations a week. Turn every miss into a new case in `evals/cases.yaml`.

package/examples/profile.example.yaml

@@ -0,0 +1,97 @@
+# HuntPilot profile: everything the agent knows about you and what you're looking for.
+# Copy to profile.yaml (git-ignored) and replace every value with your own.
+# This example is a fictional candidate.
+
+candidate:
+  name: Alex Rivera
+  title: Backend Lead / Architect
+  years: 7
+  core_stack: [NestJS, TypeScript, PostgreSQL, GraphQL, BullMQ, Redis, RAG, LLM integration]
+  timezone: UTC+1
+  working_hours: EST
+  home_country: Portugal
+  current_role:
+    employer: Example Systems
+    start: Jan 2024
+  # One headline metric, one phrasing. The agent uses it word for word everywhere.
+  headline_metric: "70% p95 latency drop (5s → 1.5s)"
+  other_metrics:
+    - 40% fewer integration incidents
+    - 99.95% API uptime
+  case_study:
+    title: Keeping an LLM feature up when the provider goes down
+    url: https://example.com/llm-failover-case-study
+  # Optional: other public pages the agent may link, as "Label: URL".
+  links:
+    - "Credentials: https://example.com/credentials"
+
+targeting:
+  roles: [Backend Lead, Backend Architect, AI Engineer, Senior Backend Engineer]
+  region: US/Canada
+  variants:
+    A:
+      name: Backend Lead / Architect
+      focus: leadership, architecture, multi-tenant SaaS, owning microservices
+      keywords: [lead, architect, architecture, ownership, mentor, multi-tenant, microservices, staff, principal]
+    B:
+      name: AI / LLM Engineer
+      focus: provider-agnostic LLM layer, RAG, failure handling
+      keywords: [llm, rag, ai engineer, embeddings, vector, openai, anthropic, prompt, agents, evals]
+    C:
+      name: Senior Backend Engineer
+      focus: PostgreSQL, GraphQL, event-driven throughput, BullMQ, Redis
+      keywords: [postgresql, postgres, graphql, event-driven, kafka, bullmq, redis, queues, throughput, api]
+  # Companies where you'd always rather go in through a referral.
+  target_companies: []
+
+scoring:
+  thresholds:
+    apply: 75
+    referral: 60
+  # Points must add up to 100.
+  areas:
+    - label: Core stack
+      points: 30
+      need: 3
+      keywords: [nestjs, node.js, nodejs, typescript, postgresql, postgres]
+    - label: Seniority
+      points: 20
+      need: 1
+      keywords: [senior, staff, lead, principal, architect]
+    - label: AI / LLM
+      points: 15
+      need: 2
+      keywords: [llm, rag, ai, embeddings, vector, agents, openai, anthropic]
+    - label: Supporting stack
+      points: 10
+      need: 2
+      keywords: [graphql, bullmq, redis, kafka, event-driven, queues, microservices]
+    - label: Remote fit
+      points: 15
+      need: 1
+      keywords: [remote, worldwide, anywhere, distributed, async, americas]
+    - label: Company signal
+      points: 10
+      need: 2
+      keywords: [product, platform, saas, customers, series a, series b, engineering team]
+  # Any match means Skip. Edit these to match your own work authorization.
+  hard_filters:
+    - name: Requires US work authorization
+      pattern: "(must|need to|required to) (be )?(legally )?authori[sz]ed to work in the (us|u\\.s\\.|united states)"
+    - name: Must live in the US or Canada
+      pattern: "must (reside|live|be located|be based) in the (us|u\\.s\\.|united states|canada)"
+    - name: Citizenship or clearance
+      pattern: "(us citizen(ship)?|green card|security clearance|ts/sci)"
+    - name: No visa sponsorship (and no contractor option)
+      pattern: "(no|not able to|unable to|cannot) (provide |offer )?(visa )?sponsor"
+    - name: Onsite only
+      pattern: "(onsite|on-site|in office) (only|required)|no remote"
+
+tracker:
+  path: /JobSearch/JobTracker.xlsx
+  table: Applications
+
+writing:
+  banned_words: [passionate, results-driven, leverage, cutting-edge, rockstar, synergy]
+  cover_letter_max_words: 250
+  outreach_max_words: 90

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "huntpilot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "HuntPilot: a referral-first AI job search copilot. Templates, fit scoring and a tracker you can deploy to Copilot Studio, Claude Projects or a custom GPT.",
+  "license": "MIT",
+  "author": "Jawad Ul Hadi",
+  "type": "module",
+  "bin": {
+    "huntpilot": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "cli": "npm run -s build && node dist/cli.js",
+    "render": "npm run -s cli -- render",
+    "check": "npm run -s cli -- check",
+    "score": "npm run -s cli -- score",
+    "tracker": "npm run -s cli -- tracker",
+    "evals": "npm run -s cli -- evals",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "exceljs": "4.4.0",
+    "yaml": "2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.2",
+    "typescript": "5.6.3",
+    "vitest": "2.1.8"
+  }
+}

package/templates/agent/instructions.md

@@ -0,0 +1,52 @@
+You are HuntPilot, the job search copilot for {{candidate.name}}, a {{candidate.title}} with {{candidate.years}}+ years in {{candidate.core_stack}}. They are based in {{candidate.timezone}} and can work {{candidate.working_hours}} hours.
+
+GOAL
+Get {{candidate.name}} interviews for {{targeting.roles}} roles, mainly {{targeting.region}} remote. Referrals come first; cold applications are the backup.
+
+SOURCE OF TRUTH
+- Use only facts from the knowledge files (resume, cover letter, certifications, facts.md) and the candidate's own public pages. Never invent employers, dates, metrics, tools, team sizes or certifications.
+- One title everywhere: "{{candidate.title}}".
+- One headline metric, one phrasing: "{{candidate.headline_metric}}". Other approved figures: {{candidate.other_metrics}}.
+- Current role: {{candidate.current_role.employer}}, {{candidate.current_role.start}} – Present.
+- Case study: "{{candidate.case_study.title}}" at {{candidate.case_study.url}}. Link it whenever the role touches what it proves.
+- Other public pages: {{candidate.links}}. Link only the one that backs the point you are making.
+- If facts.md is present, it wins over every other file, and its metric phrases are used word for word.
+- If a fact is missing or two files disagree, stop and ask. Never pick silently.
+
+MODES (ask which one if unclear)
+1. Find jobs: use the job-discovery skill.
+2. Analyse JD: fit table, score, variant, verdict. Use the job-application-workflow skill.
+3. Tailor resume: Variant A ({{targeting.variants.A.name}}), B ({{targeting.variants.B.name}}) or C ({{targeting.variants.C.name}}). Same facts, reordered.
+4. Cover letter: max {{writing.cover_letter_max_words}} words.
+5. Referral / outreach: use the referral-first skill. Max {{writing.outreach_max_words}} words.
+6. Interview prep and mock interviews.
+7. Tracker: log, update and review applications.
+
+TRACKER RULES
+- The tracker is the Excel file {{tracker.path}}, table "{{tracker.table}}", key column "ID".
+- Before adding a row, list rows and check Company + Role so you never log a duplicate.
+- New IDs are JS-0001, JS-0002, and so on: read the highest ID and add 1.
+- Dates are text in YYYY-MM-DD.
+- To update a row, use the key column ID. Change only the columns the user asked for, plus Last Update.
+- Never create a new table. If the tracker can't be found, say so and stop.
+
+FILE AND EMAIL SAFETY
+- Never overwrite the resume, the cover letter or any file you didn't create in this conversation.
+- Save new documents as new files named Company_Role_Type_YYYY-MM-DD.
+- Email and messages: drafts only, never send. Never submit applications.
+- Ask before every tracker write, file save or email draft. One confirmation can cover all three.
+
+WRITING RULES
+- Every bullet needs a number or a named system. No filler adjectives.
+- Banned words: {{writing.banned_words}}.
+- Sound like a senior engineer: direct, specific, calm.
+- Mention {{candidate.working_hours}} overlap only for remote roles in {{targeting.region}}, never for local roles in {{candidate.home_country}}.
+
+OUTPUT STYLE
+- Be concise. Use tables for fit analysis and job lists. No long intros.
+- End with a short "Needs your input" list when anything is unverified.
+
+SCOPE
+- In: job search, resumes, cover letters, outreach, interview prep, company research, the tracker.
+- Out: legal, immigration, tax or salary-negotiation guarantees. Say so briefly and suggest a professional.
+- Don't guess salary expectations, visa status or relocation. Use facts.md or ask.

package/templates/agent/prompts.md

@@ -0,0 +1,10 @@
+# Suggested prompts
+
+| Title | Prompt |
+| --- | --- |
+| Find roles | Find 10 remote {{targeting.variants.A.name}} or {{targeting.variants.B.name}} roles posted in the last 14 days and score them. |
+| Check a JD | Here's a job description. Score my fit and pick the resume variant: [paste JD] |
+| Referral ask | Find a referral route for the top role in my tracker and draft the ask. |
+| Cover letter | Write a cover letter for [Company] [Role]. |
+| Mock interview | Mock interview me for a {{targeting.variants.B.name}} role, one question at a time. |
+| Weekly review | Summarize my tracker this week: found, referral asks, applied, replies, interviews, and what to change. |

package/templates/agent/skills/job-application-workflow.md

@@ -0,0 +1,62 @@
+---
+name: job-application-workflow
+description: Analyze a job description, score fit, pick the resume variant, and draft tailored resume bullets, cover letters or interview prep using only knowledge-file facts. Use when the user pastes a JD or job link, names a company, or asks for application or interview help.
+---
+
+# Job Application Workflow
+
+## Steps
+
+1. Identify the input: pasted JD, job URL, company name, or interview request. If a URL can't be read, ask for the pasted text.
+2. Extract: title, seniority, must-haves, nice-to-haves, stack keywords, location and timezone rules, work-authorization rules, comp if listed, red flags.
+3. Apply the hard filters (below). If one fails, the verdict is Skip: quote the exact line from the JD and stop unless the user asks to continue.
+4. Map each must-have to evidence in the knowledge files. Label it Strong, Partial or Gap.
+5. Score fit 0–100 with the rubric. Show the breakdown.
+6. Choose the variant:
+   - A: {{targeting.variants.A.name}} ({{targeting.variants.A.focus}})
+   - B: {{targeting.variants.B.name}} ({{targeting.variants.B.focus}})
+   - C: {{targeting.variants.C.name}} ({{targeting.variants.C.focus}})
+7. Give the verdict: Apply ({{scoring.thresholds.apply}}+), Referral first ({{scoring.thresholds.referral}} up to but not including {{scoring.thresholds.apply}}, or {{scoring.thresholds.apply}}+ at a target company: {{targeting.target_companies}}), Skip (below {{scoring.thresholds.referral}} or a hard filter fails).
+8. Produce what was asked for (limits below).
+9. Verify before output: every number, tool, date and employer must exist in the knowledge files. Move anything unverified to "Needs your input".
+10. Offer next actions: log in the tracker, start a referral ask, save a draft. Do them only after the user approves.
+
+## Hard filters (any one = Skip)
+
+- Requires citizenship, a green card, security clearance, or local work authorization the candidate doesn't have (check facts.md), with no contractor or employer-of-record option.
+- Onsite or hybrid only, outside {{candidate.home_country}}.
+- Unpaid trial work, or a take-home over 8 hours before any conversation.
+- Comp clearly below the floor in facts.md.
+- Required working hours that don't overlap {{candidate.working_hours}}.
+
+## Fit rubric (100 points)
+
+| Area | Points | Full marks when |
+| --- | --- | --- |
+| Core stack | 30 | The candidate's core stack ({{candidate.core_stack}}) is a must-have |
+| Seniority | 20 | Senior, Staff, Lead or Architect, with ownership of design |
+| AI / LLM | 15 | LLM integration, RAG or AI reliability in scope |
+| Supporting stack | 10 | Queues, caching, event-driven or GraphQL work |
+| Remote fit | 15 | Remote for {{targeting.region}} or worldwide, async-friendly |
+| Company signal | 10 | Product company, clear scope, real engineering team |
+
+## Output limits
+
+- Fit analysis: table Requirement | Evidence | Fit, then score, variant, verdict, 3 gaps, 5 keywords to mirror.
+- Resume: same facts, reordered. Headline, 3-line summary, skills that match the JD, then bullets as action + named system + number. Single column, standard headings (Summary, Skills, Experience, Projects, Education, Certifications), no tables or text boxes.
+- Cover letter: max {{writing.cover_letter_max_words}} words. A specific hook about the company's product, one quantified proof point ("{{candidate.headline_metric}}" by default), one sentence on fit, short close.
+- Interview prep: likely questions (system design, stack depth, failure handling, leadership) with STAR outlines from real experience only. Mock mode: one question at a time, wait, then give strengths, gaps and a tighter version.
+
+## Examples
+
+**Paste a JD.** "Senior backend role at a US fintech. Fit?" Return the fit table, score, variant, verdict, 3 gaps, 5 keywords, then ask whether to tailor the resume, write the cover letter or start a referral ask.
+
+**Authorization blocker.** JD says "Must reside in the US." Verdict Skip, quote that line, one sentence why. Don't tailor anything.
+
+**Missing fact.** "Add team size to my cover letter." If team size isn't in the files, ask for it. Don't invent it.
+
+## Notes
+
+- Titles below Lead: use Variant C but keep the headline.
+- Local roles in {{candidate.home_country}}: drop the timezone pitch, keep the same facts.
+- Conflicting metrics, dates or titles across files: stop and ask.

package/templates/agent/skills/job-discovery.md

@@ -0,0 +1,29 @@
+---
+name: job-discovery
+description: Search the web for fresh roles that fit the candidate, score them, remove duplicates and offer to log them in the tracker. Use when the user asks to find, search for or list jobs or roles.
+---
+
+# Job Discovery
+
+## Steps
+
+1. Confirm the target if unclear: variant (A, B, C or any), how many roles (default 10), and how recent (default 14 days).
+2. Search company job boards and remote boards with queries built from the target roles ({{targeting.roles}}) and core stack ({{candidate.core_stack}}). Patterns:
+   - `"<role>" <stack keyword> remote site:boards.greenhouse.io`
+   - `"<role>" <stack keyword> remote site:jobs.lever.co`
+   - `"<role>" <stack keyword> remote site:jobs.ashbyhq.com`
+   - `<stack keyword> remote "worldwide" OR "{{targeting.region}}" site:weworkremotely.com`
+   - `"<role>" remote site:wellfound.com`
+   - `"Who is hiring" <stack keyword> REMOTE site:news.ycombinator.com` (current month's thread)
+3. Open each posting before scoring it. A search snippet is not enough. Skip postings older than the window or already closed.
+4. List tracker rows and drop any Company + Role already logged.
+5. Score each role with the job-application-workflow rubric and hard filters.
+6. Return a table sorted by score: Company | Role | Remote rule | Score | Variant | Verdict | Link.
+7. Ask: "Log the Apply and Referral-first roles in the tracker?" On yes, add rows with Status "Found", Source "Job board", and today's date.
+
+## Rules
+
+- Never list a role you didn't open.
+- Never apply, sign up or message anyone.
+- If a site blocks reading, say so and move on.
+- Prefer company career pages (Greenhouse, Lever, Ashby) over aggregators. They're the original source and show the real location rules.

package/templates/agent/skills/referral-first.md

@@ -0,0 +1,30 @@
+---
+name: referral-first
+description: For a role worth pursuing, find a warm route in (open-source maintainers, engineering blog authors, community members), draft a short referral ask and track it before any cold application. Use when the user asks for a referral, an intro, outreach, or what to do next on a role.
+---
+
+# Referral First
+
+## Steps
+
+1. Take the role from the tracker or the conversation. It should have the verdict Apply or Referral first.
+2. Find up to 3 contact routes, best first:
+   - Engineers at the company who maintain or contribute to public repos in the candidate's stack ({{candidate.core_stack}}). Check the company's GitHub org.
+   - Authors of the company's engineering blog posts in the candidate's area.
+   - People the candidate shares a community with: framework Discords, GitHub discussions, Stack Overflow tags.
+   - Fallback: the hiring manager or recruiter named in the posting.
+3. For each route, give the person's public role and the specific reason to contact them (a repo, a post, a discussion). Never guess a personal email address.
+4. Draft the ask, max {{writing.outreach_max_words}} words:
+   - Line 1: the specific reason (their repo, post or talk).
+   - Line 2: one proof point. Default: "{{candidate.headline_metric}}". Use the case study when it fits the role.
+   - Line 3: one clear ask: a 15-minute chat, or a referral for the role (with link).
+   - No flattery, no "I hope this finds you well", no banned words.
+5. Offer to save it as an email draft, or show it for the user to paste into LinkedIn or GitHub.
+6. After the user confirms they sent it, update the tracker: Referral Contact, Referral Asked On = today, Status = "Referral asked", Follow-up Date = today + 5 days.
+7. If there's no reply by the follow-up date, suggest the cold application with the tailored variant, and set Status "Applied" once the user confirms.
+
+## Rules
+
+- Drafts only. The user sends every message.
+- One ask per person per role, and at most one follow-up nudge.
+- Track every ask, so the weekly review can compare referral asks with cold applications.