job-forge 2.0.0

package/config/profile.example.yml

@@ -0,0 +1,67 @@
+# JobForge Profile Configuration
+# Copy this file to config/profile.yml and fill in your details.
+# This is the single source of truth for your personal data across all modes.
+
+candidate:
+  full_name: "Jane Smith"
+  email: "jane@example.com"
+  phone: "+1-555-0123"
+  location: "San Francisco, CA"
+  linkedin: "linkedin.com/in/janesmith"
+  portfolio_url: "https://janesmith.dev"
+  github: "github.com/janesmith"
+  twitter: "https://x.com/janesmith"
+
+target_roles:
+  # Your North Star roles — what you're optimizing for
+  primary:
+    - "Senior AI Engineer"
+    - "Staff ML Engineer"
+  # Archetypes help the evaluation system score fit
+  archetypes:
+    - name: "AI/ML Engineer"
+      level: "Senior/Staff"
+      fit: "primary"        # primary = dream role, secondary = good fit, adjacent = stretch
+    - name: "AI Product Manager"
+      level: "Senior"
+      fit: "secondary"
+    - name: "Solutions Architect"
+      level: "Mid-Senior"
+      fit: "adjacent"
+
+narrative:
+  # Your professional headline (1 line)
+  headline: "ML Engineer turned AI product builder"
+  # Your exit story — what makes you unique
+  exit_story: "Built and sold my SaaS after 5 years. Now focused on applied AI at scale."
+  # Your top 3-5 superpowers
+  superpowers:
+    - "End-to-end ML pipelines"
+    - "Fast prototyping (idea to prod in 2 weeks)"
+    - "Cross-functional communication"
+  # Proof points — projects, articles, case studies with measurable impact
+  proof_points:
+    - name: "Project Alpha"
+      url: "https://janesmith.dev/project-alpha"
+      hero_metric: "Reduced inference latency 40%"
+    - name: "Open Source Tool"
+      url: "https://github.com/janesmith/tool"
+      hero_metric: "2K+ GitHub stars"
+  # Optional: dashboard/demo URL with credentials
+  # dashboard:
+  #   url: "https://janesmith.dev/demo"
+  #   password: "demo-2026"
+
+compensation:
+  target_range: "$150K-200K"     # Your target total comp
+  currency: "USD"
+  minimum: "$120K"               # Walk-away number
+  location_flexibility: "Remote preferred, 1 week/month on-site possible"
+
+location:
+  country: "United States"
+  city: "San Francisco"
+  timezone: "PST"
+  visa_status: "No sponsorship needed"
+  # For remote roles outside your country:
+  # onsite_availability: "1 week/month in any city"

package/cv-sync-check.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+/**
+ * cv-sync-check.mjs — Validates that the job-forge setup is consistent.
+ *
+ * Checks:
+ * 1. cv.md exists
+ * 2. config/profile.yml exists and has required fields
+ * 3. No hardcoded metrics in _shared.md or batch/batch-prompt.md
+ * 4. article-digest.md freshness (if exists)
+ *
+ * Usage:
+ *   node cv-sync-check.mjs
+ *   npm run sync-check
+ *   npm run sync-check -- --help
+ */
+
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Consumer's project root. When installed as a package, we operate on cwd.
+const projectRoot = process.env.JOB_FORGE_PROJECT || process.cwd();
+// Harness dir (where shipped files like modes/_shared.md live). When installed
+// as a package, the consumer has modes/ as a symlink, so either path resolves.
+const harnessRoot = __dirname;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`cv-sync-check.mjs — optional setup lint for a personalized clone
+
+Checks that cv.md and config/profile.yml exist, scans modes/_shared.md and
+batch/batch-prompt.md for lines that look like hardcoded metrics, and warns
+if article-digest.md is stale when present.
+
+Usage:
+  node cv-sync-check.mjs
+  npm run sync-check
+
+Exits with code 1 if cv.md or config/profile.yml is missing; exits 0 when
+those exist (warnings only). Not part of the default PR gate — see CONTRIBUTING.md.
+
+Run from the repository root.`);
+  process.exit(0);
+}
+
+const warnings = [];
+const errors = [];
+
+// 1. Check cv.md exists
+const cvPath = join(projectRoot, 'cv.md');
+if (!existsSync(cvPath)) {
+  errors.push('cv.md not found in project root. Create it with your CV in markdown format.');
+} else {
+  const cvContent = readFileSync(cvPath, 'utf-8');
+  if (cvContent.trim().length < 100) {
+    warnings.push('cv.md seems too short. Make sure it contains your full CV.');
+  }
+}
+
+// 2. Check profile.yml exists
+const profilePath = join(projectRoot, 'config', 'profile.yml');
+if (!existsSync(profilePath)) {
+  errors.push('config/profile.yml not found. Copy from config/profile.example.yml and fill in your details.');
+} else {
+  const profileContent = readFileSync(profilePath, 'utf-8');
+  const requiredFields = ['full_name', 'email', 'location'];
+  for (const field of requiredFields) {
+    if (!profileContent.includes(field) || profileContent.includes(`"Jane Smith"`)) {
+      warnings.push(`config/profile.yml may still have example data. Check field: ${field}`);
+      break;
+    }
+  }
+}
+
+// 3. Check for hardcoded metrics in prompt files
+const filesToCheck = [
+  { path: join(projectRoot, 'modes', '_shared.md'), name: '_shared.md' },
+  { path: join(projectRoot, 'batch', 'batch-prompt.md'), name: 'batch-prompt.md' },
+];
+
+// Pattern: numbers that look like hardcoded metrics (e.g., "170+ hours", "90% self-service")
+const metricPattern = /\b\d{2,4}\+?\s*(hours?|%|evals?|layers?|tests?|fields?|bases?)\b/gi;
+
+for (const { path, name } of filesToCheck) {
+  if (!existsSync(path)) continue;
+  const content = readFileSync(path, 'utf-8');
+
+  // Skip lines that are clearly instructions (contain "NEVER hardcode" etc.)
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes('NEVER hardcode') || line.includes('NUNCA hardcode') || line.startsWith('#') || line.startsWith('<!--')) continue;
+    const matches = line.match(metricPattern);
+    if (matches) {
+      warnings.push(`${name}:${i + 1} — Possible hardcoded metric: "${matches[0]}". Should this be read from cv.md/article-digest.md?`);
+    }
+  }
+}
+
+// 4. Check article-digest.md freshness
+const digestPath = join(projectRoot, 'article-digest.md');
+if (existsSync(digestPath)) {
+  const stats = statSync(digestPath);
+  const daysSinceModified = (Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24);
+  if (daysSinceModified > 30) {
+    warnings.push(`article-digest.md is ${Math.round(daysSinceModified)} days old. Consider updating if your projects have new metrics.`);
+  }
+}
+
+// Output results
+console.log('\n=== job-forge sync check ===\n');
+
+if (errors.length === 0 && warnings.length === 0) {
+  console.log('All checks passed.');
+} else {
+  if (errors.length > 0) {
+    console.log(`ERRORS (${errors.length}):`);
+    errors.forEach(e => console.log(`  ERROR: ${e}`));
+  }
+  if (warnings.length > 0) {
+    console.log(`\nWARNINGS (${warnings.length}):`);
+    warnings.forEach(w => console.log(`  WARN: ${w}`));
+  }
+}
+
+console.log('');
+process.exit(errors.length > 0 ? 1 : 0);

package/dedup-tracker.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * dedup-tracker.mjs — Remove duplicate entries from the application tracker
+ *
+ * Supports both layouts:
+ *   - Day-based: data/applications/YYYY-MM-DD.md (preferred)
+ *   - Single-file: data/applications.md or applications.md (legacy)
+ *
+ * Groups by normalized company + fuzzy role match.
+ * Keeps entry with highest score. If discarded entry had more advanced status,
+ * preserves that status. Merges notes.
+ *
+ * Run: node dedup-tracker.mjs [--dry-run]   (from repo root)
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync } from 'fs';
+import { join, relative, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  PROJECT_DIR, DATA_APPS_DIR, DATA_APPS_FILE, ROOT_APPS_FILE,
+  usesDayFiles, ensureDayDir, getHeader, formatAppLine, parseAppLine,
+  readAllEntries, writeToDayFiles, listDayFiles, dayFilePath,
+} from './tracker-lib.mjs';
+
+const DRY_RUN = process.argv.includes('--dry-run');
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`dedup-tracker.mjs — remove duplicate tracker rows by company and role
+
+Supports day-based (data/applications/YYYY-MM-DD.md) and single-file layouts.
+Keeps the highest-scoring row per cluster; may promote status when a removed
+row was further along in the pipeline. Merges notes where applicable.
+
+Usage:
+  node dedup-tracker.mjs [--dry-run]
+  npm run dedup [-- --dry-run]
+
+Exits successfully when no tracker exists (nothing to do).
+Creates a .bak copy next to the tracker before writing (single-file mode).
+
+Run from the repository root.`);
+  process.exit(0);
+}
+
+const STATUS_RANK = {
+  'skip': 0,
+  'discarded': 0,
+  'rejected': 1,
+  'evaluated': 2,
+  'applied': 3,
+  'contacted': 3.5,
+  'responded': 4,
+  'interview': 5,
+  'offer': 6,
+};
+
+function normalizeCompany(name) {
+  return name.toLowerCase()
+    .replace(/[()]/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/[^a-z0-9 ]/g, '')
+    .trim();
+}
+
+function normalizeRole(role) {
+  return role.toLowerCase()
+    .replace(/[()]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/[^a-z0-9 /]/g, '')
+    .trim();
+}
+
+function roleMatch(a, b) {
+  const wordsA = normalizeRole(a).split(/\s+/).filter(w => w.length > 3);
+  const wordsB = normalizeRole(b).split(/\s+/).filter(w => w.length > 3);
+  const overlap = wordsA.filter(w => wordsB.some(wb => wb.includes(w) || w.includes(wb)));
+  return overlap.length >= 2;
+}
+
+function parseScore(s) {
+  const m = s.replace(/\*\*/g, '').match(/([\d.]+)/);
+  return m ? parseFloat(m[1]) : 0;
+}
+
+// Read entries
+const { entries, source } = readAllEntries();
+if (entries.length === 0) {
+  console.log('No tracker entries found. Nothing to dedup.');
+  process.exit(0);
+}
+
+console.log(`📊 ${entries.length} entries loaded from ${source === 'day' ? 'day files' : 'single file'}`);
+
+// Group by company+role
+const groups = new Map();
+for (const entry of entries) {
+  const key = normalizeCompany(entry.company);
+  if (!groups.has(key)) groups.set(key, []);
+  groups.get(key).push(entry);
+}
+
+// Find duplicates
+let removed = 0;
+const toRemove = new Set(); // entry.num values to remove
+const statusUpdates = new Map(); // num → new status
+
+for (const [company, companyEntries] of groups) {
+  if (companyEntries.length < 2) continue;
+
+  const processed = new Set();
+  for (let i = 0; i < companyEntries.length; i++) {
+    if (processed.has(i)) continue;
+    const cluster = [companyEntries[i]];
+    processed.add(i);
+
+    for (let j = i + 1; j < companyEntries.length; j++) {
+      if (processed.has(j)) continue;
+      if (roleMatch(companyEntries[i].role, companyEntries[j].role)) {
+        cluster.push(companyEntries[j]);
+        processed.add(j);
+      }
+    }
+
+    if (cluster.length < 2) continue;
+
+    // Keep the one with highest score
+    cluster.sort((a, b) => parseScore(b.score) - parseScore(a.score));
+    const keeper = cluster[0];
+
+    // Check if any removed entry has more advanced status
+    let bestStatusRank = STATUS_RANK[keeper.status.toLowerCase()] || 0;
+    let bestStatus = keeper.status;
+    for (let k = 1; k < cluster.length; k++) {
+      const rank = STATUS_RANK[cluster[k].status.toLowerCase()] || 0;
+      if (rank > bestStatusRank) {
+        bestStatusRank = rank;
+        bestStatus = cluster[k].status;
+      }
+    }
+
+    if (bestStatus !== keeper.status) {
+      statusUpdates.set(keeper.num, bestStatus);
+      console.log(`  📝 #${keeper.num}: status promoted to "${bestStatus}" (from #${cluster.find(e => e.status === bestStatus)?.num})`);
+    }
+
+    // Mark duplicates for removal
+    for (let k = 1; k < cluster.length; k++) {
+      const dup = cluster[k];
+      toRemove.add(dup.num);
+      removed++;
+      console.log(`🗑️  Remove #${dup.num} (${dup.company} — ${dup.role}, ${dup.score}) → kept #${keeper.num} (${keeper.score})`);
+    }
+  }
+}
+
+console.log(`\n📊 ${removed} duplicates found`);
+
+if (!DRY_RUN && (removed > 0 || statusUpdates.size > 0)) {
+  if (source === 'day') {
+    // Filter out removed entries and apply status updates, then rewrite
+    const kept = entries
+      .filter(e => !toRemove.has(e.num))
+      .map(e => {
+        if (statusUpdates.has(e.num)) {
+          return { ...e, status: statusUpdates.get(e.num) };
+        }
+        return e;
+      });
+    writeToDayFiles(kept);
+    console.log(`✅ Written to day files`);
+  } else {
+    // Single-file mode
+    const APPS_FILE = existsSync(DATA_APPS_FILE) ? DATA_APPS_FILE : ROOT_APPS_FILE;
+    const appsDisplay = relative(PROJECT_DIR, APPS_FILE).replace(/\\/g, '/');
+    copyFileSync(APPS_FILE, APPS_FILE + '.bak');
+
+    let content = readFileSync(APPS_FILE, 'utf-8');
+    const lines = content.split('\n');
+
+    const updatedLines = [];
+    for (const line of lines) {
+      const app = parseAppLine(line);
+      if (app && toRemove.has(app.num)) continue; // skip removed
+      if (app && statusUpdates.has(app.num)) {
+        const newStatus = statusUpdates.get(app.num);
+        const parts = line.split('|').map(s => s.trim());
+        parts[6] = newStatus;
+        updatedLines.push('| ' + parts.slice(1, -1).join(' | ') + ' |');
+      } else {
+        updatedLines.push(line);
+      }
+    }
+
+    writeFileSync(APPS_FILE, updatedLines.join('\n'));
+    console.log(`✅ Written to ${appsDisplay} (backup: ${appsDisplay}.bak)`);
+  }
+} else if (DRY_RUN) {
+  console.log('(dry-run — no changes written)');
+} else {
+  console.log('✅ No duplicates found');
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,220 @@
+# Architecture
+
+## Package architecture (v2.0.0+)
+
+JobForge ships as an npm package. There are two kinds of repo involved:
+
+- **Harness** — this repo, `razroo/JobForge`. Installable via `github:razroo/JobForge` (no npm registry). Contains modes, scripts, skill router, templates, fonts, dashboard, and bin entries.
+- **Consumer project** — what users interact with day-to-day. Scaffolded via `npx create-job-forge <dir>`, or hand-authored with `job-forge` listed in `package.json` dependencies.
+
+The consumer's project root contains only personal data:
+
+```
+my-search/
+├── package.json                 # depends on "job-forge"
+├── opencode.json                # instructions: ["templates/states.yml"]
+├── cv.md                        # personal
+├── config/profile.yml           # personal
+├── portals.yml                  # personal
+├── data/                        # personal (gitignored)
+├── reports/                     # personal (gitignored)
+├── modes/                       # → symlink to node_modules/job-forge/modes/
+├── templates/                   # → symlink to node_modules/job-forge/templates/
+├── .opencode/skills/job-forge.md # → symlink
+├── batch/batch-prompt.md        # → symlink
+├── batch/batch-runner.sh        # → symlink
+└── node_modules/job-forge/      # harness, fetched from github
+```
+
+Symlinks are created by the harness's `postinstall` hook (`bin/sync.mjs`) on every `npm install`. They are gitignored in the scaffolder template. Real files at those paths are preserved — if a user locally customizes a mode file, the sync skips that symlink and warns.
+
+The consumer's `opencode.json` loads a small set of stable files as always-present instructions: `AGENTS.harness.md` (harness operational rules), `templates/states.yml` (canonical application states), `modes/_shared.md` (scoring model), and `cv.md` (the candidate's CV). Caching these in the prefix means agents never Read them as tool calls. Churning content (score calibration anchors, specific mode files) stays out of `instructions` and is Read on demand.
+
+The skill router (`.opencode/skills/job-forge.md`) loads mode and data files on demand, keeping per-session input tokens low (~20-40K for most modes instead of ~130-170K when everything was force-loaded).
+
+**Cost-tiered subagents** live in `.opencode/agents/` (`general-free`, `general-paid`, `glm-minimal`) — the orchestrator delegates procedural work to free-tier models and reserves paid models for quality-sensitive writing. See [MODEL-ROUTING.md](MODEL-ROUTING.md) for the routing architecture, why it exists, and how to customize.
+
+**Upgrading** the harness in a consumer project is `npm run update-harness` — fetches the latest harness (`github:razroo/JobForge`) and `@razroo/opencode-model-fallback` plugin, re-runs symlink sync, and prints the resolved commit SHA.
+
+## System Overview
+
+```
+                    ┌─────────────────────────────────┐
+                    │         opencode Agent        │
+                    │   (reads OPENCODE.md + modes/*.md) │
+                    └──────────┬──────────────────────┘
+                               │
+            ┌──────────────────┼──────────────────────┐
+            │                  │                       │
+     ┌──────▼──────┐   ┌──────▼──────┐   ┌───────────▼────────┐
+     │ Single Eval  │   │ Portal Scan │   │   Batch Process    │
+     │ (auto-pipe)  │   │  (scan.md)  │   │   (batch-runner)   │
+     └──────┬──────┘   └──────┬──────┘   └───────────┬────────┘
+            │                  │                       │
+            │           ┌─────────▼─────────┐          ┌────▼─────┐
+            │           │ data/pipeline.md  │          │ N workers│
+            │           │    (URL inbox)    │          │ (opencode run)
+            │           └─────────┬─────────┘          └────┬─────┘
+            │                                          │
+     ┌──────▼──────────────────────────────────────────▼──────┐
+     │                    Output Pipeline                      │
+     │  ┌──────────┐  ┌────────────┐  ┌───────────────────┐  │
+     │  │ Report.md│  │  PDF (HTML  │  │ Tracker TSV       │  │
+     │  │ (A-F eval)│  │ → Geometra) │  │ (merge-tracker)  │  │
+     │  └──────────┘  └────────────┘  └───────────────────┘  │
+     └────────────────────────────────────────────────────────┘
+                               │
+                    ┌──────────▼──────────┐
+│  data/applications/   │
+                     │  (day-based tracker)  │
+                    └──────────────────────┘
+```
+
+## Modes (`modes/`)
+
+Markdown mode files in `modes/` define how the opencode workflow behaves together with the root `OPENCODE.md`. **`_shared.md`** is the shared layer (archetypes, scoring dimensions, negotiation scaffolding); the rest align with `/job-forge` command entry points listed in `OPENCODE.md`.
+
+| File | Focus |
+|------|--------|
+| `_shared.md` | Archetypes, evaluation axes, shared prompts |
+| `auto-pipeline.md` | Default path: evaluate, report, PDF, tracker |
+| `offer.md` | Single-offer analysis |
+| `compare.md` | Comparing multiple offers |
+| `contact.md` | Outreach (e.g. LinkedIn) |
+| `deep.md` | Company research |
+| `pdf.md` | CV / PDF generation |
+| `training.md` | Courses and certifications |
+| `project.md` | Portfolio projects |
+| `tracker.md` | Application tracker review |
+| `apply.md` | Application forms |
+| `scan.md` | Portal / job-board scanning |
+| `pipeline.md` | Pending URL inbox |
+| `batch.md` | Parallel batch runs (`batch/batch-runner.sh`) |
+| `followup.md` | Follow-up triage |
+| `rejection.md` | Rejection handling |
+| `negotiation.md` | Offer negotiation |
+
+For customization (archetypes, weights, tone), start with `_shared.md` and [CUSTOMIZATION.md](CUSTOMIZATION.md).
+
+## Evaluation Flow (Single Offer)
+
+1. **Input**: User pastes JD text or URL
+2. **Extract**: Geometra MCP/WebFetch extracts JD from URL
+3. **Classify**: Detect archetype (one row from the archetype table in `modes/_shared.md`)
+4. **Evaluate**: 6 blocks (A-F).
+   - A: Role summary.
+   - B: CV match (gaps + mitigation).
+   - C: Level strategy.
+   - D: Comp research (WebSearch).
+   - E: CV personalization plan.
+   - F: Interview prep (STAR stories).
+5. **Score**: Weighted average across 10 dimensions (1-5)
+6. **Report**: Save as `reports/{num}-{company}-{date}.md`
+7. **PDF**: Generate ATS-optimized CV (`generate-pdf.mjs`)
+8. **Track**: Write one TSV per evaluation under `batch/tracker-additions/` (see [OPENCODE.md](../OPENCODE.md) TSV layout); fold rows into `data/applications.md` with `npm run merge` / `merge-tracker.mjs` when you are ready (not automatic in every workflow)
+
+## Batch Processing
+
+The batch system processes multiple offers in parallel:
+
+```
+batch-input.tsv    →  batch-runner.sh  →  N × opencode run workers
+(id, url, source, notes) (orchestrator)   (self-contained prompt)
+                           │
+                    batch-state.tsv
+                    (tracks progress)
+```
+
+Each worker is a headless opencode instance (`opencode run`) that receives the full `batch-prompt.md` as context. Workers produce:
+- Report .md
+- PDF
+- Tracker TSV line
+
+The orchestrator manages parallelism, state, retries, and resume.
+
+**Local batch artifacts:** `batch/batch-input.tsv`, `batch/batch-state.tsv`, `batch/logs/`, and `batch/tracker-additions/*.tsv` are created when you run the runner; they are gitignored (with `.gitkeep` in `batch/logs/` and `batch/tracker-additions/`). A fresh clone ships `batch/batch-runner.sh` and `batch/batch-prompt.md` only until you add an input file — see [`batch/README.md`](../batch/README.md) and `batch/batch-runner.sh --help` for the TSV layout and workflow.
+
+## Data Flow
+
+```
+cv.md                    →  Evaluation context
+article-digest.md        →  Proof points for matching
+config/profile.yml       →  Candidate identity
+portals.yml              →  Scanner configuration
+data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/pipeline.md)
+jds/*.md                 →  Saved job descriptions referenced from the pipeline (`local:jds/{file}`)
+templates/states.yml     →  Canonical status values
+templates/cv-template.html → PDF generation template
+examples/*.md            →  Fictional layouts only (not read by scripts; see examples/README.md)
+```
+
+Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeline`); format and `local:jds/...` lines are described in [`modes/pipeline.md`](../modes/pipeline.md).
+
+## File Naming Conventions
+
+- Reports: `{###}-{company-slug}-{YYYY-MM-DD}.md` (3-digit zero-padded)
+- PDFs: `cv-candidate-{company-slug}-{YYYY-MM-DD}.pdf`
+- Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`)
+
+## Pipeline Integrity
+
+From the project root, `npx job-forge verify` (or `npm run verify`) runs `verify-pipeline.mjs`. When a tracker file exists, it validates canonical statuses (using `templates/states.yml` when that file is present and parseable), warns on probable duplicate company/role rows, checks that report column markdown links resolve to files in the repo, validates score column format (`X.X/5`, `N/A`, or `DUP`), rejects table rows with too few columns, flags markdown bold inside the score column, and warns if any `batch/tracker-additions/*.tsv` files are still waiting to be merged. It also compares state ids from `templates/states.yml` to an internal fallback list and warns when the two sets drift. **Fresh clone:** the command exits successfully when neither `data/applications.md` nor root `applications.md` exists yet; pending-TSV and states-drift checks still run so contributors see unmerged batch output early. Optional setup validation after you add `cv.md` and `config/profile.yml`: `npm run sync-check` (`cv-sync-check.mjs`).
+
+**`verify-pipeline.mjs` checks (same order as the script header):**
+
+1. Status column uses canonical ids (from `templates/states.yml` when parseable, else built-in ids and aliases), with no markdown bold and no dates embedded in the status cell.
+2. Warn when multiple rows share the same normalized company + role (possible duplicates).
+3. Report column markdown links resolve to files under the repo root.
+4. Score column matches `X.X/5`, `N/A`, or `DUP`.
+5. Table data rows have enough pipe-delimited columns.
+6. No unmerged `batch/tracker-additions/*.tsv` files (warns if any remain).
+7. Score column has no markdown bold.
+8. Warn when state ids in `templates/states.yml` drift from the script’s built-in fallback list (or when the file exists but ids failed to parse).
+
+When the tracker file is missing, checks 1–5 and 7 are skipped; checks 6 and 8 still run.
+
+## Contributing touchpoints
+
+Prefer one focused change per pull request: a single mode under `modes/`, one repository-root `.mjs` utility, documentation under `docs/`, fictional samples under [`examples/`](../examples/README.md), templates such as [`templates/portals.example.yml`](../templates/portals.example.yml), the batch flow described in [`batch/README.md`](../batch/README.md), or the Go TUI under `dashboard/` — not a repo-wide refactor across 3+ of those at once. Branch workflow, the verify + dashboard build gate, and starter ideas are in [CONTRIBUTING.md](../CONTRIBUTING.md) (**What to Contribute** and **Development**). To look for in-repo `TODO`, `FIXME`, or `HACK` markers before choosing a task, use the `rg` one-liner in [CONTRIBUTING.md — Optional: scripted agent iterations](../CONTRIBUTING.md#optional-scripted-agent-iterations). Upstream PRs MUST stay generic: do not commit real candidate data (`cv.md`, `config/profile.yml`, personalized `portals.yml`, `data/applications.md`, `reports/`, or similar paths called out in CONTRIBUTING and `.gitignore`).
+
+**PR / maintainer gate:** Before opening a pull request against `razroo/JobForge`, run `npm run verify` and `npm run build:dashboard` (or `(cd dashboard && go build .)`) from the harness repo root (same as [CONTRIBUTING.md](../CONTRIBUTING.md#development)). For optional scripted iterations that repeat that gate and commit one small change per pass, see [`scripts/cursor-agent-loop.sh`](../scripts/cursor-agent-loop.sh) (environment variables and usage in the script header; overview in [CONTRIBUTING.md](../CONTRIBUTING.md#optional-scripted-agent-iterations)).
+
+Scripts maintain data consistency. In a consumer project they're invoked via the `job-forge` CLI (`npx job-forge <cmd>`); in the harness repo they're also directly runnable as `node <script>.mjs`.
+
+| Script (in harness) | CLI | Purpose |
+|---------------------|-----|---------|
+| `merge-tracker.mjs` | `npx job-forge merge` | Merges TSV rows from `batch/tracker-additions/` into day files under `data/applications/`, or `data/applications.md` when the directory is absent |
+| `verify-pipeline.mjs` | `npx job-forge verify` | Health check — see the verify paragraph above |
+| `dedup-tracker.mjs` | `npx job-forge dedup` | Removes duplicate entries by company+role |
+| `normalize-statuses.mjs` | `npx job-forge normalize` | Maps status aliases to canonical values |
+| `generate-pdf.mjs` | `npx job-forge pdf` | Renders HTML to PDF via Geometra MCP (`geometra_generate_pdf`) or standalone Playwright/Chromium (`npx job-forge pdf <input.html> <output.pdf>`) |
+| `cv-sync-check.mjs` | `npx job-forge sync-check` | Setup lint: `cv.md` + `config/profile.yml`, hardcoded-metric scan on `modes/_shared.md` and `batch/batch-prompt.md`, optional `article-digest.md` freshness |
+| `scripts/token-usage-report.mjs` | `npx job-forge tokens` | Per-session opencode token/cost report from the SQLite DB |
+| `tracker-lib.mjs` | _(library)_ | Shared helpers for reading/writing day-based tracker files — imported by merge/dedup/verify/normalize |
+| `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project (also runs as `postinstall`) |
+| `bin/create-job-forge.mjs` | `npx create-job-forge <dir>` | Scaffolds a new personal project |
+
+All scripts resolve the consumer project dir via `process.env.JOB_FORGE_PROJECT || process.cwd()`, so running the CLI from anywhere in the consumer project Just Works.
+
+## Dashboard TUI
+
+The `dashboard/` directory contains a standalone Go TUI application that visualizes the pipeline.
+
+**Repo root:** The program needs the path to the JobForge checkout (the directory that contains `modes/`, `reports/`, and the tracker). Flag `-path` sets that directory (default `.`, i.e. the process working directory). If you run the binary from inside `dashboard/` after `go build`, use `-path ..` so the tracker is found.
+
+**Tracker file:** Day-based directory `data/applications/` (preferred) with `YYYY-MM-DD.md` files. Falls back to single-file `data/applications.md` or root `applications.md` for legacy setups.
+
+**Build / run** (see also [SETUP.md](SETUP.md#build-dashboard-optional)):
+
+```bash
+cd dashboard && go build -o job-forge-dashboard .
+./job-forge-dashboard -path ..
+```
+
+**UI:**
+
+- Filter tabs: All, Evaluated, Applied, Interview, Top ≥4, SKIP
+- Sort modes: Score, Date, Company, Status
+- Grouped/flat view
+- Lazy-loaded report previews
+- Inline status picker; on-screen key hints at the bottom of the pipeline view