job-forge 2.14.38 → 2.14.40

package/.codex/config.toml

@@ -1,4 +1,4 @@
-# generated by @razroo/iso-route — do not hand-edit
+# generated by @agent-pattern-labs/iso-route — do not hand-edit
 model = "gpt-5.4"
 model_provider = "openai"
 
@@ -17,7 +17,8 @@ model_provider = "openai"
 
 [mcp_servers.geometra]
 command = "npx"
-args = ["-y", "@geometra/mcp@1.61.3"]
+args = ["--no-install", "job-forge", "mcp:geometra"]
+env = { GEOMETRA_STEALTH = "1", GEOMETRA_BROWSER = "stealth" }
 
 [mcp_servers.gmail]
 command = "npx"

package/.cursor/mcp.json

@@ -3,9 +3,14 @@
     "geometra": {
       "command": "npx",
       "args": [
-        "-y",
-        "@geometra/mcp@1.61.3"
-      ]
+        "--no-install",
+        "job-forge",
+        "mcp:geometra"
+      ],
+      "env": {
+        "GEOMETRA_STEALTH": "1",
+        "GEOMETRA_BROWSER": "stealth"
+      }
     },
     "gmail": {
       "command": "npx",

package/.cursor/rules/main.mdc

@@ -56,7 +56,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
-- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@agent-pattern-labs/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
 - [D8] Use deterministic local helpers instead of prose when they can answer or validate state, identity, policy, scoring, timing, dispatch, priority, lineage, migration, or safe-export questions. Read `modes/reference-local-helpers.md` when choosing a helper or changing helper wiring.

package/.mcp.json

@@ -3,9 +3,14 @@
     "geometra": {
       "command": "npx",
       "args": [
-        "-y",
-        "@geometra/mcp@1.61.3"
-      ]
+        "--no-install",
+        "job-forge",
+        "mcp:geometra"
+      ],
+      "env": {
+        "GEOMETRA_STEALTH": "1",
+        "GEOMETRA_BROWSER": "stealth"
+      }
     },
     "gmail": {
       "command": "npx",

package/AGENTS.md

@@ -51,7 +51,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
-- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@agent-pattern-labs/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
 - [D8] Use deterministic local helpers instead of prose when they can answer or validate state, identity, policy, scoring, timing, dispatch, priority, lineage, migration, or safe-export questions. Read `modes/reference-local-helpers.md` when choosing a helper or changing helper wiring.

package/CLAUDE.md

@@ -51,7 +51,7 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D6] Pick the mode from the **Routing** table below AND name it explicitly in your first response (e.g., "running auto-pipeline mode", "this is a `compare` request"). If no row matches the user's intent, ask which mode fits; do not guess.
   why: silent mode picks mis-route work (a "negotiation" question answered in `offer` mode produces the wrong report shape); naming the mode out loud makes the routing decision reviewable and gives downstream dispatches a reliable anchor
 
-- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@razroo/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
+- [D7] For standalone `batch` runs, prefer `batch/batch-runner.sh` instead of hand-rolling the loop. It delegates to `@agent-pattern-labs/iso-orchestrator`, persists workflow records in `.jobforge-runs/`, caps bundle fan-out, and mutexes state/report-number writes. Use `JOBFORGE_LEGACY_BATCH_RUNNER=1` only as a fallback.
   why: the old Bash loop encoded resumability and parallelism manually; the iso-orchestrator path makes the durable control state inspectable and prevents report-number collisions under parallel bundles
 
 - [D8] Use deterministic local helpers instead of prose when they can answer or validate state, identity, policy, scoring, timing, dispatch, priority, lineage, migration, or safe-export questions. Read `modes/reference-local-helpers.md` when choosing a helper or changing helper wiring.

package/README.md

@@ -1,242 +1,194 @@
 # 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.
+> AI-powered job search pipeline for opencode: evaluate roles, generate tailored CV PDFs, scan portals, apply to good-fit jobs, and track the whole search locally.
 
 ![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">
+  <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>
+<p align="center"><em>Paste a job URL. Get a scored evaluation, tailored CV, and tracker entry.</em></p>
 
----
+## Start Here
 
-## Quick Start
+Most users should scaffold a personal job-search project instead of cloning this harness repo directly.
+
+### Prerequisites
+
+- [opencode](https://opencode.ai) installed and configured
+- Node.js 20.6 or newer
+- Optional: Go, only if you want to build the dashboard TUI
+
+### Create Your Project
 
 ```bash
 npx --package=job-forge create-job-forge my-job-search
 cd my-job-search
 npm install
-opencode
 ```
 
-The scaffolded `opencode.json` already has three MCPs wired up — they launch automatically the first time opencode starts:
+Then edit the three personal files the scaffolder creates:
 
-- **Geometra** — browser automation + PDF generation
-- **Gmail** — reads replies from recruiters
-- **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with `python3 -m pip install "state-trace[mcp]"`; the MCP command is `state-trace-mcp`.
+| File | What to put there |
+|------|-------------------|
+| `cv.md` | Your CV in markdown. This is the source for matching and PDF generation. |
+| `config/profile.yml` | Your identity, target roles, location constraints, compensation, and proof points. |
+| `portals.yml` | Companies, search queries, and title filters for portal scanning. |
 
-JobForge also keeps MCP-free local workflow state and policy: `templates/canon.json` defines URL/company/role identity keys via `@razroo/iso-canon`, `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/score.json` defines weighted scoring and gates via `@razroo/iso-score`, `templates/timeline.json` defines follow-up and next-action windows via `@razroo/iso-timeline`, `templates/prioritize.json` defines next-action ranking via `@razroo/iso-prioritize`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, `templates/preflight.json` defines safe dispatch rounds/gates via `@razroo/iso-preflight`, `templates/postflight.json` defines safe dispatch settlement via `@razroo/iso-postflight`, `templates/redact.json` defines safe-export redaction rules via `@razroo/iso-redact`, `templates/migrations.json` defines safe consumer-project upgrades via `@razroo/iso-migrate`, `templates/facts.json` defines source-backed fact extraction via `@razroo/iso-facts`, `.jobforge-ledger/events.jsonl` records duplicate/status events via `@razroo/iso-ledger`, `.jobforge-cache/` stores reusable JD/artifact content via `@razroo/iso-cache`, `.jobforge-index.json` indexes artifact source pointers via `@razroo/iso-index`, `.jobforge-facts.json` materializes queryable facts with provenance, `.jobforge-timeline.json` materializes due/overdue follow-up actions, `.jobforge-prioritize.json` materializes the ranked local priority queue, and `.jobforge-lineage.json` records stale-output checks for generated artifacts via `@razroo/iso-lineage`. None of these add always-on prompt or tool-schema tokens.
+Optional: add `article-digest.md` with portfolio links, case studies, or extra proof points.
 
-`npm install` also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run `opencode`, `cursor`, `claude`, or `codex` in the same project and each picks up the shared MCP config and instructions.
+### First Run
 
-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 `job-forge` from npm, re-syncs symlinks, applies safe consumer migrations, prints the resolved version)
-
-Full setup guide and alternative install paths (including contributing to the harness itself): **[docs/SETUP.md](docs/SETUP.md)**.
+```bash
+npx job-forge sync-check
+opencode
+```
 
----
+Inside opencode, paste a job URL or job description. JobForge routes it through the auto-pipeline: evaluation, score, tailored report, PDF, and tracker update.
 
-## What Is This
+To see the command menu:
 
-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:
+```text
+/job-forge
+```
 
-- **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
+## What It Does
+
+JobForge is built for selective, high-fit applications. It is not intended for spray-and-pray submission.
+
+- Scores opportunities with a consistent weighted rubric.
+- Generates tailored ATS-friendly CV PDFs.
+- Scans configured company portals and job boards.
+- Tracks applications, follow-ups, rejections, offers, reports, and PDFs.
+- Supports batch evaluation and application work through bounded subagents.
+- Uses local helper CLIs for dedupe, scoring, lineage, preflight, postflight, and tracker integrity.
+
+## Common Commands
+
+Run these from your personal project root after `npm install`.
+
+| Need | Command |
+|------|---------|
+| Verify setup after editing profile and CV | `npx job-forge sync-check` |
+| Check tracker and pipeline health | `npx job-forge verify` |
+| Merge batch tracker additions | `npx job-forge merge` |
+| Generate a CV PDF from the current project | `npx job-forge pdf` |
+| Show token usage | `npx job-forge tokens --days 1` |
+| Rebuild harness symlinks | `npx job-forge sync` |
+| Upgrade the harness | `npm run update-harness` |
+
+Useful opencode commands:
+
+| Need | Command |
+|------|---------|
+| Evaluate a pasted URL or JD | Paste it directly, or use `/job-forge` |
+| Scan configured portals | `/job-forge scan` |
+| Process queued URLs | `/job-forge pipeline` |
+| Batch evaluate roles | `/job-forge batch` |
+| Fill an application form | `/job-forge apply` |
+| Check application status | `/job-forge tracker` |
+| Check due follow-ups | `/job-forge followup` |
+| Draft LinkedIn outreach | `/job-forge contact` |
+| Research a company | `/job-forge deep` |
+| Handle rejection or offer workflows | `/job-forge rejection` or `/job-forge negotiation` |
+
+## How The Flow Works
+
+```text
+Paste a job URL or JD
+        |
+        v
+Extract role details and classify fit
+        |
+        v
+Score against profile, CV, location, comp, and role goals
+        |
+        v
+Create report + tailored PDF + tracker entry
+        |
+        v
+Apply, follow up, research, or negotiate from the tracked state
+```
 
-> **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.
+## Project Layout
+
+A scaffolded personal project looks like this:
+
+```text
+my-job-search/
+├── package.json                 # depends on job-forge from npm
+├── opencode.json                # MCP and opencode configuration
+├── cv.md                        # personal, gitignored
+├── article-digest.md            # optional personal proof points, gitignored
+├── config/profile.yml           # personal, gitignored
+├── portals.yml                  # personal scanner config, gitignored
+├── data/                        # pipeline, applications, scan history
+├── reports/                     # generated evaluations
+├── output/                      # generated PDFs
+├── batch/tracker-additions/     # batch apply/eval results before merge
+├── AGENTS.md                    # personal overrides
+├── AGENTS.harness.md            # symlink into node_modules/job-forge
+├── modes/                       # symlinked JobForge modes
+├── templates/                   # symlinked policies and templates
+└── node_modules/job-forge/       # the harness package
+```
 
-## Features
+Your personal files and generated job-search state are gitignored by the scaffolded project.
 
-| 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 and deterministic `job-forge score:*` checks |
-| **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** | `job-forge timeline:*` computes timing-based nudges from local tracker/pipeline sources: Applied 7+ days ago, Contacted 5+ days ago, Interview 1-day thank-you, and 7-day interview nudge. |
-| **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 headless AI CLI workers (`opencode run` or `codex exec`), with honest verification flagging |
-| **Durable Batch Orchestration** | `batch-runner.sh` uses `@razroo/iso-orchestrator` for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in `.jobforge-runs/`. |
-| **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
-| **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to `opencode-go/deepseek-v4-flash` so application runs avoid overloaded free-model pools. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
-| **Trace + Telemetry + Guard + Contract + Score + Canon + Ledger + Capabilities + Context + Cache + Index + Facts + Timeline + Prioritize + Lineage + Preflight + Postflight + Redact + Migrate** | `job-forge trace:*` exposes local harness transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge score:*` computes/checks weighted offer scores, `job-forge canon:*` derives stable URL/company/role identity keys, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, `job-forge context:*` plans mode/reference context bundles, `job-forge cache:*` reuses fetched JD/artifact content, `job-forge index:*` queries compact source pointers, `job-forge facts:*` materializes source-backed job/application/candidate facts, `job-forge timeline:*` computes due/overdue follow-up actions, `job-forge prioritize:*` ranks local apply/follow-up candidates, `job-forge lineage:*` detects stale reports/PDFs after source changes, `job-forge preflight:*` plans bounded apply dispatch rounds from file-backed candidate facts, `job-forge postflight:*` settles dispatch outcomes/artifacts/post-steps, `job-forge redact:*` sanitizes local exports, and `job-forge migrate:*` applies safe consumer-project upgrades without MCP/tool-schema overhead. |
-| **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. |
+## MCPs And Automation
 
-## Usage
+The scaffolded opencode project wires up the browser and mail automation JobForge needs:
 
-```
-/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
-```
+- Geometra MCP for browser automation and PDF generation.
+- Gmail MCP for recruiter replies, interview callbacks, offer responses, and status emails.
 
-Or just paste a job URL or description directly -- JobForge auto-detects it and runs the full pipeline.
+The harness also ships config for Cursor, Claude Code, and Codex through generated symlinks. `npm install` and `npx job-forge sync` refresh those links.
 
-> **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".
+## Contributor Setup
 
-## How It Works
+Clone this repo directly only when you want to work on the harness itself: modes, scripts, templates, generated agent configs, or release packaging.
 
-```
-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 + iso-score checks
-└────────┬─────────┘
-         │
-    ┌────┼────┐
-    ▼    ▼    ▼
- Report  PDF  Tracker
-  .md   .pdf   .tsv
-         │
-    ┌────┼────┐
-    ▼    ▼    ▼
- Apply  Follow  Negotiate
-        up      (if offer)
+```bash
+git clone https://github.com/Agent-Pattern-Labs/JobForge.git
+cd JobForge
+npm install
+npm run build:config
+npm run verify
 ```
 
-## Project Structure
+The source of truth for generated harness configuration is under `iso/`. Run `npm run build:config` after changing `iso/` files.
 
-**Your personal project** (after `npx --package=job-forge create-job-forge my-search`):
+## Documentation
 
-```
-my-search/
-├── package.json                  # depends on "job-forge": "^2.0.0" (npm registry)
-├── opencode.json                 # thin config — enables MCPs + states.yml
-├── cv.md                         # your CV (personal)
-├── article-digest.md             # your proof points (optional, personal)
-├── portals.yml                   # companies to scan (personal)
-├── config/profile.yml            # your identity, target roles (personal)
-├── data/                         # applications, pipeline, scan history (personal, gitignored)
-├── .jobforge-ledger/              # append-only local workflow events (personal, gitignored)
-├── .jobforge-cache/               # content-addressed local JD/artifact cache (personal, gitignored)
-├── .jobforge-index.json           # deterministic artifact lookup index (generated, gitignored)
-├── .jobforge-facts.json           # deterministic fact set with provenance (generated, gitignored)
-├── .jobforge-timeline.json        # deterministic follow-up action plan (generated, gitignored)
-├── .jobforge-prioritize.json      # deterministic next-action ranking (generated, gitignored)
-├── .jobforge-lineage.json         # report/PDF lineage and stale-output checks (generated, gitignored)
-├── .jobforge-redacted/            # sanitized local exports (generated, gitignored)
-├── reports/                      # generated evaluation reports (personal, gitignored)
-├── batch/{batch-input,batch-state}.tsv, tracker-additions/, logs/   # personal
-├── .jobforge-runs/                # durable batch workflow records (generated)
-├── AGENTS.md                     # personal overrides (opencode + codex)
-├── CLAUDE.md                     # personal overrides (Claude Code), @-imports CLAUDE.harness.md
-│
-│ # ↓ symlinks into node_modules/job-forge/, regenerated by postinstall sync.mjs
-├── AGENTS.harness.md             # → harness instructions (loaded via opencode.json)
-├── CLAUDE.harness.md             # → harness instructions (imported from personal CLAUDE.md)
-├── .mcp.json                     # → Claude Code MCP config
-├── .codex/config.toml            # → Codex MCP config
-├── .cursor/mcp.json              # → Cursor MCP config
-├── .cursor/rules/main.mdc        # → Cursor always-apply rule
-├── .opencode/skills/job-forge.md # → skill router
-├── .opencode/agents/             # → @general-free, @general-paid, @glm-minimal
-├── modes/                        # → _shared.md + skill modes
-├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, score.json, timeline.json, prioritize.json, capabilities.json, context.json, index.json, facts.json, preflight.json, postflight.json, redact.json, migrations.json
-├── batch/batch-prompt.md         # → batch worker prompt
-├── batch/batch-runner.sh         # → parallel orchestrator
-│
-└── node_modules/job-forge/       # the harness (from npm: `job-forge@2.x`)
-```
+- [Setup](docs/SETUP.md) - full install paths, personalization, tracker setup, token tracking, troubleshooting.
+- [Architecture](docs/ARCHITECTURE.md) - consumer vs harness split, modes, scripts, batch flow, generated config.
+- [Customization](docs/CUSTOMIZATION.md) - profile, archetypes, scanner keywords, states, templates, local overrides.
+- [Model Routing](docs/MODEL-ROUTING.md) - subagent tiers and how to change model routing.
+- [Examples](examples/README.md) - fictional CVs, sample JD, and sample report.
+- [Batch Runner](batch/README.md) - TSV format, durable batch runner, merge flow.
+- [Contributing](CONTRIBUTING.md) - branch workflow and quality checks.
 
-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`.
+## Troubleshooting
 
-**The harness itself** (this repo, what gets published as `job-forge` on npm):
+`sync-check` fails before your CV/profile are complete. That is expected until `cv.md` and `config/profile.yml` are filled in.
 
-```
-JobForge/
-├── iso/                          # ← SOURCE OF TRUTH for harness configuration
-│   ├── instructions.md           # → AGENTS.md + CLAUDE.md (Claude Code / Codex / Cursor)
-│   ├── mcp.json                  # → .mcp.json + .cursor/mcp.json + .codex/config.toml + opencode.json
-│   ├── agents/*.md               # → .opencode/agents/*.md (general-free, general-paid, glm-minimal)
-│   ├── commands/job-forge.md     # → .opencode/skills/job-forge.md
-│   └── config.json               # per-harness top-level extras (e.g. opencode `instructions` array)
-│
-├── package.json                  # bin: job-forge, create-job-forge; prepack runs iso-harness
-├── bin/
-│   ├── job-forge.mjs             # CLI dispatcher (merge/verify/pdf/tokens/sync/...)
-│   ├── sync.mjs                  # postinstall: creates symlinks in consumer project
-│   └── create-job-forge.mjs      # scaffolder
-├── modes/                        # _shared.md + 16 skill modes
-├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, score.json, timeline.json, prioritize.json, capabilities.json, context.json, facts.json, preflight.json, postflight.json, redact.json, migrations.json
-├── config/profile.example.yml    # template for consumer's profile.yml
-├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
-├── scripts/
-│   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
-│   ├── tracker-line.mjs          # iso-contract-backed tracker TSV renderer
-│   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
-│   ├── capabilities.mjs          # iso-capabilities-backed role policy CLI
-│   ├── context.mjs               # iso-context-backed context bundle CLI
-│   ├── cache.mjs                 # iso-cache-backed local artifact cache CLI
-│   ├── index.mjs                 # iso-index-backed artifact lookup CLI
-│   ├── facts.mjs                 # iso-facts-backed local fact materialization
-│   ├── timeline.mjs              # iso-timeline-backed follow-up planning CLI
-│   ├── prioritize.mjs            # iso-prioritize-backed next-action ranking
-│   ├── lineage.mjs               # iso-lineage-backed stale artifact checks
-│   ├── score.mjs                 # iso-score-backed offer scoring CLI
-│   ├── canon.mjs                 # iso-canon-backed identity normalization CLI
-│   ├── preflight.mjs             # iso-preflight-backed dispatch planning CLI
-│   ├── postflight.mjs            # iso-postflight-backed dispatch settlement CLI
-│   ├── redact.mjs                # iso-redact-backed safe-export redaction CLI
-│   ├── migrate.mjs               # iso-migrate-backed consumer-project migrations
-│   ├── token-usage-report.mjs    # opencode cost analyzer
-│   └── release/check-source.mjs  # version gate for npm publish
-├── tracker-lib.mjs / merge-tracker.mjs / dedup-tracker.mjs / verify-pipeline.mjs
-├── normalize-statuses.mjs / generate-pdf.mjs / cv-sync-check.mjs
-├── dashboard/                    # optional Go TUI
-├── fonts/                        # Space Grotesk + DM Sans (for PDF)
-├── docs/                         # architecture, setup, customization
-└── .github/workflows/            # quality.yml + release.yml (CI publish to npm)
-```
+If symlinks look stale after moving a project, run:
 
-All per-harness config trees (`.opencode/`, `.cursor/`, `.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `.mcp.json`, `opencode.json`) are **generated** from `iso/` by [`@razroo/iso-harness`](https://www.npmjs.com/package/@razroo/iso-harness) and gitignored in this repo. `npm run build:config` regenerates them locally; `prepack` regenerates them into the tarball at publish time so consumers get everything pre-baked.
+```bash
+npx job-forge sync
+```
 
-## Documentation
+If PDF or browser automation fails, start with:
 
-Index and cross-links: [docs/README.md](docs/README.md).
+```bash
+opencode mcp list
+```
 
-- [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
+Then see [docs/SETUP.md](docs/SETUP.md#troubleshooting) for Geometra, Gmail, dashboard, tracker, and merge troubleshooting.
 
 ## License
 

package/batch/README.md

@@ -14,7 +14,7 @@ The `batch/` folder holds the **parallel batch runner** for processing 10+ job U
 
 Per [`.gitignore`](../.gitignore): `batch-input.tsv`, `batch-state.tsv`, `logs/*`, `tracker-additions/*.tsv`, and `.jobforge-runs/`. Empty dirs (`logs/`, `tracker-additions/`) use `.gitkeep` so the tree exists in a fresh clone.
 
-The default runner uses `@razroo/iso-orchestrator` through
+The default runner uses `@agent-pattern-labs/iso-orchestrator` through
 `scripts/batch-orchestrator.mjs`. It persists bundle steps and events in
 `.jobforge-runs/`, caps worker fan-out with `workflow.forEach`, serializes
 state/report-number writes while parallel bundles run, and records worker

package/bin/create-job-forge.mjs

@@ -240,7 +240,11 @@ const opencodeCfg = {
   mcp: {
     geometra: {
       type: 'local',
-      command: ['npx', '-y', '@geometra/mcp@1.61.3'],
+      command: ['npx', '--no-install', 'job-forge', 'mcp:geometra'],
+      environment: {
+        GEOMETRA_STEALTH: '1',
+        GEOMETRA_BROWSER: 'stealth',
+      },
       enabled: true,
     },
     gmail: {
@@ -286,7 +290,7 @@ write('opencode.json', JSON.stringify(opencodeCfg, null, 2) + '\n');
 
 write('AGENTS.md', `# AGENTS — ${name}
 
-Personal job search project using the [job-forge](https://github.com/razroo/JobForge) harness. The harness lives in \`node_modules/job-forge/\`; most files you need are accessible through symlinks at the project root.
+Personal job search project using the [job-forge](https://github.com/Agent-Pattern-Labs/JobForge) harness. The harness lives in \`node_modules/job-forge/\`; most files you need are accessible through symlinks at the project root.
 
 **How context loads in this project:** opencode auto-loads *this* file as the project-root AGENTS.md, then loads \`AGENTS.harness.md\` plus \`.opencode/instructions.md\` via \`opencode.json:instructions\`. \`AGENTS.harness.md\` is the shared cross-harness contract; \`.opencode/instructions.md\` is reserved for OpenCode-only addenda. Keep *this* file for personal overrides — anything you want to diverge from or add on top.
 
@@ -442,7 +446,7 @@ node_modules/
 
 write('README.md', `# ${name}
 
-Personal job search project using the [job-forge](https://github.com/razroo/JobForge) harness.
+Personal job search project using the [job-forge](https://github.com/Agent-Pattern-Labs/JobForge) harness.
 
 ## Setup
 
@@ -459,7 +463,7 @@ Then fill in:
 ## Updating the harness
 
 \`\`\`bash
-npm update job-forge       # pulls the latest from razroo/JobForge
+npm update job-forge       # pulls the latest from Agent-Pattern-Labs/JobForge
 job-forge sync             # re-run if symlinks drift
 \`\`\`
 

package/bin/geometra-mcp-launcher.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_FALLBACK_PACKAGE = '@geometra/mcp@1.61.3';
+const RESOLVE_ONLY_FLAG = '--job-forge-resolve-target';
+
+function normalizeEnv(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function resolveExplicitPath(rawPath) {
+  const resolvedPath = resolve(rawPath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`JOB_FORGE_GEOMETRA_MCP_PATH points to a missing file: ${resolvedPath}`);
+  }
+  return resolvedPath;
+}
+
+export function resolveGeometraMcpLaunchTarget() {
+  const explicitPath = normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_PATH);
+  if (explicitPath) {
+    const resolvedPath = resolveExplicitPath(explicitPath);
+    return {
+      source: 'env-path',
+      command: process.execPath,
+      args: [resolvedPath],
+      resolvedPath,
+    };
+  }
+
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const siblingRepoPath = resolve(scriptDir, '../../geometra/mcp/dist/index.js');
+  if (existsSync(siblingRepoPath)) {
+    return {
+      source: 'sibling-repo',
+      command: process.execPath,
+      args: [siblingRepoPath],
+      resolvedPath: siblingRepoPath,
+    };
+  }
+
+  const packageSpec = normalizeEnv(process.env.JOB_FORGE_GEOMETRA_MCP_PACKAGE) ?? DEFAULT_FALLBACK_PACKAGE;
+  return {
+    source: 'npm-package',
+    command: 'npx',
+    args: ['-y', packageSpec],
+    packageSpec,
+  };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const target = resolveGeometraMcpLaunchTarget();
+
+  if (argv.length === 1 && argv[0] === RESOLVE_ONLY_FLAG) {
+    process.stdout.write(`${JSON.stringify(target, null, 2)}\n`);
+    return;
+  }
+
+  const child = spawn(target.command, [...target.args, ...argv], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  child.on('error', (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  void main();
+}