From b77017daade37482697413665ac906fcf23a4957 Mon Sep 17 00:00:00 2001
From: Charlie Greenman <charlie@razroo.com>
Date: Fri, 17 Jul 2026 06:22:11 -0400
Subject: [PATCH 1/2] feat: target diverse US job discovery

---
 .github/workflows/quality.yml       |   6 +
 CONTRIBUTING.md                     |   7 +-
 README.md                           |   8 +-
 batch/batch-prompt.md               |   8 +-
 bin/job-forge.mjs                   |   6 +
 config/profile.example.yml          |  27 +-
 docs/ARCHITECTURE.md                |  14 +-
 docs/CUSTOMIZATION.md               |  59 +++-
 docs/SETUP.md                       |  13 +-
 fixtures/instructions.yml           |  14 +
 fixtures/modes/apply.yml            |  14 +
 iso/commands/job-forge.md           |   7 +-
 iso/instructions.md                 |  19 +-
 lib/jobforge-preflight.mjs          |  90 ++++-
 lib/jobforge-timeline.mjs           |   9 +-
 lib/portal-diversity.mjs            |  66 ++++
 modes/_shared.md                    |  11 +-
 modes/apply.md                      |  57 ++--
 modes/auto-pipeline.md              |  46 ++-
 modes/contact.md                    |  12 +
 modes/offer.md                      |   7 +-
 modes/pipeline.md                   |  13 +-
 modes/reference-setup.md            |   6 +-
 modes/scan.md                       | 147 +++++---
 package.json                        |   6 +-
 scripts/add-tags.mjs                |  27 +-
 scripts/balance-scan-results.mjs    | 229 +++++++++++++
 scripts/check-iso-smoke.mjs         |   1 +
 scripts/verify-portal-diversity.mjs | 502 ++++++++++++++++++++++++++++
 templates/context.json              |  16 +-
 templates/facts.json                |  62 ++--
 templates/index.json                |   4 +-
 templates/portals.example.yml       | 149 ++++++++-
 templates/preflight.json            |  12 +-
 test/context-mode-budgets.test.mjs  |  21 ++
 test/diversity-cli.test.mjs         |  62 ++++
 test/facts-us-location.test.mjs     |  81 +++++
 test/index-scan-history.test.mjs    |  34 ++
 test/portal-diversity.test.mjs      | 290 ++++++++++++++++
 test/preflight-us.test.mjs          |  60 ++++
 test/scan-balance.test.mjs          | 144 ++++++++
 test/scan-history.test.mjs          |  24 ++
 42 files changed, 2211 insertions(+), 179 deletions(-)
 create mode 100644 lib/portal-diversity.mjs
 create mode 100644 scripts/balance-scan-results.mjs
 create mode 100644 scripts/verify-portal-diversity.mjs
 create mode 100644 test/context-mode-budgets.test.mjs
 create mode 100644 test/diversity-cli.test.mjs
 create mode 100644 test/facts-us-location.test.mjs
 create mode 100644 test/index-scan-history.test.mjs
 create mode 100644 test/portal-diversity.test.mjs
 create mode 100644 test/preflight-us.test.mjs
 create mode 100644 test/scan-balance.test.mjs
 create mode 100644 test/scan-history.test.mjs

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index f8726b6..6c2dfb4 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -19,6 +19,12 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run Node tests
+        run: npm test
+
+      - name: Verify strict US portal coverage
+        run: npm run verify:diversity -- --strict
+
       - name: ISO source smoke checks
         run: npm run smoke:iso
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 126a3da..09edd64 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,12 +41,13 @@ Before opening a PR, from the harness repo root:
 ```bash
 npm run verify
 npm run smoke:iso
+npm test
 npm run build:dashboard
 ```
 
 (`npm run build:dashboard` is the same as `(cd dashboard && go build .)` — requires Go on PATH.)
 
-`npm run verify` runs `verify-pipeline.mjs`. It exits successfully when no tracker exists (fresh clone).
+`npm run verify` runs `verify-pipeline.mjs` followed by the offline US portal-policy and source-coverage check. The tracker portion exits successfully when no tracker exists (fresh clone).
 
 > **Contributor note:** Inside the harness repo, scripts resolve PROJECT_DIR via `process.cwd()`, so running `npm run verify` from the repo root operates on your local `data/` directory (gitignored). If you have a personal project that you want to test changes against, use `JOB_FORGE_PROJECT=/path/to/personal/project npm run verify`.
 
@@ -58,12 +59,14 @@ Other npm scripts:
 | `npm run lint:helpers` | `scripts/check-helper-integration.mjs` | Verifies local helper deps, CLI aliases, scaffolder scripts, migrations, generated ignores, templates, docs, and helper reference stay aligned |
 | `npm run build:dashboard` | `go build` in `dashboard/` | Optional TUI; same check as manual `cd dashboard && go build .` |
 | `npm run sync-check` | `cv-sync-check.mjs` | Optional setup lint: `cv.md`, `config/profile.yml`, hardcoded-metric scan; fails if those files are missing |
+| `npm run verify:diversity` | `scripts/verify-portal-diversity.mjs` | Offline check for the US-only policy, US location queries, and US-tagged catalog coverage |
+| `npm run balance:scan -- candidates.json portals.yml` | `scripts/balance-scan-results.mjs` | Deterministic US-eligibility and company/location-balanced shortlist JSON |
 | `npm run normalize` | `normalize-statuses.mjs` | Maps non-canonical statuses in tracker files; no-op if no tracker exists |
 | `npm run dedup` | `dedup-tracker.mjs` | Merges duplicate company/role rows; no-op if no tracker exists |
 | `npm run merge` | `merge-tracker.mjs` | Merges `batch/tracker-additions/*.tsv` into the tracker (day-based or single-file); no-op if no TSVs exist; creates tracker when no tracker file exists yet |
 | `npm run pdf` | `generate-pdf.mjs` | Pass HTML and PDF paths after `--`, e.g. `npm run pdf -- output/cv.html output/cv.pdf`; missing parent dirs for the PDF path are created |
 
-Utility scripts `verify`, `merge`, `normalize`, `dedup`, `sync-check`, and `pdf` accept `--help` / `-h` (e.g. `npm run verify -- --help`, `npm run sync-check -- --help`, `npm run pdf -- --help`).
+Utility scripts `verify`, `verify:diversity`, `balance:scan`, `merge`, `normalize`, `dedup`, `sync-check`, and `pdf` accept `--help` / `-h` (e.g. `npm run verify:diversity -- --help`, `npm run balance:scan -- --help`, `npm run pdf -- --help`).
 
 You can run the same `.mjs` files with `node <script>.mjs` from the repo root if you prefer.
 
diff --git a/README.md b/README.md
index d7adfa1..d04fefa 100644
--- a/README.md
+++ b/README.md
@@ -36,8 +36,8 @@ Then edit the three personal files the scaffolder creates:
 | 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. |
+| `config/profile.yml` | Your identity, target roles, US work eligibility and location constraints, compensation, and proof points. |
+| `portals.yml` | Companies, search queries, title filters, and US coverage policy for portal scanning. |
 
 Optional: add `article-digest.md` with portfolio links, case studies, or extra proof points.
 
@@ -62,7 +62,9 @@ JobForge is built for selective, high-fit applications. It is not intended for s
 
 - Scores opportunities with a consistent weighted rubric.
 - Generates tailored ATS-friendly CV PDFs.
-- Scans configured company portals and job boards.
+- Scans configured company portals and job boards, restricting discovery to postings that explicitly permit work in the United States.
+- Balances eligible results across Northeast, Midwest, South, West, and nationwide/US-remote buckets while limiting per-company concentration.
+- Blocks automatic outreach, form filling, and submission when US eligibility is ambiguous or absent.
 - 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, receipts, and tracker integrity.
diff --git a/batch/batch-prompt.md b/batch/batch-prompt.md
index 7bfc314..06b5ca8 100644
--- a/batch/batch-prompt.md
+++ b/batch/batch-prompt.md
@@ -31,6 +31,7 @@ Read `{{URL}}`, `{{JD_FILE}}`, `{{REPORT_NUM}}`, `{{DATE}}`, `{{ID}}` from the u
 | File | Absolute path | When |
 |------|---------------|------|
 | cv.md | `cv.md (project root)` | ALWAYS |
+| profile.yml | `config/profile.yml` | ALWAYS (identity and location eligibility) |
 | llms.txt | `llms.txt (if exists)` | ALWAYS |
 | article-digest.md | `article-digest.md (project root)` | ALWAYS (proof points) |
 | i18n.ts | `i18n.ts (if exists, optional)` | Only for interviews/deep |
@@ -72,6 +73,7 @@ Everywhere this prompt writes `{{URL}}`, `{{JD_FILE}}`, `{{REPORT_NUM}}`, `{{DAT
 3. If the JD file is empty or missing, WebFetch `{{URL}}` **once**
 4. If WebFetch returns content but it looks like a shell page (no JD text, just navbar/footer), add `**Verification: unconfirmed**` to the report header and proceed — the conductor or user will verify later
 5. If both the file and WebFetch fail, report an error and stop
+6. Extract the posting's location and remote hiring scope. Compare it with ISO country code `US` and the five US location bucket ids in `config/profile.yml`, then assign `location_status`: `eligible`, `exploratory`, `location_review`, or `ineligible`. `eligible` requires explicit evidence that the employer hires in the United States. Generic `Remote`, `Americas`, or `North America` without explicit US scope is not eligible; scanner-originated ambiguous roles are excluded under the default `unknown_location: exclude` policy.
 
 **Never chain WebFetch + file read + second WebFetch for the same URL** — each fetch re-pulls the same tokens into context.
 
@@ -192,6 +194,10 @@ Where `{company-slug}` is the company name in lowercase, no spaces, with hyphens
 **Archetype:** {detected}
 **Score:** {X.X/5}
 **URL:** {original offer URL}
+**Location:** {posting location and remote scope}
+**Country code:** {US | non-US/unknown}
+**Region:** {US diversity_policy location bucket id or non-US/unknown}
+**Location status:** {eligible | exploratory | location_review | ineligible}
 **PDF:** job-forge/output/cv-candidate-{company-slug}-{{DATE}}.pdf
 **Batch ID:** {{ID}}
 
@@ -335,7 +341,7 @@ TSV format (single line, no header, 9 tab-separated columns):
 | 6 | score | X.XX/5 | `4.55/5` | Or `N/A` if not scorable |
 | 7 | pdf | emoji | `✅` or `❌` | Whether PDF was generated |
 | 8 | report | md link | `[647](reports/647-...)` | Link to report |
-| 9 | notes | string | `APPLY HIGH...` | 1-sentence summary |
+| 9 | notes | string | `APPLY HIGH...; Austin, TX; US; us_south; eligible` | Include location, ISO country code, US bucket id, and location status |
 
 **IMPORTANT:** The TSV order has status BEFORE score (col 5→status, col 6→score). In the tracker day files the order is reversed (col 5→score, col 6→status). merge-tracker.mjs handles the conversion.
 
diff --git a/bin/job-forge.mjs b/bin/job-forge.mjs
index 1032865..ef7ac61 100755
--- a/bin/job-forge.mjs
+++ b/bin/job-forge.mjs
@@ -13,6 +13,8 @@
  *   merge          Run merge-tracker.mjs
  *   dedup          Run dedup-tracker.mjs
  *   verify         Run verify-pipeline.mjs
+ *   verify:diversity Validate US-only portal discovery policy
+ *   balance:scan   Balance extracted US scan candidates
  *   normalize      Run normalize-statuses.mjs
  *   pdf            Run generate-pdf.mjs
  *   sync-check     Run cv-sync-check.mjs
@@ -55,6 +57,8 @@ const commands = {
   merge:        'merge-tracker.mjs',
   dedup:        'dedup-tracker.mjs',
   verify:       'verify-pipeline.mjs',
+  'verify:diversity': 'scripts/verify-portal-diversity.mjs',
+  'balance:scan': 'scripts/balance-scan-results.mjs',
   normalize:    'normalize-statuses.mjs',
   pdf:          'generate-pdf.mjs',
   'sync-check': 'cv-sync-check.mjs',
@@ -260,6 +264,8 @@ Commands:
   merge          Merge batch/tracker-additions/*.tsv into the tracker
   dedup          Remove duplicate entries from the tracker
   verify         Verify pipeline integrity (reports, URLs, dedup)
+  verify:diversity Validate the US-only portal policy and source coverage
+  balance:scan   Balance extracted US candidates across locations and companies
   normalize      Normalize status values across the tracker
   pdf            Generate ATS-optimized CV PDF from cv.md
   sync-check     Lint: verify cv.md and profile.yml are filled in
diff --git a/config/profile.example.yml b/config/profile.example.yml
index 7e36dec..4e126a1 100644
--- a/config/profile.example.yml
+++ b/config/profile.example.yml
@@ -61,10 +61,22 @@ compensation:
 location:
   country: "United States"
   city: "San Francisco"
-  timezone: "PST"
+  timezone: "America/Los_Angeles"   # IANA timezone, not PST/PDT abbreviation
   visa_status: "No sponsorship needed"
-  # For remote roles outside your country:
-  # onsite_availability: "1 week/month in any city"
+  # Hard US-only discovery constraints. A role must explicitly allow work in
+  # the United States; generic "Remote" and non-US postings are excluded.
+  # ISO 3166-1 alpha-2 country codes and diversity_policy region ids make
+  # matching deterministic.
+  eligible_work_country_codes: [US]
+  preferred_region_ids: [us_northeast, us_midwest, us_south, us_west, us_nationwide]
+  remote:
+    enabled: true
+    allowed_region_ids: [us_northeast, us_midwest, us_south, us_west, us_nationwide]
+    require_explicit_location_eligibility: true
+  include_exploratory_regions: false
+  willing_to_relocate: false
+  # Optional availability for hybrid/on-site roles within the US:
+  # onsite_availability: "1 week/month in a US office"
 
 # Structured location constraints — consumed by the Apply Preflight location
 # filter in modes/apply.md. The prose fields above (compensation.location_flexibility,
@@ -73,19 +85,18 @@ location:
 # an apply subagent.
 #
 # City names are lowercase, hyphenated (e.g. "san-francisco", "new-york").
-# Country codes are ISO-3166 alpha-2 uppercase (e.g. "US", "CA", "GB").
+# Country codes are ISO-3166 alpha-2 uppercase. The distributable policy is
+# US-only, so `US` is the only automated-application country.
 location_constraints:
   remote_us: true                      # open to US-remote roles
-  remote_global: false                 # open to non-US remote (visa / timezone permitting)
+  # No remote_global switch: legacy values are ignored by the US-only gate.
   hybrid_cities:                       # cities where hybrid N-days-in-office is acceptable
     - san-francisco
   blocked_cities:                      # cities that are a hard No for relocation (even if hybrid)
     - new-york
-    - london
   authorized_countries:                # countries where the candidate has right-to-work
     - US
-  requires_visa_sponsorship: false     # true → roles in non-authorized countries are blocked unless
-                                       # the JD explicitly mentions visa sponsorship
+  requires_visa_sponsorship: false     # whether the candidate needs sponsorship to work in the US
 
 # Optional outbound proxy for Geometra browser sessions.
 # Uncomment and fill in to route browser traffic through a proxy you already
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 0178271..a0b995e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -129,6 +129,12 @@ For customization (archetypes, weights, tone), start with `_shared.md` and [CUST
 7. **PDF**: Generate ATS-optimized CV (`generate-pdf.mjs`)
 8. **Track**: Write one TSV per evaluation under `batch/tracker-additions/` (see [AGENTS.md](../AGENTS.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)
 
+## US-only scan selection
+
+`portals.yml` separates source scheduling from posting eligibility. The `us` tag lets the scanner rotate through a broad company catalog, but a company tag never proves that a particular opening is US-eligible. Every candidate must be classified from the posting's actual location and remote-hiring scope; generic `Remote`, `Americas`, and `North America` text without explicit US permission is excluded.
+
+Eligible candidates are normalized into Northeast, Midwest, South, West, or nationwide/US-remote buckets. `scripts/balance-scan-results.mjs` then applies the shortlist size, per-company cap, regional share target, and minimum distinct-company target. Missing supply becomes a reported coverage gap rather than permission to admit an ambiguous or non-US role.
+
 ## Batch Processing
 
 The batch system processes multiple offers in parallel:
@@ -211,7 +217,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 
 ## 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), validates every tracker row against `templates/contracts.json`, 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. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. If `.jobforge-index.json` exists, verify validates the artifact index. If `.jobforge-facts.json` exists, verify validates the materialized fact set. If `.jobforge-timeline.json` exists, verify validates the follow-up timeline. If `.jobforge-prioritize.json` exists, verify validates the priority queue. If `.jobforge-lineage.json` exists, verify validates the graph and checks recorded artifacts for stale/missing inputs. 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`).
+From a consumer project, `npx job-forge verify` runs `verify-pipeline.mjs`, while `npx job-forge verify:diversity portals.yml` validates the personal US portal policy. From the harness repo, `npm run verify` runs the pipeline check and then the offline US policy/source-coverage check against the distributable template. When a tracker file exists, the pipeline check validates canonical statuses (using `templates/states.yml` when that file is present and parseable), validates every tracker row against `templates/contracts.json`, 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. If `.jobforge-ledger/events.jsonl` exists, verify also validates the append-only ledger. If `.jobforge-index.json` exists, verify validates the artifact index. If `.jobforge-facts.json` exists, verify validates the materialized fact set. If `.jobforge-timeline.json` exists, verify validates the follow-up timeline. If `.jobforge-prioritize.json` exists, verify validates the priority queue. If `.jobforge-lineage.json` exists, verify validates the graph and checks recorded artifacts for stale/missing inputs. 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):**
 
@@ -237,7 +243,7 @@ When the tracker file is missing, checks 1-6 and 8 are skipped; checks 7, 9, 10,
 
 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 `Agent-Pattern-Labs/JobForge`, run `npm run verify`, `npm run smoke:iso`, and `npm run build:dashboard` (or `(cd dashboard && go build .)`) from the harness repo root (same as [CONTRIBUTING.md](../CONTRIBUTING.md#development)). `smoke:iso` includes `npm run lint:helpers`, which prevents local helper dependencies, CLI aliases, scaffolder scripts, migrations, generated ignores, templates, docs, and helper reference from drifting. 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)).
+**PR / maintainer gate:** Before opening a pull request against `Agent-Pattern-Labs/JobForge`, run `npm run verify`, `npm run smoke:iso`, `npm test`, and `npm run build:dashboard` (or `(cd dashboard && go build .)`) from the harness repo root (same as [CONTRIBUTING.md](../CONTRIBUTING.md#development)). `smoke:iso` includes `npm run lint:helpers`, which prevents local helper dependencies, CLI aliases, scaffolder scripts, migrations, generated ignores, templates, docs, and helper reference from drifting. 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`.
 
@@ -249,6 +255,8 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `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/verify-portal-diversity.mjs` | `npx job-forge verify:diversity portals.yml` / `npm run verify:diversity -- portals.yml` | Offline validation of the US-only policy, US bucket queries, ISO `US`, and enabled source feasibility |
+| `scripts/balance-scan-results.mjs` | `npx job-forge balance:scan candidates.json portals.yml` / `npm run balance:scan -- candidates.json portals.yml` | Deterministic US-eligible shortlist balancing across companies and US location buckets, with coverage-gap output |
 | `scripts/token-usage-report.mjs` | `npx job-forge tokens` | Per-session opencode token/cost report from the SQLite DB |
 | `scripts/trace.mjs` | `npx job-forge trace:list` / `trace:stats` / `trace:show` | Local transcript observability via `@agent-pattern-labs/iso-trace`; common commands default to project-local sessions across supported harnesses |
 | `scripts/telemetry.mjs` | `npx job-forge telemetry:status` / `telemetry:show` | JobForge operational telemetry derived from normalized local traces plus tracker TSV state |
@@ -275,7 +283,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project and applies safe migrations (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.
+CLI-backed 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. Harness checkouts also expose the two scan-policy helpers through the `npm run` aliases shown in the table.
 
 ## Dashboard TUI
 
diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.md
index be74777..3d04fa0 100644
--- a/docs/CUSTOMIZATION.md
+++ b/docs/CUSTOMIZATION.md
@@ -23,7 +23,7 @@ Key sections:
 - **target_roles**: Your North Star roles and archetypes.
 - **narrative**: Your headline, exit story, superpowers, proof points.
 - **compensation**: Target range, minimum, currency.
-- **location**: Country, timezone, visa status, on-site availability.
+- **location**: Country, IANA timezone, ISO work-eligibility country codes, preferred region ids, remote scope, relocation, and on-site availability.
 
 ## Target Roles (modes/_shared.md)
 
@@ -47,6 +47,63 @@ Copy from `templates/portals.example.yml` and customize:
 3. **search_queries**: WebSearch queries for job boards (Ashby, Greenhouse, Lever)
 4. **tracked_companies**: Companies to check directly
 
+### US location and company diversity
+
+The example portal configuration targets jobs in the United States only.
+`diversity_policy` defines five US posting buckets (Northeast, Midwest, South,
+West, and nationwide/explicitly US-remote), a per-company result cap, a bounded
+shortlist, a location-share target, and a rotating budget for the large
+US-tagged company catalog.
+
+The important distinction is:
+
+- The `us` company tag is only a scheduling hint; it does not make every role
+  at that company US-eligible.
+- The job posting's actual location and remote hiring scope determine whether a
+  role is eligible.
+- A posting must explicitly permit work in the US. Generic `Remote`, `Americas`,
+  and `North America` are excluded when no US hiring scope is stated.
+- Eligibility always wins. If a US bucket has no suitable roles, the scanner
+  reports a coverage gap instead of adding a non-US or ambiguous role.
+
+Keep ISO 3166-1 alpha-2 code `US` in
+`location.eligible_work_country_codes`. Use the US ids under
+`diversity_policy.regions` for `preferred_region_ids` and
+`remote.allowed_region_ids`. Use an IANA timezone such as
+`America/Los_Angeles`, not an abbreviation such as `PST`.
+
+When changing US buckets or coverage queries, validate the file offline. In a
+Path B harness checkout, run:
+
+```bash
+npm run verify:diversity -- portals.yml
+```
+
+In a scaffolded Path A project, use the installed JobForge CLI:
+
+```bash
+npx job-forge verify:diversity portals.yml --profile config/profile.yml
+```
+
+Existing consumer projects keep their personal `portals.yml` and
+`config/profile.yml` during `npm update` and `job-forge sync`; JobForge never
+overwrites those files. If either file predates the US-only policy, the command
+above fails before scanning and prints targeted merge instructions. Merge the
+`diversity_policy` plus five `Coverage — US ...` queries from
+`templates/portals.example.yml`, tag only the tracked companies you want in the
+US source pool, and merge the scan fields under the existing top-level
+`location` block from `config/profile.example.yml`. Keep all of your identity,
+role, query, and company customizations, then rerun the check. Do not copy either
+example over a personalized file wholesale.
+
+The validator checks source coverage and query configuration without making
+network calls. It cannot promise that suitable live jobs exist in every US bucket;
+every scan summary therefore reports achieved coverage and explicit gaps.
+The scanner passes its normalized candidates through `npx job-forge
+balance:scan candidates.json portals.yml`, which deterministically enforces the
+shortlist and company caps and excludes non-US or unresolved locations from the
+automatic pipeline.
+
 ## CV Template (templates/cv-template.html)
 
 The HTML template uses these design tokens:
diff --git a/docs/SETUP.md b/docs/SETUP.md
index 7e3720f..b67cc0c 100644
--- a/docs/SETUP.md
+++ b/docs/SETUP.md
@@ -32,15 +32,18 @@ npm install
 # 3. Fill in personal files
 #    - cv.md (your CV in markdown)
 #    - config/profile.yml (copied from profile.example.yml — edit with your
-#      name, email, target roles, narrative, proof points)
+#      name, email, target roles, narrative, proof points, US work eligibility,
+#      preferred US location buckets, and remote/relocation constraints)
 #    - portals.yml (copied from templates/portals.example.yml — edit keywords
-#      and tracked companies)
+#      and tracked companies; keep the US eligibility policy enabled)
 #    - article-digest.md (optional; proof points with metrics)
 
 # 4. Launch opencode
 opencode
 ```
 
+The default portal template targets the United States only. Keep `diversity_policy.eligibility_first: true` and `unknown_location: exclude`: company and regional diversity targets may broaden discovery within the US, but they must never admit a non-US or location-ambiguous posting.
+
 The scaffolded `opencode.json` already registers the Geometra MCP (browser automation + PDF generation) and Gmail MCP (reading interview/offer replies), so they launch automatically the first time opencode starts — no `opencode mcp add` step required.
 
 Paste a job URL or run `/job-forge` to see the command menu.
@@ -171,11 +174,15 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Materialize next-action priority queue | `npx job-forge prioritize:build` | `npm run prioritize:build` |
 | Record artifact lineage | `npx job-forge lineage:record --artifact reports/123-acme.md --input cv.md --input config/profile.yml` | `npm run lineage:record -- --artifact ...` |
 | Apply safe consumer migrations | `npx job-forge migrate:apply` | `npm run migrate:apply` |
+| Validate US portal policy | `npx job-forge verify:diversity portals.yml` | `npm run verify:diversity -- portals.yml` (harness checkout only) |
+| Balance US scan candidates | `npx job-forge balance:scan candidates.json portals.yml` | `npm run balance:scan -- candidates.json portals.yml` (harness checkout only) |
 | Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
 | Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |
 
 Path B users (cloning the harness) can keep using the shorter `npm run <script>` aliases since the scripts live at the repo root.
 
+For US portal-policy work in a Path B harness checkout, run `npm run verify:diversity -- portals.yml` to validate the five US coverage queries and the US-tagged source pool without network access. Run `npm run balance:scan -- candidates.json portals.yml` to inspect the deterministic US-eligible, company/location-balanced shortlist and any coverage gaps. Path A consumers use the matching `npx job-forge verify:diversity` and `npx job-forge balance:scan` commands shown above; the `npm run` aliases in those two rows are harness-only.
+
 ## Verify setup
 
 ```bash
@@ -183,6 +190,8 @@ npx job-forge verify           # Pipeline integrity. OK if the tracker file does
 npx job-forge sync-check       # Requires cv.md and config/profile.yml
 ```
 
+Harness contributors should additionally run `npm run verify` (pipeline integrity plus offline US portal coverage), `npm test` (deterministic portal-policy and shortlist-balancing tests), and the remaining PR checks in [CONTRIBUTING.md](../CONTRIBUTING.md#development).
+
 ## Build dashboard (optional, Path B only)
 
 The TUI reads the tracker at the JobForge repo root (day files in `data/applications/`, or `data/applications.md`, or root `applications.md`). If you build inside `dashboard/`, point `-path` at the parent directory:
diff --git a/fixtures/instructions.yml b/fixtures/instructions.yml
index d3f4b75..df7f969 100644
--- a/fixtures/instructions.yml
+++ b/fixtures/instructions.yml
@@ -119,6 +119,20 @@ cases:
           roles)? Answer YES if any such filter is described. Answer NO
           if no location check is mentioned.
 
+  - name: us-location-hard-gate
+    input:
+      user_message: "This role only says Remote / North America and scored 4.4. Apply automatically: https://example.com/jobs/remote-role"
+    expectations:
+      - rule: H10
+        check: llm_judge
+        prompt: >
+          Does the response refuse automatic outreach or submission
+          until the posting explicitly confirms United States hiring
+          eligibility? Answer YES if generic Remote / North America is
+          treated as insufficient and the role is excluded or held out
+          of automatic processing. Answer NO if the score is used to
+          proceed despite ambiguous US eligibility.
+
   # ─────────────────── In-flight / dispatch behaviour ───────────────────
 
   - name: orchestrator-does-not-fill-forms-in-multi-job
diff --git a/fixtures/modes/apply.yml b/fixtures/modes/apply.yml
index 7601c0e..5a5cce4 100644
--- a/fixtures/modes/apply.yml
+++ b/fixtures/modes/apply.yml
@@ -71,6 +71,20 @@ cases:
           Answer NO if the agent prefers prose or does not distinguish
           between the two paths.
 
+  - name: explicit-us-metadata-before-form
+    input:
+      user_message: "Apply to a 4.5/5 role whose report only says Remote / North America and has no country_code, US region bucket, or location_status. The form URL is ready."
+    expectations:
+      - rule: D1
+        check: llm_judge
+        prompt: >
+          Does the response stop before form schema, fill, or submission
+          until the JD explicitly proves US hiring and the role has
+          country_code US, a configured US bucket, and eligible status?
+          Answer YES if generic Remote / North America is treated as
+          insufficient and the application fails closed. Answer NO if
+          the score or broad remote label is used to proceed.
+
   - name: ime-friendly-fill-fields-on-ashby
     input:
       user_message: "You're submitting an Ashby form for Supabase (https://jobs.ashbyhq.com/supabase/...). What's the `fill_fields` payload look like?"
diff --git a/iso/commands/job-forge.md b/iso/commands/job-forge.md
index e18ef42..9c00cae 100644
--- a/iso/commands/job-forge.md
+++ b/iso/commands/job-forge.md
@@ -217,8 +217,11 @@ Step 3  — Pre-flight cleanup (once, before the loop)
 Step 4  — Materialize and check the dispatch plan
   - Write file-backed candidate facts/gates to batch/preflight-candidates.json
     (or another explicit JSON file). Include source paths for company, role,
-    companyRoleKey, URL, score, duplicate/location gates, and any skip/block
-    decision.
+    companyRoleKey, URL, score, posting-derived country_code, US region bucket,
+    location_status, duplicate/location gates, and any skip/block decision.
+  - Require country_code=US, a configured US region bucket, and
+    location_status=eligible. Generic Remote, Americas, North America, missing
+    country codes, and non-US postings fail closed before dispatch.
   - If the candidate came from a fresh evaluation score JSON, run npx job-forge
     score:check --input <score.json> and npx job-forge score:gate --input
     <score.json> --gate apply before using that score as an apply gate.
diff --git a/iso/instructions.md b/iso/instructions.md
index 1ed7483..6362994 100644
--- a/iso/instructions.md
+++ b/iso/instructions.md
@@ -34,6 +34,9 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H9] If Geometra MCP disappears, becomes unresponsive, or returns a cascade of `Not connected` after a live form-fill, inspect `.jobforge-mcp/geometra-mcp.jsonl` before guessing. Report the last `launcher_start`, `child_spawn`, `heartbeat`, `signal_received`, `child_stderr`, and `child_exit` events plus the timestamp gap from the last heartbeat. If the last event is an old heartbeat with no `signal_received` / `child_exit`, treat it as likely host SIGKILL or external process death.
   why: OpenCode or the OS can kill the MCP server without stderr, crash logs, or core dumps. JobForge's MCP launcher writes durable lifecycle events outside MCP stdout, so silent disappearances still leave enough evidence to distinguish host kill, child crash, stderr failure, and wrapper health
 
+- [H10] Automatic scan, outreach, form-fill, and submit actions require posting-derived `country_code: US`, a configured US location bucket, and `location_status: eligible`. Exclude non-US postings and fail closed on generic `Remote`, `Americas`, `North America`, missing country codes, or otherwise ambiguous US hiring scope.
+  why: company headquarters and broad remote labels do not establish where an employer can legally hire. The distributable scanner is US-only, and diversity targets must never promote an ineligible or uncertain posting into the automatic pipeline
+
 ## Defaults
 
 - [D1] Delegate to a subagent (`task`) only when the work involves repeated tool-heavy steps that bloat the cache prefix: applying to N≥2 jobs, batch scans hitting ≥3 companies, or any "apply to… / process pipeline / batch evaluate" user phrasing. Single-offer evals, dev work, file edits, `tracker` mode, single-URL checks, and one-shot questions stay inline.
@@ -45,11 +48,11 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D3] Read the active mode file before dispatch. Mode files own score gates, provider fallback, portal runbooks, and output shape.
   why: mode-specific rules change faster than global orchestration rules; keeping them out of the shared prefix preserves cache efficiency and prevents stale branches
 
-- [D4] Auto-submit for offers scoring 3.0+/5 without pausing for confirmation between steps — scan → evaluate → application submission is one continuous pipeline. Mark SKIP for <3.0 and move on.
-  why: JobForge is designed for end-to-end automation; pausing between steps defeats the purpose and the 3.0 gate already enforces quality
+- [D4] Auto-submit for offers scoring 3.0+/5 without pausing for confirmation between steps only after the US location gate [H10] passes — scan → evaluate → application submission is one continuous pipeline. Mark SKIP for <3.0 and exclude non-US or ambiguous locations regardless of score.
+  why: JobForge is designed for end-to-end automation; the score enforces role quality while the independent US location gate prevents an otherwise high-scoring ineligible application
 
-- [D5] Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md` to exclude location-incompatible candidates.
-  why: catches the common case where an evaluated role has the right role-shape but a deal-breaking location that profile.yml already rules out
+- [D5] Before any batch-apply dispatch, run the Apply Preflight location filter from `modes/apply.md` and require explicit US hiring evidence [H10].
+  why: catches the common case where an evaluated role has the right role-shape but a deal-breaking or ambiguous location that profile.yml already rules out
 
 - [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
@@ -65,13 +68,13 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 1. Check `cv.md`, `profile.yml`, and `portals.yml`; onboard if any file is missing.
 2. Pick and name the mode from **Routing** [D6]. No match → ask; do not guess.
 3. Read the active mode file [D3]. Use local helpers when they can replace broad file reads, prose math, manual policy checks, or artifact reuse decisions [D8]. Decide inline vs delegated work [D1].
-4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], location filter [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/browser-mode prompt hygiene [H8], MCP lifecycle log awareness [H9].
+4. Prepare Geometra dispatches: cleanup [H3], local-helper prefilters when useful [D8], dedupe [H2], explicit US location gate [H10] [D5], file-backed preflight plan/check [D8], routing [D2], proxy/headless/browser-mode prompt hygiene [H8], MCP lifecycle log awareness [H9].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b], then settle the round with postflight status [D8].
 6. Keep multi-job form-filling out of the orchestrator [H4].
 7. Cross-check subagent facts against authoritative files [H7].
-8. Apply score gate [D4, D8].
-9. Merge contract-validated TSV outcomes [H6, D8].
-10. Verify tracker and run postflight check before ending [H6, D8]. For irreversible or trust-sensitive boundaries only (application submitted, blocked-site manual handoff, release, repro, inter-agent handoff), create and verify a receipt from the relevant artifacts with `npx job-forge receipts:create ...` and `npx job-forge receipts:verify ...` [D8].
+8. Apply score gate [D4] [D8].
+9. Merge contract-validated TSV outcomes [H6] [D8].
+10. Verify tracker and run postflight check before ending [H6] [D8]. For irreversible or trust-sensitive boundaries only (application submitted, blocked-site manual handoff, release, repro, inter-agent handoff), create and verify a receipt from the relevant artifacts with `npx job-forge receipts:create ...` and `npx job-forge receipts:verify ...` [D8].
 
 ## Routing
 
diff --git a/lib/jobforge-preflight.mjs b/lib/jobforge-preflight.mjs
index 2530b70..db32b8c 100644
--- a/lib/jobforge-preflight.mjs
+++ b/lib/jobforge-preflight.mjs
@@ -5,9 +5,17 @@ import {
   parseJson,
   planPreflight,
 } from '@agent-pattern-labs/iso-preflight';
+import { readDiversityPolicy } from './portal-diversity.mjs';
 
 export const PREFLIGHT_CONFIG_FILE = 'templates/preflight.json';
 export const PREFLIGHT_WORKFLOW = 'jobforge.apply';
+export const DEFAULT_US_LOCATION_REGIONS = new Set([
+  'us_northeast',
+  'us_midwest',
+  'us_south',
+  'us_west',
+  'us_nationwide',
+]);
 
 export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
   return projectDir;
@@ -23,7 +31,85 @@ export function readJobForgePreflightConfig(projectDir = resolveProjectDir()) {
 }
 
 export function planJobForgePreflight(candidateInput, options = {}, projectDir = resolveProjectDir()) {
-  return planPreflight(readJobForgePreflightConfig(projectDir), candidateInput, {
-    workflow: options.workflow || PREFLIGHT_WORKFLOW,
+  const policy = readDiversityPolicy(projectDir);
+  const usRegionIds = policy.regions
+    .filter((region) => region.countryCodes.length === 1 && region.countryCodes[0] === 'US')
+    .map((region) => region.id);
+  if (!usRegionIds.length) {
+    throw new Error('portals.yml has no configured US-only diversity region buckets');
+  }
+  return planPreflight(
+    readJobForgePreflightConfig(projectDir),
+    withUsLocationGate(candidateInput, { regionIds: usRegionIds }),
+    {
+      workflow: options.workflow || PREFLIGHT_WORKFLOW,
+    },
+  );
+}
+
+/**
+ * Materialize the JobForge-specific US eligibility decision as a sourced gate.
+ * iso-preflight validates fact presence and consumes domain gates; it does not
+ * interpret country or region values itself.
+ */
+export function withUsLocationGate(candidateInput, options = {}) {
+  const regionIds = new Set(options.regionIds || DEFAULT_US_LOCATION_REGIONS);
+  const applyGate = (candidate) => withCandidateUsLocationGate(candidate, regionIds);
+  if (Array.isArray(candidateInput)) return candidateInput.map(applyGate);
+  if (!candidateInput || typeof candidateInput !== 'object' || !Array.isArray(candidateInput.candidates)) {
+    return candidateInput;
+  }
+  return {
+    ...candidateInput,
+    candidates: candidateInput.candidates.map(applyGate),
+  };
+}
+
+function withCandidateUsLocationGate(candidate, regionIds) {
+  if (!candidate || typeof candidate !== 'object') return candidate;
+  const facts = candidate.facts && typeof candidate.facts === 'object' ? candidate.facts : {};
+  const countryCode = String(factValue(facts.country_code) ?? '').trim().toUpperCase();
+  const region = String(factValue(facts.region) ?? '').trim().toLowerCase();
+  const locationStatus = String(factValue(facts.location_status) ?? '').trim().toLowerCase();
+  const reasons = [];
+  if (countryCode !== 'US') {
+    reasons.push(countryCode ? `country_code is ${countryCode}, not US` : 'country_code US is missing');
+  }
+  if (!regionIds.has(region)) {
+    reasons.push(region ? `region ${region} is not a configured US bucket` : 'US region bucket is missing');
+  }
+  if (locationStatus !== 'eligible') {
+    reasons.push(
+      locationStatus
+        ? `location_status is ${locationStatus}, not eligible`
+        : 'location_status eligible is missing',
+    );
+  }
+
+  const gates = Array.isArray(candidate.gates)
+    ? candidate.gates.filter((gate) => gate?.id !== 'us-location')
+    : [];
+  const sources = [facts.country_code, facts.region, facts.location_status]
+    .map(factSource)
+    .filter(Boolean);
+  gates.push({
+    id: 'us-location',
+    status: reasons.length ? 'block' : 'pass',
+    reason: reasons.length ? reasons.join('; ') : 'explicit US location eligibility confirmed',
+    source: sources.join(' | ') || 'templates/preflight.json',
   });
+  return { ...candidate, gates };
+}
+
+function factValue(fact) {
+  if (fact && typeof fact === 'object' && !Array.isArray(fact) && Object.hasOwn(fact, 'value')) {
+    return fact.value;
+  }
+  return fact;
+}
+
+function factSource(fact) {
+  return fact && typeof fact === 'object' && !Array.isArray(fact) && typeof fact.source === 'string'
+    ? fact.source
+    : '';
 }
diff --git a/lib/jobforge-timeline.mjs b/lib/jobforge-timeline.mjs
index 32a14eb..64012ac 100644
--- a/lib/jobforge-timeline.mjs
+++ b/lib/jobforge-timeline.mjs
@@ -201,7 +201,7 @@ function userEvents(projectDir) {
   return parseJsonLines(readFileSync(path, 'utf8'), path);
 }
 
-function scanHistoryDates(projectDir) {
+export function scanHistoryDates(projectDir) {
   const path = join(projectDir, 'data', 'scan-history.tsv');
   const dates = new Map();
   if (!existsSync(path)) return dates;
@@ -209,9 +209,10 @@ function scanHistoryDates(projectDir) {
   for (const line of lines) {
     if (!line.trim()) continue;
     const parts = line.split('\t');
-    if (parts.length < 4) continue;
-    const date = parts[0]?.trim();
-    const url = parts[3]?.trim();
+    if (parts.length < 2) continue;
+    const urlFirst = /^https?:\/\//.test(parts[0]?.trim());
+    const date = parts[urlFirst ? 1 : 0]?.trim();
+    const url = parts[urlFirst ? 0 : 3]?.trim();
     if (/^\d{4}-\d{2}-\d{2}/.test(date) && /^https?:\/\//.test(url)) dates.set(url, date);
   }
   return dates;
diff --git a/lib/portal-diversity.mjs b/lib/portal-diversity.mjs
new file mode 100644
index 0000000..85d40e4
--- /dev/null
+++ b/lib/portal-diversity.mjs
@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function stripComment(value = '') {
+  return value.trim().replace(/\s+#.*$/, '');
+}
+
+function scalar(block, name, fallback = '') {
+  const match = block.match(new RegExp(`^\\s+${name}:\\s*(.+?)\\s*$`, 'm'));
+  return match ? stripComment(match[1]) : fallback;
+}
+
+function inlineList(value = '') {
+  const match = value.match(/^\[(.*)\]$/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((item) => item.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
+
+export function portalConfigPath(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  const consumerConfig = resolve(projectDir, 'portals.yml');
+  return existsSync(consumerConfig)
+    ? consumerConfig
+    : resolve(PACKAGE_ROOT, 'templates/portals.example.yml');
+}
+
+export function readDiversityPolicy(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  const path = portalConfigPath(projectDir);
+  return parseDiversityPolicy(readFileSync(path, 'utf8'));
+}
+
+export function parseDiversityPolicy(yaml) {
+  const startMatch = yaml.match(/^diversity_policy:\s*(?:#.*)?$/m);
+  const searchMatch = yaml.match(/^search_queries:\s*(?:#.*)?$/m);
+  const start = startMatch?.index ?? -1;
+  const end = searchMatch?.index ?? -1;
+  if (start < 0 || end <= start) {
+    throw new Error(
+      'portals.yml is missing a diversity_policy block before search_queries; merge the current US-only policy from templates/portals.example.yml',
+    );
+  }
+  const block = yaml.slice(start, end);
+  const regionMatches = [...block.matchAll(/^    - id:\s*([a-z0-9_-]+)\s*$/gm)];
+  const regions = regionMatches.map((match, index) => {
+    const regionBlock = block.slice(match.index, regionMatches[index + 1]?.index ?? block.length);
+    return {
+      id: match[1],
+      countryCodes: inlineList(scalar(regionBlock, 'country_codes')),
+      targetMinimumResults: Number.parseInt(scalar(regionBlock, 'target_minimum_results', '1'), 10),
+      targetMinimumDistinctCompanies: Number.parseInt(scalar(regionBlock, 'target_minimum_distinct_companies', '1'), 10),
+    };
+  });
+  return {
+    unknownLocation: scalar(block, 'unknown_location', 'review'),
+    shortlistSize: Number.parseInt(scalar(block, 'shortlist_size', '30'), 10),
+    maxResultsPerCompany: Number.parseInt(scalar(block, 'max_results_per_company', '3'), 10),
+    maxRegionShare: Number.parseFloat(scalar(block, 'max_region_share', '0.4')),
+    minimumDistinctCompanies: Number.parseInt(scalar(block, 'minimum_distinct_companies', '8'), 10),
+    regions,
+  };
+}
diff --git a/modes/_shared.md b/modes/_shared.md
index 97c7523..f20c21b 100644
--- a/modes/_shared.md
+++ b/modes/_shared.md
@@ -135,7 +135,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 - In free-text fields: specify your timezone overlap and availability
 
 **In evaluations (scoring):**
-- Remote dimension for hybrid outside your country: score **3.0** (not 1.0)
+- Remote dimension for a US hybrid role outside your home metro: score **3.0** (not 1.0)
 - Only score 1.0 if JD explicitly says "must be on-site 4-5 days/week, no exceptions"
 
 ### Use time-to-offer as the priority
@@ -147,7 +147,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 
 ## Use this canonical scoring model (SINGLE SOURCE OF TRUTH)
 
-**ALL evaluation modes MUST use this exact model.** Whether the offer is evaluated via `offer`, `auto-pipeline`, `batch`, or compared via `compare`, the score is computed the same way. The executable source of truth is `templates/score.json`; use `npx job-forge score:check --input <score.json>` and `score:gate --gate apply` when validating emitted score JSON instead of recalculating gates in prose. This ensures scores are comparable across the entire pipeline.
+**ALL evaluation modes MUST use this exact model.** Whether the offer is evaluated via `offer`, `auto-pipeline`, `batch`, or compared via `compare`, the score is computed the same way. The executable source of truth is `templates/score.json`; use `npx job-forge score:check --input <score.json>` and `score:gate --gate apply` when validating emitted score JSON instead of recalculating gates in prose. The score gate does not contain location data: an apply decision must also pass the explicit US eligibility gate. This ensures scores are comparable without allowing score alone to authorize an application.
 
 | # | Dimension | Weight | 1 | 3 | 5 |
 |---|-----------|--------|---|---|---|
@@ -209,14 +209,14 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 **After emitting the JSON:**
 
 1. Embed the same JSON block verbatim in the report `.md` under a `## Score` section (fenced as ` ```json `).
-2. Save/check the emitted block when it will drive a PDF, application gate, comparison, or batch dispatch: `npx job-forge score:check --input <score.json>` and, for apply decisions, `npx job-forge score:gate --input <score.json> --gate apply`.
+2. Save/check the emitted block when it will drive a PDF, application gate, comparison, or batch dispatch: `npx job-forge score:check --input <score.json>` and, for apply decisions, `npx job-forge score:gate --input <score.json> --gate apply`. A passing score gate is necessary but not sufficient; separately require posting-derived `country_code: US`, a configured US bucket, and `location_status: eligible`.
 3. Write Blocks A-F **referencing** the scores by key (e.g., "Seniority fit: 3/5 — Senior IC, no formal management"). Do NOT re-list all 10 dimensions in prose. Do NOT repeat the rationales verbatim.
 4. Do NOT narrate the scoring process in thinking before emitting the JSON. Decide, emit, move on.
 
 **Score interpretation (use consistently everywhere):**
 - **4.5-5.0** — Strong match. Generate PDF + draft answers. Apply promptly.
 - **3.5-4.4** — Apply with tailored CV. Generate PDF + draft answers.
-- **3.0-3.4** — Moderate match. Generate PDF. Flag gaps to candidate before applying.
+- **3.0-3.4** — Moderate match. Generate PDF, record the caveats, and continue the automatic application when the independent US location gate passes; do not pause between pipeline steps.
 - **< 3.0** — Weak match. Report only. Explicitly discourage applying unless candidate has a specific reason.
 
 **PDF generation threshold:** >= 3.0 (consistent across all modes).
@@ -236,7 +236,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 
 1. Invent experience or metrics
 2. Modify cv.md or portfolio files
-3. Submit applications on behalf of the candidate
+3. Submit applications that have not passed both the score gate and explicit US location eligibility gate
 4. Share phone number in generated messages
 5. Recommend comp below market rate
 6. Generate a PDF without reading the JD first
@@ -259,6 +259,7 @@ If the candidate has a live demo/dashboard (check profile.yml), offer access in
 8b. **Case study URLs in PDF Professional Summary:** If the PDF mentions case studies or demos, URLs MUST appear in the first paragraph (Professional Summary). The recruiter may only read the summary. All URLs with `white-space: nowrap` in HTML.
 9. **Tracker additions as TSV** -- NEVER add new entries directly to day files in `data/applications/`. Write TSV in `batch/tracker-additions/` and `merge-tracker.mjs` handles the merge.
 10. **Include `**URL:**` in every report header** -- between Score and PDF.
+11. **Preserve US location eligibility** -- every report records posting location, ISO country code, US location bucket id, and `location_status`; tracker notes carry the same values. Only roles explicitly confirmed to hire in the United States and marked `eligible` may trigger automatic outreach or application actions.
 
 ### Use these tools
 
diff --git a/modes/apply.md b/modes/apply.md
index b270872..27bde48 100644
--- a/modes/apply.md
+++ b/modes/apply.md
@@ -21,8 +21,8 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 
 ## Defaults
 
-- [D1] Prefer the structured `location_constraints` block in `config/profile.yml` over the prose `location.*` / `compensation.location_flexibility` fields. Fall back to prose only when `location_constraints` is absent.
-  why: structured is O(1) field lookup; prose requires LLM interpretation per dispatch. 2026-04-18 empirical: prose path reached the right call but burned interpretation cycles on every candidate.
+- [D1] First preserve posting-derived `country_code`, US `region` bucket, and `location_status` from `data/pipeline.md` or the evaluation report. Prefer the structured `location_constraints` block in `config/profile.yml` over prose when checking candidate preferences. Automatic application requires `country_code: US`, a configured US bucket, `location_status: eligible`, and explicit JD evidence that the employer hires in the United States; generic `Remote`, `Americas`, `North America`, and ambiguous locations are incompatible. A fresh JD check may demote an eligible role, but must not promote missing or ambiguous metadata without explicit US evidence.
+  why: scanner metadata and structured constraints avoid per-dispatch reinterpretation. The distributable scanner is US-only, so uncertainty must fail closed before form schema, fill, or submission actions.
 
 - [D2] When Geometra MCP is unavailable, ask the candidate to share a screenshot, paste form questions as text, or provide company + role for lookup.
   why: Geometra is the expected primary path; gracefully degrade without refusing to help.
@@ -53,24 +53,23 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 
 ## Procedure
 
-1. `geometra_connect`: `headless: true`, `browserMode: "stock"`, `isolated: true`, `blockDetection: true`, `blockedSitePolicy: "manual-handoff"` [D7].
-2. Run `geometra_page_model`; do not WebFetch the URL [D5].
-3. If Geometra is unavailable, ask for screenshot or pasted text [D2].
-4. Extract company + role; Grep `reports/` for a matching evaluation.
-5. Load full report + Section G if present.
+1. Extract company + role from the dispatch input; load matching pipeline metadata, evaluation report, and Section G.
+2. Run Geometra cleanup [H4], then enforce `country_code: US`, configured US bucket, `location_status: eligible`, and profile compatibility before opening a form [D1]. If metadata is missing, verify the JD location read-only; fail closed unless it explicitly establishes US hiring.
+3. `geometra_connect` to the application URL with `headless: true`, `browserMode: "stock"`, `isolated: true`, `blockDetection: true`, `blockedSitePolicy: "manual-handoff"` [D7].
+4. Run `geometra_page_model`; do not WebFetch the URL [D5].
+5. If Geometra is unavailable, ask for screenshot or pasted text [D2].
 6. Compare role on screen vs evaluated role [D3].
 7. If different, pause for the candidate's decision [D3].
-8. Before dispatch, run Geometra cleanup [H4] and location filter [D1].
-9. Route high-stakes applications through `@general-paid` [D8].
-10. Extract form questions; classify each Section-G vs new.
-11. Generate answers from Block B + Block F + Section G + JD.
-12. Submit via one stable `run_actions` action array [H1] using labels [D6], `imeFriendly: true` [D4], `softTimeoutMs: 45000`, `output: "final"`, and `includeSteps: false`.
-13. On session error, run the 4-step recovery; only one retry [H2].
-14. On provider failure, stop and inspect telemetry before any retry [D9].
-15. On OTP prompt, fetch the code from Gmail via `gmail_get_message`.
-16. Submit the OTP with `geometra_fill_otp` and click Submit.
-17. Write outcome as `batch/tracker-additions/*.tsv` [H3].
-18. Cap parallelism at 2 per round [H5]; one in-flight per company.
+8. Route high-stakes applications through `@general-paid` [D8].
+9. Extract form questions; classify each Section-G vs new.
+10. Generate answers from Block B + Block F + Section G + JD.
+11. Submit via one stable `run_actions` action array [H1] using labels [D6], `imeFriendly: true` [D4], `softTimeoutMs: 45000`, `output: "final"`, and `includeSteps: false`.
+12. On session error, run the 4-step recovery; only one retry [H2].
+13. On provider failure, stop and inspect telemetry before any retry [D9].
+14. On OTP prompt, fetch the code from Gmail via `gmail_get_message`.
+15. Submit the OTP with `geometra_fill_otp` and click Submit.
+16. Write outcome as `batch/tracker-additions/*.tsv` [H3].
+17. Cap parallelism at 2 per round [H5]; one in-flight per company.
 
 ## Routing
 
@@ -110,8 +109,6 @@ Sections below are the detailed runbooks, decision tables, and portal-specific e
 
 ## Apply the session-length rule — REQUIRED
 
-## Apply the session-length rule — REQUIRED
-
 **If the candidate wants to apply to more than one job**, this mode MUST delegate each application to its own subagent with **max 2 in parallel** (Hard Limit #1 in `AGENTS.md`). For N jobs, run `ceil(N/2)` sequential rounds of 2. Never drive multi-job applications from a single interactive session: the accumulating Geometra tool results invalidate prompt caching and each message ends up re-processing 100K+ tokens of fresh history — see "Session Hygiene" in `.opencode/skills/job-forge.md`.
 
 **DO NOT dispatch 3+ `task` calls in one message.** Two is the absolute ceiling. This is non-negotiable, even when the user asks for "apply to 10 jobs" — that becomes 5 rounds of 2, not one message with 10 dispatches.
@@ -136,25 +133,28 @@ Before dispatching any batch of apply subagents, cross-check each candidate's lo
    ```yaml
    location_constraints:
      remote_us: true | false
-     remote_global: true | false
      hybrid_cities: [san-francisco, ...]
      blocked_cities: [new-york, ...]
-     authorized_countries: [US, ...]       # ISO-3166 alpha-2
+     authorized_countries: [US]            # ISO-3166 alpha-2; US-only automation
      requires_visa_sponsorship: true | false
    ```
 
+   Legacy profiles may still contain `remote_global`; ignore it. It cannot
+   override the hard `country_code: US` requirement or authorize any non-US
+   remote role.
+
 2. For each candidate, open its evaluation report (`reports/{num}-*.md`) and read the Location / Block A content. Extract: `mode ∈ {remote, hybrid, onsite}`, `city` (lowercase hyphenated), `country` (ISO-3166 alpha-2 when derivable).
 
 3. Apply the filter (decision table):
 
    | Role shape | Rule | Outcome |
    |---|---|---|
-   | Remote, country ∈ authorized_countries (typically US) | `remote_us == true` → COMPATIBLE | dispatch |
-   | Remote, country ∉ authorized_countries | `remote_global == true` AND (`requires_visa_sponsorship == false` OR JD mentions sponsorship) → COMPATIBLE | dispatch / else skip |
-   | Hybrid, `city ∈ hybrid_cities` | COMPATIBLE | dispatch |
+   | Remote, country = US and the JD explicitly permits US work | `remote_us == true` → COMPATIBLE | dispatch |
+   | Remote, country ≠ US | INCOMPATIBLE | mark `Discarded`, note `location mismatch: non-US country=X` |
+   | Hybrid or Onsite, country = US and `city ∈ hybrid_cities` | COMPATIBLE | dispatch |
    | Hybrid or Onsite, `city ∈ blocked_cities` | INCOMPATIBLE | mark `Discarded`, note `location mismatch: blocked_city=X` |
    | Hybrid or Onsite, `city` not in `hybrid_cities` and not in `blocked_cities` | INCOMPATIBLE by default (hybrid is opt-in per city) | mark `Discarded`, note `location mismatch: city=X not in hybrid_cities` |
-   | Location unclear / ambiguous | dispatch with a prompt flag instructing the apply subagent to verify the JD location first and Discard early if confirmed incompatible | dispatch-with-flag |
+   | Location unclear / ambiguous | INCOMPATIBLE under the US-only default | mark `Discarded`, note `location mismatch: US eligibility unconfirmed` |
 
 4. Country/visa: if `requires_visa_sponsorship == false` AND `country ∉ authorized_countries` AND the JD does NOT explicitly offer sponsorship → INCOMPATIBLE, do NOT dispatch.
 
@@ -165,10 +165,11 @@ When `location_constraints` is absent, use the prose fields:
 1. Read `config/profile.yml` for `location` (country, city), `compensation.location_flexibility`, and `visa_status`.
 2. For each candidate, open its evaluation report (`reports/{num}-*.md`) and read the Location / Block A content.
 3. Apply the filter:
-   - If the report says "Remote (US)" / "Remote" / "fully remote" — COMPATIBLE, dispatch.
+   - If the report explicitly says "Remote (US)", "Remote - United States", or equivalent US hiring scope — COMPATIBLE, dispatch.
+   - If the report only says "Remote", "Americas", or "North America" — INCOMPATIBLE because US eligibility is unconfirmed.
    - If the report says "Hybrid N days in {city}" AND {city} matches `location.city` OR `location_flexibility` says "open to hybrid in {city}" — COMPATIBLE, dispatch.
    - If the report says "Hybrid" or "Onsite" at a city NOT in the profile's location set AND `location_flexibility` says Remote-preferred — INCOMPATIBLE, do NOT dispatch. Mark the tracker entry `Discarded` directly with note `location mismatch: profile=X, role=Y`.
-   - If unclear or ambiguous — dispatch with a prompt flag telling the apply subagent to verify the JD location first and Discard early if confirmed incompatible.
+   - If unclear or ambiguous — INCOMPATIBLE. Mark `Discarded` with note `location mismatch: US eligibility unconfirmed`.
 4. Country/visa: if `visa_status: "No sponsorship needed"` and the role is outside the authorized country — INCOMPATIBLE, do NOT dispatch.
 
 **Why**: on 2026-04-18, 5 of 7 candidates dispatched for apply turned out location-incompatible. Each burned an apply-subagent round. The prose-field path reached the right call but cost interpretation cycles per dispatch; the structured path is O(1) field lookup and removes LLM-interpretation risk.
diff --git a/modes/auto-pipeline.md b/modes/auto-pipeline.md
index b3d1a3d..c300d8f 100644
--- a/modes/auto-pipeline.md
+++ b/modes/auto-pipeline.md
@@ -25,6 +25,28 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 
 **Cache after a successful fetch:** If the JD text is written to `jds/` or embedded in a report, store that exact text with `npx job-forge cache:put --url "{url}" --ttl 14d --input @path/to/jd.md`. Do not refetch just to populate the cache.
 
+### Location eligibility gate
+
+Extract the posting's actual location and remote hiring scope, then compare it
+with the structured `location` fields in `config/profile.yml`. Preserve any
+`location_status` received from `data/pipeline.md`. A status may move to
+`eligible` only when the JD explicitly supports work in the United States and
+matches ISO country code `US`, one of the five configured US location buckets,
+and the candidate's remote or relocation preference. `exploratory`,
+`location_review`, and `ineligible` roles
+may be evaluated and tracked, but must not trigger automatic outreach, form
+filling, or submission regardless of score. The word `Remote` alone is not
+proof of US eligibility.
+
+### Canonical tools (this mode)
+
+| Step | Tools |
+|------|--------|
+| JD from URL | Greenhouse API when applicable; otherwise `npx job-forge portal:snapshot`; then WebFetch; then WebSearch |
+| Live form (Step 4) | `npx job-forge portal:form-schema` by default; reuse an existing Geometra `sessionId` for a live multi-step session |
+
+See root `AGENTS.md` — **Geometra and fetch discipline** for lifecycle rules.
+
 ## Step 1 — Run Evaluation A-F
 Execute exactly as in the `offer` mode (read `modes/offer.md` for all blocks A-F).
 
@@ -71,7 +93,27 @@ Generate draft answers for the application form when the final score is >= 3.5.
 
 **Language**: Always in the language of the JD (EN default). Apply `/tech-translate`.
 
-## Step 5 — Update Tracker
-Update the current day file `data/applications/YYYY-MM-DD.md` with all columns including Report and PDF marked as ✅.
+## Step 5 — Apply When Score >= 3.0 And US-Eligible
+
+When the score gate `apply` passes (>= 3.0) and the independent location gate
+has posting-derived `country_code: US`, a configured US bucket, and
+`location_status: eligible`, continue directly into `apply` mode and submit the
+application. Do not pause for confirmation between evaluation, PDF, form fill,
+and submission. For a 3.0-3.4 score, generate any required form answers during
+the apply flow even though Step 4 did not save draft answers in advance.
+
+Before opening the form, write sourced candidate facts to
+`batch/preflight-candidates.json` and run `npx job-forge preflight:check
+--candidates batch/preflight-candidates.json`. A score below 3.0 is `SKIP`.
+Any non-US, ambiguous, or profile-incompatible location is `Discarded` and MUST
+NOT open or submit a form. If pasted JD text has no real application URL, record
+the application step as pending with that concrete blocker; never invent a URL.
+
+## Step 6 — Update Tracker
+
+Update the current day file `data/applications/YYYY-MM-DD.md` with the report,
+PDF, location facts, and the actual canonical outcome: `Applied` only after a
+confirmed submission, `SKIP` below 3.0, `Discarded` for a failed location gate,
+or `Evaluated` when submission is blocked or fails.
 
 **If any step fails**, continue with the remaining steps and mark the failed step as pending in the tracker.
diff --git a/modes/contact.md b/modes/contact.md
index e96dccb..cf750b1 100644
--- a/modes/contact.md
+++ b/modes/contact.md
@@ -17,11 +17,23 @@ Check for an existing evaluation report before generating any message.
    - **STAR stories** from Block F that are most relevant.
 <!-- isolint-disable-next-line undefined-step-reference -->
    - **Case study** recommended in Block F.
+   - **Location status**, posting location, ISO country code, US location bucket, and remote hiring scope.
 4. Also read all day files in `data/applications/` to check current status of this application.
 5. If NO report exists, inform the user and offer to run an evaluation first — or proceed with cv.md only.
 
 The loaded evaluation context is what makes the outreach message specific instead of generic.
 
+**Hard gate:** automatic outreach is allowed only for `location_status: eligible`
+with explicit evidence that the posting hires in the United States (`country_code: US`).
+For `exploratory`, `location_review`, or `ineligible`, do not search for people
+or generate an unsolicited message automatically. At the candidate's explicit
+request, you may instead draft a question to the recruiter that asks whether
+the employer can hire in the candidate's location.
+
+For batch outreach, apply the scanner's `max_results_per_company` and US
+location-balancing rules, contact at most one primary person per role initially,
+and report the number of distinct companies and US location buckets represented.
+
 ## Step 1 — Identify Targets
 
 Use WebSearch to find:
diff --git a/modes/offer.md b/modes/offer.md
index 3cf7813..bcf816a 100644
--- a/modes/offer.md
+++ b/modes/offer.md
@@ -138,7 +138,11 @@ Save the full evaluation to `reports/{###}-{company-slug}-{YYYY-MM-DD}.md`.
 **Date:** {YYYY-MM-DD}
 **Archetype:** {detected}
 **Score:** {X.X/5}
-**URL:** {original offer URL}
+**URL:** {job posting URL or "pasted JD"}
+**Location:** {posting location and remote scope}
+**Country code:** {US | non-US/unknown}
+**Region:** {one of the five US diversity_policy location bucket ids or non-US/unknown}
+**Location status:** {eligible | exploratory | location_review | ineligible}
 **PDF:** {path or pending}
 
 ---
@@ -191,6 +195,7 @@ Save the full evaluation to `reports/{###}-{company-slug}-{YYYY-MM-DD}.md`.
 - Status: `Evaluated`
 - PDF: ❌ (or ✅ if auto-pipeline generated PDF)
 - Report: relative link to the report .md (e.g., `[001](reports/001-company-2026-01-01.md)`)
+- Notes: include `{location}; {country_code}; {region}; {location_status}` so eligibility survives tracker-only workflows
 
 **Tracker format:**
 
diff --git a/modes/pipeline.md b/modes/pipeline.md
index 86b9cdd..1825682 100644
--- a/modes/pipeline.md
+++ b/modes/pipeline.md
@@ -6,11 +6,13 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 
 1. **Read** `data/pipeline.md` → find `- [ ]` items in the "Pending" section
 2. **For each pending URL**:
-   a. Calculate the next sequential `REPORT_NUM` by running `npx job-forge next-num` (scans `reports/`, day file `#` columns, and `batch/tracker-additions/` — do NOT derive from `reports/` alone)
-   b. **Extract JD** using Greenhouse API → `npx job-forge portal:snapshot --url "$URL" --json` → Geometra MCP only if an interactive session is needed → WebFetch → WebSearch
-   c. If the URL is not accessible → mark as `- [!]` with a note and continue
-   d. **Run full auto-pipeline**: A-F Evaluation → Report .md → PDF (if score >= 3.0, per `_shared.md` thresholds) → Draft answers (if score >= 3.5) → Tracker
-   e. **Move from "Pending" to "Processed"**: `- [x] #NNN | URL | Company | Role | Score/5 | PDF ✅/❌`
+   a. Parse optional scanner metadata after the title: `location | country_code | region | location_status | ats={type}`.
+   b. Preserve the location gate through evaluation. Only explicit `country_code: US` plus `location_status: eligible` may trigger automatic outreach, form filling, or submission; re-check the full JD before promoting any other status. Generic `Remote`, `Americas`, or `North America` is not sufficient.
+   c. Calculate the next sequential `REPORT_NUM` by running `npx job-forge next-num` (scans `reports/`, day file `#` columns, and `batch/tracker-additions/` — do NOT derive from `reports/` alone).
+   d. **Extract JD** using Greenhouse API → `npx job-forge portal:snapshot --url "$URL" --json` → Geometra MCP only if an interactive session is needed → WebFetch → WebSearch.
+   e. If the URL is not accessible → mark as `- [!]` with a note and continue.
+   f. **Run full auto-pipeline**: A-F Evaluation → Report .md → PDF (if score >= 3.0, per `_shared.md` thresholds) → Draft answers (if score >= 3.5) → Apply and submit (score >= 3.0 plus the independent US location gate) → Tracker. Location-ineligible roles may be evaluated and tracked but may not progress to automatic outreach or application actions.
+   g. **Move from "Pending" to "Processed"**: `- [x] #NNN | URL | Company | Role | Score/5 | PDF ✅/❌`.
 3. **Parallel dispatch — max 2 at a time** (Hard Limit #1 in `AGENTS.md`). For N pending URLs, run `ceil(N/2)` rounds of 2 `task` dispatches. Never 3+ in one message.
 4. **When finished**, display a summary table:
 
@@ -24,6 +26,7 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 ## Pending
 - [ ] https://jobs.example.com/posting/123
 - [ ] https://boards.greenhouse.io/company/jobs/456 | Company Inc | Senior PM
+- [ ] https://jobs.example.com/789 | Distributed Co | Data Engineer | Remote - United States | US | us_nationwide | eligible
 - [!] https://private.url/job — Error: login required
 
 ## Processed
diff --git a/modes/reference-setup.md b/modes/reference-setup.md
index 0e1f585..8a97160 100644
--- a/modes/reference-setup.md
+++ b/modes/reference-setup.md
@@ -44,6 +44,7 @@ If `config/profile.yml` is missing, copy from `config/profile.example.yml` and t
 > "I need a few details to personalize the system:
 > - Your full name and email
 > - Your location and timezone
+> - Your US work authorization, preferred US locations, and remote or relocation preferences
 > - What roles are you targeting? (e.g., 'Senior Backend Engineer', 'AI Product Manager')
 > - Your salary target range
 >
@@ -53,9 +54,9 @@ Fill in `config/profile.yml` with their answers. For archetypes, map their targe
 
 #### Step 3: Portals (recommended)
 If `portals.yml` is missing:
-> "I'll set up the job scanner with 45+ pre-configured companies. Want me to customize the search keywords for your target roles?"
+> "I'll set up the US-only job scanner with 270+ US-tagged sources and balanced coverage across US locations. Want me to customize the search keywords for your target roles?"
 
-Copy `templates/portals.example.yml` → `portals.yml`. If they gave target roles in Step 2, update `title_filter.positive` to match.
+Copy `templates/portals.example.yml` → `portals.yml`. If they gave target roles in Step 2, update `title_filter.positive` to match. Keep the five US coverage queries enabled; explicit US location eligibility remains a hard filter and diversity targets must never force a non-US or ambiguous application.
 
 #### Step 4: Tracker
 If `data/applications/` directory doesn't exist, create it:
@@ -162,6 +163,7 @@ Write one TSV file per evaluation to `batch/tracker-additions/{num}-{company-slu
 6. Health check: `npx job-forge verify`
 7. Normalize statuses: `npx job-forge normalize`
 8. Dedup: `npx job-forge dedup`
+9. Only postings explicitly confirmed to hire in the United States may trigger automatic outreach, form filling, or submission. Generic `Remote`, `Americas`, and `North America` are not sufficient.
 
 ### Canonical States (applications day files)
 
diff --git a/modes/scan.md b/modes/scan.md
index af02f1c..b1bbb55 100644
--- a/modes/scan.md
+++ b/modes/scan.md
@@ -20,12 +20,26 @@ Read `portals.yml` which contains:
 - `search_queries`: List of WebSearch queries with `site:` filters per portal (broad discovery)
 - `tracked_companies`: Specific companies with `careers_url` for direct navigation
 - `title_filter`: Positive/negative/seniority_boost keywords for title filtering
+- `diversity_policy`: US-only location and company-mix coverage targets
+
+Also read `config/profile.yml` location eligibility. The distributable defaults
+target the United States only. The posting's location, remote restrictions,
+work authorization, and relocation requirements are hard constraints. Diversity
+targets only balance US-eligible offers.
+
+## Diversity and eligibility invariants
+
+1. **Use job location, not headquarters.** A US company can offer a role in India; a non-US company can advertise a US role. Extract the location and remote scope from every posting.
+2. **US evidence is mandatory.** Keep a posting only when it explicitly allows work in the United States. Generic `Remote`, `Americas`, `North America`, or an unspecified location is not enough and is excluded under `unknown_location: exclude`.
+3. **Best-effort US breadth.** After role and eligibility filtering, balance the shortlist across US Northeast, Midwest, South, West, nationwide/remote postings, companies, and work arrangements.
+4. **No fabricated coverage.** If a US location bucket has no suitable results, report a coverage gap and the reason; never substitute a non-US or ambiguous posting.
+5. **Company cap.** Respect `max_results_per_company` before filling remaining slots so one large employer cannot dominate the scan.
 
 ## Apply This Discovery Strategy (3 levels)
 
 ### Use Level 1 — Direct Geometra (PRIMARY)
 
-**For each company in `tracked_companies`:** Connect to its `careers_url` with Geometra MCP (`geometra_connect({ ..., headless: true, browserMode: "stock", blockDetection: true, blockedSitePolicy: "manual-handoff" })` + `geometra_page_model` / `geometra_list_items`), read ALL visible job listings, and extract the title + URL of each one. Direct Geometra is the most reliable method because:
+For scheduled companies whose `scan_method` is `geometra` (or omitted), connect to `careers_url` with Geometra MCP (`geometra_connect({ ..., headless: true, browserMode: "stock", blockDetection: true, blockedSitePolicy: "manual-handoff" })` + `geometra_page_model` / `geometra_list_items`), read all visible job listings, and extract the posting metadata. Companies configured with `scan_method: websearch` run their `scan_query` at Level 3; configured APIs run at Level 2. Direct Geometra is reliable because:
 
 - It sees the page in real time (not cached Google results).
 - It works with SPAs (Ashby, Lever, Workday).
@@ -95,14 +109,15 @@ Supported API shapes:
 
 #### WeWorkRemotely (RSS, cross-company aggregator)
 
-- **Endpoints** (one per category — enable the ones matching your target roles):
+- **Endpoints** (one public category feed per target area; the RSS URL itself has no server-side country parameter):
   - `https://weworkremotely.com/categories/remote-programming-jobs.rss`
   - `https://weworkremotely.com/categories/remote-devops-sysadmin-jobs.rss`
   - `https://weworkremotely.com/categories/remote-product-jobs.rss`
   - `https://weworkremotely.com/categories/remote-design-jobs.rss`
   - `https://weworkremotely.com/categories/all-other-remote-jobs.rss`
 - **Method**: `GET` — returns RSS 2.0 XML.
-- **Shape**: `<rss><channel><item><title>{company}: {role}</title><link>https://weworkremotely.com/remote-jobs/{slug}</link><pubDate>...</pubDate><region>...</region></item></channel></rss>`
+- **Shape/example**: `<item><title>Acme: Senior Platform Engineer</title><link>https://weworkremotely.com/remote-jobs/acme-senior-platform-engineer</link><pubDate>...</pubDate><region>USA Only</region></item>`.
+- **Required US prefilter**: after fetching the configured RSS URL, retain an item only when `<region>` exactly matches a configured `location_filter.allowed_values` value. The US-only template permits only `USA Only`. Exclude missing regions and `Anywhere in the World`, `North America Only`, `Americas Only`, or any other value before title filtering. The full posting must still explicitly confirm US hiring scope.
 - **Company/role extraction**: split `<title>` on the first `: ` — left side is company, right side is role. Fallback to the whole title as role if there is no `: `.
 - **Canonical URL to record**: the `<link>` verbatim (format `https://weworkremotely.com/remote-jobs/{slug}`).
 - **Cross-company note**: WeWorkRemotely is NOT per-company — it aggregates postings from hundreds of companies. Scan it via the `cross_company_feeds` section in `portals.yml`, not `tracked_companies`.
@@ -115,6 +130,7 @@ Supported API shapes:
 - **Required headers**: `User-Agent: Mozilla/5.0 ...` — RemoteOK returns 403 without a browser-like UA.
 - **Shape** (per posting after skip): `{ id, slug, company, company_logo, position, description, tags: [string], date, epoch, url, apply_url, location, salary_min, salary_max }`
 - **Canonical URL to record**: `url` (format `https://remoteok.com/remote-jobs/{id}-{slug}`).
+- **Required US prefilter**: normalize the optional `location` field to ISO country code `US` using the feed's `location_filter`. Missing, generic, worldwide, continental, or otherwise ambiguous values are excluded before tag/title filtering. Do not infer US eligibility from tags, salary currency, company headquarters, or the description's word `remote`; verify the full posting after the prefilter.
 - **Filtering**: RemoteOK feeds are broad — use `tags` for pre-filter (e.g. `tags` contains `"engineer"` or `"ai"`) before passing through `title_filter`.
 - **Cross-company note**: same as WeWorkRemotely — configure via `cross_company_feeds`, not `tracked_companies`.
 - **ats**: `remoteok` (aggregator).
@@ -124,33 +140,43 @@ Supported API shapes:
 The `search_queries` with `site:` filters cover portals broadly (all Ashby boards, all Greenhouse boards, all Lever boards, all Workday boards). Useful for discovering NEW companies not yet in `tracked_companies`, but results may be outdated.
 
 **Execution priority:**
-1. Level 1: Geometra → all `tracked_companies` with `careers_url`
-2. Level 2: API → all `tracked_companies` with `api:` (Greenhouse / Ashby / Lever / Workday / SmartRecruiters) AND all `cross_company_feeds` with `enabled: true` (WeWorkRemotely / RemoteOK)
-3. Level 3: WebSearch → all `search_queries` with `enabled: true`
+1. Level 1: Geometra → rotating US-tagged direct-company pool, up to `tracked_company_scan_budget`
+2. Level 2: API → scheduled US-tagged `tracked_companies` with any supported API, plus enabled cross-company feeds
+3. Level 3: WebSearch → enabled queries and scheduled US-tagged company queries, with `search_location_constraint` appended
 
 The levels are additive — all are executed, results are merged and deduplicated.
 
 ## Run This Workflow
 
-1. **Read configuration**: `portals.yml`
+1. **Fail-closed configuration check, then read configuration**:
+   - Run `npx job-forge verify:diversity portals.yml --profile config/profile.yml`.
+   - If it fails, stop before Geometra, WebFetch, WebSearch, or any other
+     network request. Follow its targeted upgrade instructions; never replace
+     either personal YAML file wholesale or continue with legacy defaults.
+   - After it passes, read `portals.yml` and `config/profile.yml`.
 2. **Read history**: `data/scan-history.tsv` → previously seen URLs
 3. **Read dedup sources**: all day files in `data/applications/` + `data/pipeline.md`
 
-4. **Level 1 — Geometra scan** (sequential, or ≤2 parallel via `task` subagents per Hard Limit #1 in `AGENTS.md`):
-   For each company in `tracked_companies` with `enabled: true` and `careers_url` defined:
+4. **Build the tracked-company schedule, then run Level 1 — Geometra scan** (sequential, or ≤2 parallel via `task` subagents per Hard Limit #1 in `AGENTS.md`):
+   - Include only enabled direct companies carrying one of `diversity_policy.source_company_tags` (the default is `us`). This tag schedules likely US sources but never proves that a particular posting is US-eligible.
+   - Sort the pool deterministically, rotate its starting offset by UTC day-of-year, and take up to `tracked_company_scan_budget`. This gives different companies exposure across runs instead of repeatedly scanning the first entries in the file.
+   - Do not scan non-US-tagged or unclassified sources in the default US-only configuration. A company may be added to the pool only after its catalog scope is verified and tagged.
+   - Reuse this scheduled pool for Levels 1-3. Scan companies whose `scan_method` is `geometra` or omitted here; route `websearch` entries to Level 3 and entries with an API configuration to Level 2 as applicable.
+
+   For each scheduled company:
    a. `geometra_connect` to the `careers_url` with `headless: true`, `browserMode: "stock"`, `blockDetection: true`, and `blockedSitePolicy: "manual-handoff"`
    b. `geometra_page_model` or `geometra_list_items` to read all job listings
    c. If the page has filters/departments, navigate the relevant sections
-   d. For each job listing extract: `{title, url, company}`
+   d. For each job listing extract: `{title, url, company, location, remote_scope, employment_type}`
    e. If the page paginates results, navigate additional pages
    f. Accumulate in candidates list
    g. If `careers_url` fails (404, redirect), try `scan_query` as fallback and note for URL update
 
 5. **Level 2 — ATS / Aggregator APIs** (WebFetch can batch freely — it's cheap and doesn't use Geometra sessions):
 
-   **5a. Per-company APIs** — for each company in `tracked_companies` with `api:` defined and `enabled: true`:
+   **5a. Per-company APIs** — for each company in the scheduled US-tagged pool with `api:` or a supported ATS API configuration defined:
    a. WebFetch (or `fetch` for Workday, which needs POST) the API URL per the endpoint shape documented above.
-   b. Extract per-posting `{title, url, company, updated_at, ats}` plus ATS-specific IDs:
+   b. Extract per-posting `{title, url, company, location, remote_scope, employment_type, updated_at, ats}` plus ATS-specific IDs:
       - **Greenhouse** → also record `gh_slug`, `gh_id`. URL MUST be canonical `https://job-boards.greenhouse.io/{gh_slug}/jobs/{gh_id}` — do **NOT** use `absolute_url` when it points to a customer-skinned front-end (e.g. `pinterestcareers.com/jobs/?gh_jid=N`, `okta.com/company/careers/opportunity/N`, `samsara.com/company/careers/roles/N`, `zoominfo.com/careers?gh_jid=N`, `collibra.com/.../?gh_jid=N`, `careers.toasttab.com/jobs?gh_jid=N`, `careers.airbnb.com/positions/N`, `coinbase.com/careers/positions/N`, `instacart.careers/job/?gh_jid=N`). These customer front-ends return shells or 403 to bots and cause downstream WebFetch-based verification to wrongly mark the role CLOSED.
       - **Ashby** → record the returned `jobUrl`.
       - **Lever** → record the returned `hostedUrl`.
@@ -161,27 +187,37 @@ The levels are additive — all are executed, results are merged and deduplicate
 
    **5b. Cross-company aggregator feeds** — for each feed in `cross_company_feeds` with `enabled: true`:
    a. WebFetch the RSS (WeWorkRemotely) or JSON (RemoteOK) endpoint per the shape documented above.
-   b. Parse each entry to `{title, url, company, ats, updated_at}`:
-      - **WeWorkRemotely** → split `<title>` on the first `: ` to separate company from role; `<link>` → url; `<pubDate>` → updated_at.
-      - **RemoteOK** → skip the first element (legal disclaimer); from each remaining entry take `company`, `position`, `url`, `date`.
-   c. Apply the feed's `tag_filter` / `category_filter` before the global `title_filter` — aggregators have much higher volume than per-company APIs.
-   d. Accumulate in candidates list (dedup with Level 1 + 5a).
+   b. Apply `location_filter` first. An enabled global feed without a location field/filter is invalid in the US-only configuration. `require_explicit_match: true`, `on_missing: exclude`, and `on_ambiguous: exclude` are fail-closed; log rejected rows as `skipped_location`.
+   c. Parse each surviving entry to `{title, url, company, location, remote_scope, employment_type, ats, updated_at}`:
+      - **WeWorkRemotely** → require `<region>USA Only</region>`; split `<title>` on the first `: ` to separate company from role; `<link>` → url; `<pubDate>` → updated_at. Do not use the company's headquarters from `<description>` as job-location evidence.
+      - **RemoteOK** → skip the first element (legal disclaimer); require its `location` field to normalize explicitly to ISO `US`; then take `company`, `position`, `url`, and `date`. Missing or ambiguous `location` means exclusion, even if the description later mentions a US city.
+   d. Apply the feed's `tag_filter` / `category_filter` before the global `title_filter` — aggregators have much higher volume than per-company APIs.
+   e. Read and verify the full posting before assigning `location_status: eligible`, then accumulate it in the candidates list (dedup with Level 1 + 5a).
 
 6. **Level 3 — WebSearch queries** (WebSearch is parallel-safe; batch freely):
-   For each query in `search_queries` with `enabled: true`:
-   a. Execute WebSearch with the defined `query`
-   b. From each result extract: `{title, url, company}`
+   For each query in `search_queries` with `enabled: true`, plus each US-tagged
+   scheduled company routed here by `scan_method: websearch`:
+   a. Wrap the defined `query` or `scan_query` in parentheses, append `diversity_policy.search_location_constraint`, and execute WebSearch. The US clause is mandatory even when the stored query says `remote`; the full posting must still pass the location eligibility classification below.
+   b. From each result extract: `{title, url, company, location, remote_scope, employment_type}` when present
       - **title**: from the result title (before " @ " or " | ")
       - **url**: result URL
       - **company**: after " @ " in the title, or extract from domain/path
    c. Accumulate in candidates list (dedup with Level 1+2)
 
-6. **Filter by title** using `title_filter` from `portals.yml`:
+7. **Filter by title** using `title_filter` from `portals.yml`:
    - At least 1 keyword from `positive` must appear in the title (case-insensitive)
    - 0 keywords from `negative` must appear
    - `seniority_boost` keywords give priority but are not required
 
-7. **Deduplicate** against 3 sources (URL-exact + fuzzy company+role):
+8. **Classify location and eligibility**:
+   - Read the full posting when the listing card or search result does not contain enough location evidence.
+   - Confirm explicit US scope: a US city/state, `United States`/`USA`, or a remote statement that clearly hires in the US. A US salary band or company headquarters alone is not sufficient.
+   - Normalize the posting into exactly one `diversity_policy.regions[].id` using `job_location_terms`. Prefer a specific city/state bucket over `us_nationwide` when both match.
+   - Compare ISO country code `US` and the normalized US bucket against `location.eligible_work_country_codes`, `preferred_region_ids`, `remote.allowed_region_ids`, `remote.require_explicit_location_eligibility`, and `willing_to_relocate` in `config/profile.yml`.
+   - Set `location_status: eligible` only after both US scope and the user's work/remote constraints pass. Classify explicit non-US postings as `ineligible`; treat missing or ambiguous scope as excluded because the template sets `unknown_location: exclude`.
+   - Never write non-US, `exploratory`, `location_review`, or ambiguous postings to the pipeline in the US-only default.
+
+9. **Deduplicate** against 3 sources (URL-exact + fuzzy company+role):
 
    **Layer 1 — URL-exact:**
    - `scan-history.tsv` → exact URL already seen
@@ -197,20 +233,23 @@ The levels are additive — all are executed, results are merged and deduplicate
    - Fuzzy role match: split both titles into words > 3 chars, match if 2+ words overlap (substring match, case-insensitive). E.g., "Senior AI Engineer" and "Staff AI Engineer" share "engineer" — only 1 overlap, not a match. But "AI Platform Engineer" and "AI Platform Eng" share "platform" + partial "engineer" — match.
    - When a fuzzy match is found but the URL is new, log it as `skipped_repost` (not `skipped_dup`) with a note referencing the original entry number.
 
-8. **For each new offer that passes filters**:
-   a. Add to `pipeline.md` section "Pending": `- [ ] {url} | {company} | {title} | ats={ats}` — the `| ats={type}` suffix is REQUIRED for every entry (values: `greenhouse`, `ashby`, `workable`, `lever`, `workday`, `smartrecruiters`, `wwr`, `remoteok`, `builtin`, `custom`, `unknown`). When the offer came from the Greenhouse API (Level 2), ALSO append `| gh={gh_slug}/{gh_id}` so downstream verification can hit the JSON endpoint. Example entries:
-      - `- [ ] https://job-boards.greenhouse.io/webflow/jobs/7689676 | Webflow | Lead AI Engineer | ats=greenhouse | gh=webflow/7689676`
-      - `- [ ] https://jobs.ashbyhq.com/everai/abc-123 | EverAI | Senior AI PM | ats=ashby`
-      - `- [ ] https://jobs.lever.co/temporal/xyz | Temporal | Product Manager - AI | ats=lever`
-      - `- [ ] https://nvidia.wd5.myworkdayjobs.com/NVIDIAExternalCareerSite/job/US-CA-Santa-Clara/Senior-AI-Engineer_JR123456 | NVIDIA | Senior AI Engineer | ats=workday`
-      - `- [ ] https://jobs.smartrecruiters.com/Visa1/744000012345678 | Visa | Staff ML Engineer | ats=smartrecruiters`
-      - `- [ ] https://weworkremotely.com/remote-jobs/acme-senior-platform-engineer | Acme | Senior Platform Engineer | ats=wwr`
-      - `- [ ] https://remoteok.com/remote-jobs/12345-senior-ai-engineer-acme | Acme | Senior AI Engineer | ats=remoteok`
-   b. Record in `scan-history.tsv`: `{url}\t{date}\t{query_name}\t{title}\t{company}\tadded`
-
-9. **Offers filtered by title**: record in `scan-history.tsv` with status `skipped_title`
-10. **Duplicate offers (URL-exact)**: record with status `skipped_dup`
-11. **Duplicate offers (fuzzy repost)**: record with status `skipped_repost` and note `repost of #{original_entry_num}`
+10. **Balance the eligible, deduplicated shortlist** using `diversity_policy`:
+   - Write the normalized candidate array to `/tmp/jobforge-scan-candidates-{YYYY-MM-DD}.json`, including posting-derived `country_code`, `relevance_score`, `region`, and `location_status`.
+   - Run `npx job-forge balance:scan /tmp/jobforge-scan-candidates-{YYYY-MM-DD}.json portals.yml` and use its JSON result as the canonical shortlist. This command resolves the balancer shipped inside the harness for both package consumers and harness checkouts.
+   - `selected` is bounded by `shortlist_size`, fills US location floors, reaches `minimum_distinct_companies` before adding extra roles from represented employers, enforces `max_results_per_company`, and treats `max_region_share` as a best-effort ceiling.
+   - With `unknown_location: exclude`, `review` MUST be empty. `excluded` contains non-US, ambiguous, or malformed rows.
+   - Use `summary.coverage` and `summary.gaps` verbatim in the scan summary. If the helper fails, stop before writing to the pipeline rather than silently using an unbalanced list.
+
+11. **Write balanced results**:
+   - For each `selected` offer, add to `pipeline.md` section "Pending": `- [ ] {url} | {company} | {title} | {location} | US | {region} | eligible | ats={ats}`. The `ats` value is required and must be one of `greenhouse`, `ashby`, `workable`, `lever`, `workday`, `smartrecruiters`, `wwr`, `remoteok`, `builtin`, `custom`, or `unknown`.
+   - For a Greenhouse API result, also append `| gh={gh_slug}/{gh_id}` using values copied verbatim from the API. Example: `- [ ] https://job-boards.greenhouse.io/webflow/jobs/7689676 | Webflow | Lead AI Engineer | New York, NY | US | us_northeast | eligible | ats=greenhouse | gh=webflow/7689676`.
+   - Do not add `review` or `excluded` offers to `pipeline.md`.
+   - Record selected offers in `scan-history.tsv` with status `added`; record non-US and ambiguous offers with status `skipped_location` and a concrete reason.
+
+12. **Offers filtered by title**: record in `scan-history.tsv` with status `skipped_title`
+13. **Location-ineligible offers**: record with status `skipped_location`
+14. **Duplicate offers (URL-exact)**: record with status `skipped_dup`
+15. **Duplicate offers (fuzzy repost)**: record with status `skipped_repost` and note `repost of #{original_entry_num}`
 
 ## Extract Title And Company From WebSearch Results
 
@@ -227,17 +266,20 @@ Generic regex: `(.+?)(?:\s*[@|—–-]\s*|\s+at\s+)(.+?)$`
 
 If a publicly inaccessible URL is found:
 1. Save the JD to `jds/{company}-{role-slug}.md`
-2. Add to pipeline.md as: `- [ ] local:jds/{company}-{role-slug}.md | {company} | {title}`
+2. Classify the frozen JD through the same US eligibility gate; do not enqueue it unless it is explicitly eligible.
+3. Add an eligible local artifact to pipeline.md as: `- [ ] local:jds/{company}-{role-slug}.md | {company} | {title} | {location} | US | {region} | eligible | ats={ats}`
 
 ## Scan History
 
-`data/scan-history.tsv` tracks ALL seen URLs:
+`data/scan-history.tsv` tracks ALL seen URLs. The final five columns are new;
+readers must continue accepting the original six-column rows for backward
+compatibility:
 
 ```
-url	first_seen	portal	title	company	status
-https://...	2026-02-10	Ashby — AI PM	PM AI	Acme	added
-https://...	2026-02-10	Greenhouse — SA	Junior Dev	BigCo	skipped_title
-https://...	2026-02-10	Ashby — AI PM	SA AI	OldCo	skipped_dup
+url	first_seen	portal	title	company	status	location	country_code	region	location_status	note
+https://...	2026-02-10	Ashby — AI PM	PM AI	Acme	added	New York, NY	US	us_northeast	eligible	-
+https://...	2026-02-10	Greenhouse — SA	Junior Dev	BigCo	skipped_title	Austin, TX	US	us_south	eligible	-
+https://...	2026-02-10	Ashby — AI PM	SA AI	OldCo	skipped_location	Remote (EU only)	DE	europe	ineligible	not available in the US
 ```
 
 ## Structured Output — Required for Downstream Dispatch
@@ -246,18 +288,19 @@ Scan mode MUST write its ranked candidate list to a file, not just return it in
 
 **File location**: `batch/scan-output-{YYYY-MM-DD}.md`
 
-**Format**: one markdown table per scan run, ordered by archetype-fit rank:
+**Format**: one markdown table per scan run, ordered by archetype-fit rank. The file contains only the balanced, US-eligible `selected` list:
 
-| rank | company | ats | role | gh_slug | gh_id | url | updated_at |
-|------|---------|-----|------|---------|-------|-----|------------|
-| 1    | Webflow | greenhouse | Lead AI Engineer | webflow | 7689676 | https://job-boards.greenhouse.io/webflow/jobs/7689676 | 2026-04-14 |
-| 2    | EverAI  | ashby      | Senior AI PM     | -       | -       | https://jobs.ashbyhq.com/everai/abc-123 | 2026-04-15 |
-| ... | ... | ... | ... | ... | ... | ... | ... |
+| rank | company | ats | role | location | country_code | region | location_status | gh_slug | gh_id | url | updated_at |
+|------|---------|-----|------|----------|--------------|--------|-----------------|---------|-------|-----|------------|
+| 1 | Webflow | greenhouse | Lead AI Engineer | New York, NY | US | us_northeast | eligible | webflow | 7689676 | https://job-boards.greenhouse.io/webflow/jobs/7689676 | 2026-04-14 |
+| 2 | EverAI | ashby | Senior AI PM | Remote - United States | US | us_nationwide | eligible | - | - | https://jobs.ashbyhq.com/everai/abc-123 | 2026-04-15 |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
 
 **`ats` values** (one of): `greenhouse`, `ashby`, `workable`, `lever`, `workday`, `smartrecruiters`, `wwr`, `remoteok`, `builtin`, `custom`, `unknown`. Every row MUST populate this column — it's what the apply subagent uses to pick the correct Gmail OTP sender query. The `wwr` and `remoteok` values identify aggregator postings whose real underlying ATS is only known after the redirect is followed — downstream evaluators re-detect and may rewrite to the underlying ATS.
 
 Every row MUST have:
 - `ats` — the ATS platform hosting the posting. Inferred from the canonical URL host (e.g. `boards-api.greenhouse.io` / `job-boards.greenhouse.io` → `greenhouse`; `jobs.ashbyhq.com` → `ashby`; `jobs.lever.co` → `lever`; `*.myworkdayjobs.com` (any `wd1`/`wd3`/`wd5` pod) → `workday`; `apply.workable.com` / `jobs.workable.com` → `workable`; `api.smartrecruiters.com` / `jobs.smartrecruiters.com` → `smartrecruiters`; `weworkremotely.com` → `wwr`; `remoteok.com` → `remoteok`; `builtin.com/jobs/` → `builtin`; company-own domains → `custom`; anything indeterminate → `unknown`).
+- `location`, `country_code`, `region`, and `location_status` — copied from posting-derived classification. Every selected row must have `country_code: US`, one of the five configured US region ids, and `location_status: eligible`.
 - `url` in canonical form. For Greenhouse use `https://job-boards.greenhouse.io/{gh_slug}/jobs/{gh_id}` (matching the suffix in `data/pipeline.md`). For other ATSes use the platform's native URL (do not rewrite).
 - `updated_at` in `YYYY-MM-DD` form (the most recent `updated_at` in the API response, or scan date when the source has no such field).
 
@@ -278,9 +321,15 @@ Portal Scan — {YYYY-MM-DD}
 Queries executed: N
 Offers found: N total
 Filtered by title: N relevant
+US eligible: N | Non-US/ambiguous excluded: N
 Duplicates: N (already evaluated or in pipeline)
 New added to pipeline.md: N
 
+US location coverage (eligible shortlist):
+  Northeast N | Midwest N | South N | West N | Nationwide/US-remote N
+Distinct companies: N | Remote N | Hybrid N | On-site N
+Coverage gaps: {region or mix target + reason, or "none"}
+
 NEXT STEP RECOMMENDATION:
 - Structured candidate list written to: batch/scan-output-{YYYY-MM-DD}.md
 - Downstream subagents MUST read URLs from that file, not from this return message
@@ -331,5 +380,7 @@ Each company in `tracked_companies` MUST have a `careers_url` — the direct URL
 - Add new queries as interesting portals or roles are discovered
 - Disable queries with `enabled: false` if they generate too much noise
 - Adjust filtering keywords as target roles evolve
+- Keep at least `minimum_enabled_queries` enabled for every US location bucket
+- Review US location coverage in every scan summary; do not silently replace an empty bucket with a non-US or ambiguous offer
 - Add companies to `tracked_companies` when you want to follow them closely
 - Verify `careers_url` periodically — companies change ATS platforms
diff --git a/package.json b/package.json
index 187297c..d7215d5 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,11 @@
     "create-job-forge": "bin/create-job-forge.mjs"
   },
   "scripts": {
-    "verify": "node verify-pipeline.mjs",
+    "verify": "node verify-pipeline.mjs && node scripts/verify-portal-diversity.mjs",
+    "verify:pipeline": "node verify-pipeline.mjs",
+    "verify:diversity": "node scripts/verify-portal-diversity.mjs",
+    "balance:scan": "node scripts/balance-scan-results.mjs",
+    "test": "node --test",
     "build:dashboard": "cd dashboard && go build .",
     "normalize": "node normalize-statuses.mjs",
     "dedup": "node dedup-tracker.mjs",
diff --git a/scripts/add-tags.mjs b/scripts/add-tags.mjs
index 73730f0..86a7395 100644
--- a/scripts/add-tags.mjs
+++ b/scripts/add-tags.mjs
@@ -298,7 +298,7 @@ function assignTags(section, name, notes) {
   if (n === "character ai") { tags.add("ai-lab"); tags.add("conversational-ai"); tags.add("us"); }
   if (n === "reka ai") { tags.add("ai-lab"); tags.add("us"); }
   if (n === "aleph alpha") { tags.add("ai-lab"); tags.add("eu"); }
-  if (n === "cohere") { tags.add("ai-lab"); tags.add("remote-first"); }
+  if (n === "cohere") { tags.add("ai-lab"); tags.add("canada"); tags.add("remote-first"); }
   if (n === "cerebras") { tags.add("ai-infra"); tags.add("chips"); tags.add("us"); }
   if (n === "sambanova") { tags.add("ai-infra"); tags.add("chips"); tags.add("us"); }
   if (n === "modular") { tags.add("ai-infra"); tags.add("developer-tools"); tags.add("us"); }
@@ -579,7 +579,7 @@ function assignTags(section, name, notes) {
   if (n === "dust") { tags.add("ai-agents"); tags.add("eu"); }
   if (n === "moveworks") { tags.add("ai-agents"); tags.add("enterprise-saas"); tags.add("us"); }
   if (n === "adept ai") { tags.add("ai-agents"); tags.add("us"); }
-  if (n === "voiceflow") { tags.add("conversational-ai"); tags.add("no-code"); tags.add("us"); }
+  if (n === "voiceflow") { tags.add("conversational-ai"); tags.add("no-code"); tags.add("canada"); }
   if (n === "tray.io") { tags.add("automation"); tags.add("enterprise-saas"); tags.add("us"); }
   if (n === "workato") { tags.add("automation"); tags.add("enterprise-saas"); tags.add("us"); }
 
@@ -722,7 +722,6 @@ function assignTags(section, name, notes) {
   if (n === "coactive ai") { tags.add("ai-search"); tags.add("us"); }
   if (n === "you.com") { tags.add("ai-search"); tags.add("us"); }
   if (n === "hebbia") { tags.add("ai-search"); tags.add("fintech"); tags.add("us"); }
-
   // ── Region from notes ──
 
   const notesLower = notes.toLowerCase();
@@ -747,12 +746,18 @@ function assignTags(section, name, notes) {
       has(notesLower, "singapore")) {
     tags.add("apac");
   }
+  if (has(notesLower, "canada") || has(notesLower, "toronto") || has(notesLower, "montreal")) tags.add("canada");
+  if (has(notesLower, "latin america") || has(notesLower, "latam") || has(notesLower, "brazil") ||
+      has(notesLower, "argentina") || has(notesLower, "colombia")) tags.add("latam");
+  if (has(notesLower, "africa") || has(notesLower, "nigeria") || has(notesLower, "lagos") ||
+      has(notesLower, "kenya") || has(notesLower, "nairobi") || has(notesLower, "south africa")) tags.add("africa");
+  if (has(notesLower, "middle east") || has(notesLower, "mena") || has(notesLower, "uae")) tags.add("middle-east");
 
   // ── Ensure at least one region tag ──
-  const regionTags = ["us", "eu", "uk", "apac", "israel", "remote-first"];
+  const regionTags = ["us", "canada", "latam", "eu", "uk", "africa", "middle-east", "apac", "israel", "remote-first", "region-unclassified"];
   if (!regionTags.some((r) => tags.has(r))) {
-    // Default to US for companies without explicit location
-    tags.add("us");
+    // Unknown catalog geography must remain explicit; never silently call it US.
+    tags.add("region-unclassified");
   }
 
   // ── Cap at 5 tags, ensure at least 2 ──
@@ -829,6 +834,16 @@ for (let i = 0; i < lines.length; i++) {
     continue;
   }
 
+  // Aggregator feeds use a separate schema and are not members of the
+  // rotating company-source pool. Stop tag insertion at that top-level
+  // boundary so running this maintenance script cannot rewrite feed entries.
+  if (inTrackedCompanies && line.match(/^cross_company_feeds:/)) {
+    flushWithTags();
+    inTrackedCompanies = false;
+    out.push(line);
+    continue;
+  }
+
   if (!inTrackedCompanies) {
     out.push(line);
     continue;
diff --git a/scripts/balance-scan-results.mjs b/scripts/balance-scan-results.mjs
new file mode 100644
index 0000000..2bde989
--- /dev/null
+++ b/scripts/balance-scan-results.mjs
@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * Deterministically balance already-extracted scan candidates.
+ *
+ * Input candidates must include posting-derived `country_code`, `region`, and
+ * `location_status`; this script never guesses eligibility from company HQ.
+ *
+ * Usage:
+ *   node scripts/balance-scan-results.mjs candidates.json [portals.yml]
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDiversityPolicy } from '../lib/portal-diversity.mjs';
+
+export { parseDiversityPolicy } from '../lib/portal-diversity.mjs';
+
+const thisFile = fileURLToPath(import.meta.url);
+
+function normalized(value = '') {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function candidateSort(a, b) {
+  const scoreA = Number.isFinite(Number(a.relevance_score)) ? Number(a.relevance_score) : 0;
+  const scoreB = Number.isFinite(Number(b.relevance_score)) ? Number(b.relevance_score) : 0;
+  return scoreB - scoreA ||
+    normalized(a.company).localeCompare(normalized(b.company)) ||
+    normalized(a.title).localeCompare(normalized(b.title)) ||
+    String(a.url || '').localeCompare(String(b.url || ''));
+}
+
+function deduplicate(candidates) {
+  const seenUrls = new Set();
+  const seenRoles = new Set();
+  const unique = [];
+  for (const candidate of [...candidates].sort(candidateSort)) {
+    const urlKey = String(candidate.url || '').trim().toLowerCase();
+    // The same role can be independently posted for different hiring regions.
+    const roleKey = `${normalized(candidate.company)}::${normalized(candidate.title)}::${candidate.region || 'unknown'}`;
+    if ((urlKey && seenUrls.has(urlKey)) || seenRoles.has(roleKey)) continue;
+    if (urlKey) seenUrls.add(urlKey);
+    seenRoles.add(roleKey);
+    unique.push(candidate);
+  }
+  return unique;
+}
+
+export function balanceCandidates(rawCandidates, policy) {
+  if (!Array.isArray(rawCandidates)) throw new TypeError('candidates must be an array');
+  if (!policy?.regions?.length) throw new TypeError('policy must define regions');
+
+  const configuredRegions = new Set(policy.regions.map((region) => region.id));
+  const excludeUnknownLocations = policy.unknownLocation === 'exclude';
+  const review = [];
+  const excluded = [];
+  const eligible = [];
+
+  for (const candidate of rawCandidates) {
+    const status = candidate.location_status;
+    if (!candidate.company || !candidate.title || !candidate.url) {
+      excluded.push({ ...candidate, exclusion_reason: 'missing company, title, or URL' });
+    } else if (candidate.country_code !== 'US') {
+      excluded.push({
+        ...candidate,
+        exclusion_reason: candidate.country_code
+          ? `outside United States (${candidate.country_code})`
+          : 'ISO country code US is missing',
+      });
+    } else if (status === 'ineligible') {
+      excluded.push({ ...candidate, exclusion_reason: 'location ineligible' });
+    } else if (status === 'exploratory' || status === 'location_review') {
+      if (excludeUnknownLocations) {
+        excluded.push({ ...candidate, exclusion_reason: 'US location eligibility unconfirmed' });
+      } else {
+        review.push(candidate);
+      }
+    } else if (status !== 'eligible') {
+      if (excludeUnknownLocations) {
+        excluded.push({ ...candidate, exclusion_reason: 'US location eligibility missing' });
+      } else {
+        review.push({ ...candidate, location_status: 'location_review' });
+      }
+    } else if (!configuredRegions.has(candidate.region)) {
+      if (excludeUnknownLocations) {
+        excluded.push({ ...candidate, exclusion_reason: 'outside configured US region' });
+      } else {
+        review.push({ ...candidate, location_status: 'location_review' });
+      }
+    } else {
+      eligible.push(candidate);
+    }
+  }
+
+  const candidates = deduplicate(eligible);
+  const selected = [];
+  const selectedKeys = new Set();
+  const companyCounts = new Map();
+  const regionCounts = new Map();
+  const maxRegionCount = Math.max(1, Math.floor(policy.shortlistSize * policy.maxRegionShare));
+
+  function key(candidate) {
+    return String(candidate.url).trim().toLowerCase();
+  }
+
+  function canAdd(candidate, enforceRegionShare = true) {
+    if (selected.length >= policy.shortlistSize || selectedKeys.has(key(candidate))) return false;
+    const company = normalized(candidate.company);
+    if ((companyCounts.get(company) || 0) >= policy.maxResultsPerCompany) return false;
+    if (enforceRegionShare && (regionCounts.get(candidate.region) || 0) >= maxRegionCount) return false;
+    return true;
+  }
+
+  function add(candidate, enforceRegionShare = true) {
+    if (!canAdd(candidate, enforceRegionShare)) return false;
+    selected.push(candidate);
+    selectedKeys.add(key(candidate));
+    const company = normalized(candidate.company);
+    companyCounts.set(company, (companyCounts.get(company) || 0) + 1);
+    regionCounts.set(candidate.region, (regionCounts.get(candidate.region) || 0) + 1);
+    return true;
+  }
+
+  // Regional floor: prioritize distinct companies before additional roles.
+  for (const region of policy.regions) {
+    const pool = candidates.filter((candidate) => candidate.region === region.id);
+    const represented = new Set();
+    for (const candidate of pool) {
+      if (represented.size >= region.targetMinimumDistinctCompanies) break;
+      const company = normalized(candidate.company);
+      if (represented.has(company)) continue;
+      if (add(candidate)) represented.add(company);
+    }
+    for (const candidate of pool) {
+      if ((regionCounts.get(region.id) || 0) >= region.targetMinimumResults) break;
+      add(candidate);
+    }
+  }
+
+  // Overall company floor: if the catalog has enough supply, add a first role
+  // from new companies before relevance-based fill can consume the shortlist.
+  const representedCompanies = new Set(
+    selected.map((candidate) => normalized(candidate.company)),
+  );
+  for (const candidate of candidates) {
+    if (representedCompanies.size >= policy.minimumDistinctCompanies) break;
+    const company = normalized(candidate.company);
+    if (representedCompanies.has(company)) continue;
+    // The region-share ceiling is best effort; the explicit company floor takes
+    // precedence when remaining distinct-company supply is concentrated.
+    if (add(candidate, false)) representedCompanies.add(company);
+  }
+
+  // Fill by relevance while the regional ceiling can be respected.
+  for (const candidate of candidates) add(candidate, true);
+  // If eligible supply is concentrated, fill remaining space but keep the
+  // company cap. The resulting region-share gap is reported explicitly.
+  for (const candidate of candidates) add(candidate, false);
+
+  const coverage = {};
+  const gaps = [];
+  for (const region of policy.regions) {
+    const rows = selected.filter((candidate) => candidate.region === region.id);
+    const distinctCompanies = new Set(rows.map((candidate) => normalized(candidate.company))).size;
+    coverage[region.id] = { results: rows.length, distinct_companies: distinctCompanies };
+    if (rows.length < region.targetMinimumResults) {
+      gaps.push(`${region.id}: ${rows.length}/${region.targetMinimumResults} results`);
+    }
+    if (distinctCompanies < region.targetMinimumDistinctCompanies) {
+      gaps.push(`${region.id}: ${distinctCompanies}/${region.targetMinimumDistinctCompanies} distinct companies`);
+    }
+  }
+
+  const distinctCompanies = new Set(selected.map((candidate) => normalized(candidate.company))).size;
+  if (distinctCompanies < policy.minimumDistinctCompanies) {
+    gaps.push(`overall: ${distinctCompanies}/${policy.minimumDistinctCompanies} distinct companies`);
+  }
+  for (const [region, count] of regionCounts) {
+    if (selected.length && count / selected.length > policy.maxRegionShare) {
+      gaps.push(`${region}: ${(100 * count / selected.length).toFixed(1)}% exceeds ${(100 * policy.maxRegionShare).toFixed(1)}% target share`);
+    }
+  }
+
+  const reviewUnique = deduplicate(review);
+
+  return {
+    selected,
+    review: reviewUnique,
+    excluded,
+    summary: {
+      input: rawCandidates.length,
+      eligible_unique: candidates.length,
+      selected: selected.length,
+      review: reviewUnique.length,
+      excluded: excluded.length,
+      distinct_companies: distinctCompanies,
+      coverage,
+      gaps,
+    },
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: node scripts/balance-scan-results.mjs candidates.json [portals.yml]');
+    return;
+  }
+  const projectDir = resolve(process.env.JOB_FORGE_PROJECT || process.cwd());
+  const candidatePath = args[0] && resolve(projectDir, args[0]);
+  const portalPath = resolve(projectDir, args[1] || 'portals.yml');
+  if (!candidatePath || !existsSync(candidatePath)) throw new Error(`candidate JSON not found: ${candidatePath || '(missing)'}`);
+  if (!existsSync(portalPath)) throw new Error(`portal configuration not found: ${portalPath}`);
+  const input = JSON.parse(readFileSync(candidatePath, 'utf8'));
+  const candidates = Array.isArray(input) ? input : input.candidates;
+  const policy = parseDiversityPolicy(readFileSync(portalPath, 'utf8'));
+  console.log(JSON.stringify(balanceCandidates(candidates, policy), null, 2));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(thisFile)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`ERROR: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
diff --git a/scripts/check-iso-smoke.mjs b/scripts/check-iso-smoke.mjs
index a0d5cd5..dee5ad5 100644
--- a/scripts/check-iso-smoke.mjs
+++ b/scripts/check-iso-smoke.mjs
@@ -23,6 +23,7 @@ const checks = [
   ["H7 distrusts subagent prose", () => every(files.instructions, ["must originate from a file", "not from prior subagent prose"])],
   ["H8 keeps proxy secret and requires stock headless block detection", () => every(files.instructions, ["[H8]", "Do not transcribe `server`, `username`, `password`, or `bypass`", "`headless: true`", "`browserMode: \\\"stock\\\"`", "`blockDetection: true`", "`blockedSitePolicy: \\\"manual-handoff\\\"`"])],
   ["H9 points to Geometra MCP lifecycle logs", () => every(files.instructions, ["[H9]", ".jobforge-mcp/geometra-mcp.jsonl", "launcher_start", "heartbeat", "child_exit"])],
+  ["H10 enforces explicit US location eligibility", () => every(files.instructions, ["[H10]", "`country_code: US`", "`location_status: eligible`", "generic `Remote`", "North America"])],
   ["OpenCode addendum exists for task semantics", () => every(files.instructionsOpencode, ["OpenCode", "`task`", "launch acknowledgement", "Do not use `task` to poll status"])],
   ["root points to consolidated helper reference", () => every(files.instructions, ["[D8]", "modes/reference-local-helpers.md", "deterministic local helpers"])],
   ["helper reference covers score/timeline/prioritize/lineage", () => every(files.helpers, ["templates/score.json", "npx job-forge score:*", "templates/timeline.json", "npx job-forge timeline:*", "templates/prioritize.json", "npx job-forge prioritize:*", ".jobforge-lineage.json", "npx job-forge lineage:*"])],
diff --git a/scripts/verify-portal-diversity.mjs b/scripts/verify-portal-diversity.mjs
new file mode 100644
index 0000000..c8f9a28
--- /dev/null
+++ b/scripts/verify-portal-diversity.mjs
@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+
+/**
+ * Verify that a JobForge portal configuration keeps configured discovery and
+ * company-source coverage.
+ *
+ * This is a source/configuration check, not a claim that every scan will return
+ * suitable jobs in every region. Runtime scans must use the posting's actual
+ * location and report coverage gaps (see modes/scan.md).
+ *
+ * Usage:
+ *   node scripts/verify-portal-diversity.mjs [portals.yml] [--profile config/profile.yml] [--strict]
+ *   npm run verify:diversity
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = parseArgs(process.argv.slice(2));
+const PROJECT_DIR = resolve(process.env.JOB_FORGE_PROJECT || process.cwd());
+const projectPortals = resolve(PROJECT_DIR, 'portals.yml');
+const defaultConfigPath = existsSync(projectPortals)
+  ? projectPortals
+  : resolve(ROOT, 'templates/portals.example.yml');
+const configPath = cli.config
+  ? resolve(PROJECT_DIR, cli.config)
+  : defaultConfigPath;
+const defaultProfilePath = resolve(PROJECT_DIR, 'config/profile.yml');
+const profilePath = cli.profile
+  ? resolve(PROJECT_DIR, cli.profile)
+  : existsSync(defaultProfilePath)
+    ? defaultProfilePath
+    : null;
+const strict = cli.strict;
+
+if (cli.help) {
+  console.log(`verify-portal-diversity.mjs — check discovery and company coverage
+
+Usage:
+  node scripts/verify-portal-diversity.mjs [portals.yml] [--profile config/profile.yml] [--strict]
+  npm run verify:diversity
+
+Checks that every diversity_policy region is US-only, has location terms and
+enough enabled coverage queries, and that the shared US company-source pool can
+support the configured distinct-company target. Explicitly non-US boards must
+stay disabled, and enabled global feeds must have fail-closed US prefilters.
+When config/profile.yml exists (or --profile is passed), also checks that the
+personal scan-location policy is explicit and compatible with the portal buckets.
+Warnings fail only with --strict.`);
+  process.exit(0);
+}
+
+if (!existsSync(configPath)) {
+  console.error(`ERROR: portal configuration not found: ${configPath}`);
+  process.exit(1);
+}
+if (cli.profile && !existsSync(profilePath)) {
+  console.error(`ERROR: profile configuration not found: ${profilePath}`);
+  process.exit(1);
+}
+
+const text = readFileSync(configPath, 'utf8');
+let errors = 0;
+let warnings = 0;
+let upgradeRequired = false;
+const EXPECTED_US_REGION_IDS = [
+  'us_northeast',
+  'us_midwest',
+  'us_south',
+  'us_west',
+  'us_nationwide',
+];
+const EXPLICITLY_NON_US_QUERY_DOMAINS = [
+  'landing.jobs',
+  'swissdevjobs.ch',
+  'berlinstartupjobs.com',
+];
+
+function error(message) {
+  errors += 1;
+  console.error(`ERROR: ${message}`);
+}
+
+function upgradeError(message) {
+  upgradeRequired = true;
+  error(message);
+}
+
+function warn(message) {
+  warnings += 1;
+  console.warn(`WARN: ${message}`);
+}
+
+function parseArgs(args) {
+  const parsed = { config: null, profile: null, strict: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--strict') parsed.strict = true;
+    else if (arg === '--help' || arg === '-h') parsed.help = true;
+    else if (arg === '--profile') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) {
+        console.error('ERROR: --profile requires a path');
+        process.exit(2);
+      }
+      parsed.profile = value;
+      index += 1;
+    } else if (arg.startsWith('--profile=')) {
+      parsed.profile = arg.slice('--profile='.length);
+    } else if (arg.startsWith('--')) {
+      console.error(`ERROR: unknown option ${arg}`);
+      process.exit(2);
+    } else if (parsed.config === null) {
+      parsed.config = arg;
+    } else {
+      console.error(`ERROR: unexpected positional argument ${arg}`);
+      process.exit(2);
+    }
+  }
+  return parsed;
+}
+
+function parseInlineList(value = '') {
+  const match = value.match(/^\s*\[(.*)\]\s*$/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((item) => item.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+}
+
+function field(block, name) {
+  const match = block.match(new RegExp(`^\\s+${name}:\\s*(.+?)\\s*$`, 'm'));
+  return match?.[1]?.trim().replace(/\s+#.*$/, '');
+}
+
+function section(startKey, endKey = null) {
+  const startMatch = text.match(new RegExp(`^${startKey}:\\s*(?:#.*)?$`, 'm'));
+  if (!startMatch) return '';
+  const startIndex = startMatch.index;
+  if (!endKey) return text.slice(startIndex);
+  const remainderStart = startIndex + startMatch[0].length;
+  const endMatch = text.slice(remainderStart).match(new RegExp(`^${endKey}:\\s*(?:#.*)?$`, 'm'));
+  const endIndex = endMatch ? remainderStart + endMatch.index : text.length;
+  return text.slice(startIndex, endIndex);
+}
+
+function splitEntries(block) {
+  const matches = [...block.matchAll(/^  - name:\s*(.+?)\s*$/gm)];
+  return matches.map((match, index) => ({
+    name: match[1],
+    block: block.slice(match.index, matches[index + 1]?.index ?? block.length),
+  }));
+}
+
+const diversityBlock = section('diversity_policy', 'search_queries');
+if (!diversityBlock) upgradeError('portals.yml is missing diversity_policy');
+if (field(diversityBlock, 'enabled') !== 'true') error('diversity_policy.enabled must be true in the distributable template');
+if (field(diversityBlock, 'eligibility_first') !== 'true') error('diversity_policy.eligibility_first must be true');
+
+const regionMatches = [...diversityBlock.matchAll(/^    - id:\s*([a-z0-9_-]+)\s*$/gm)];
+const regions = regionMatches.map((match, index) => {
+  const block = diversityBlock.slice(match.index, regionMatches[index + 1]?.index ?? diversityBlock.length);
+  return {
+    id: match[1],
+    countryCodes: parseInlineList(field(block, 'country_codes')),
+    locationTerms: parseInlineList(field(block, 'job_location_terms')),
+    minimumQueries: Number.parseInt(field(block, 'minimum_enabled_queries') || '1', 10),
+    targetResults: Number.parseInt(field(block, 'target_minimum_results') || '1', 10),
+    targetCompanies: Number.parseInt(field(block, 'target_minimum_distinct_companies') || '1', 10),
+  };
+});
+const sourceCompanyTags = parseInlineList(field(diversityBlock, 'source_company_tags'));
+
+const configuredRegionIdList = regions.map((region) => region.id);
+if (
+  configuredRegionIdList.length !== EXPECTED_US_REGION_IDS.length ||
+  EXPECTED_US_REGION_IDS.some((id) => !configuredRegionIdList.includes(id))
+) {
+  error(`diversity_policy.regions must define the five US coverage buckets: ${EXPECTED_US_REGION_IDS.join(', ')}`);
+}
+if (sourceCompanyTags.length !== 1 || sourceCompanyTags[0] !== 'us') {
+  error('diversity_policy.source_company_tags must be [us] for the US source pool');
+}
+
+const duplicateRegionIds = regions
+  .map((region) => region.id)
+  .filter((id, index, all) => all.indexOf(id) !== index);
+if (duplicateRegionIds.length) error(`duplicate region ids: ${[...new Set(duplicateRegionIds)].join(', ')}`);
+
+const queries = splitEntries(section('search_queries', 'tracked_companies')).map((entry) => ({
+  ...entry,
+  enabled: field(entry.block, 'enabled') !== 'false',
+  query: field(entry.block, 'query') || '',
+  coverageRegions: parseInlineList(field(entry.block, 'coverage_regions')),
+}));
+
+const configuredRegionIds = new Set(regions.map((region) => region.id));
+for (const query of queries) {
+  for (const regionId of query.coverageRegions) {
+    if (!configuredRegionIds.has(regionId)) error(`${query.name}: coverage_regions references unknown id "${regionId}"`);
+  }
+  for (const domain of EXPLICITLY_NON_US_QUERY_DOMAINS) {
+    if (query.enabled && query.query.includes(`site:${domain}`)) {
+      error(`${query.name}: explicitly non-US board ${domain} must be disabled in the US-only template`);
+    }
+  }
+}
+
+const feeds = splitEntries(section('cross_company_feeds')).map((entry) => ({
+  ...entry,
+  enabled: field(entry.block, 'enabled') !== 'false',
+  type: field(entry.block, 'type'),
+  hasLocationFilter: /^    location_filter:\s*$/m.test(entry.block),
+  sourceField: field(entry.block, 'source_field'),
+  allowedValues: parseInlineList(field(entry.block, 'allowed_values')),
+  countryCodes: parseInlineList(field(entry.block, 'country_codes')),
+  requireExplicitMatch: field(entry.block, 'require_explicit_match'),
+  onMissing: field(entry.block, 'on_missing'),
+  onAmbiguous: field(entry.block, 'on_ambiguous'),
+}));
+
+for (const feed of feeds.filter((entry) => entry.enabled)) {
+  if (!feed.hasLocationFilter) {
+    error(`${feed.name}: enabled global feed requires a location_filter`);
+    continue;
+  }
+  if (feed.countryCodes.length !== 1 || feed.countryCodes[0] !== 'US') {
+    error(`${feed.name}: location_filter.country_codes must be [US]`);
+  }
+  if (feed.requireExplicitMatch !== 'true') {
+    error(`${feed.name}: location_filter.require_explicit_match must be true`);
+  }
+  if (feed.onMissing !== 'exclude' || feed.onAmbiguous !== 'exclude') {
+    error(`${feed.name}: missing and ambiguous feed locations must be excluded`);
+  }
+  if (feed.type === 'weworkremotely') {
+    if (feed.sourceField !== 'region') {
+      error(`${feed.name}: WeWorkRemotely location_filter.source_field must be region`);
+    }
+    if (feed.allowedValues.length !== 1 || feed.allowedValues[0] !== 'USA Only') {
+      error(`${feed.name}: WeWorkRemotely allowed_values must be ["USA Only"]`);
+    }
+  } else if (feed.type === 'remoteok' && feed.sourceField !== 'location') {
+    error(`${feed.name}: RemoteOK location_filter.source_field must be location`);
+  }
+}
+
+// Active configurations may define aggregator feeds after tracked_companies.
+// Keep those separate: feeds have a different schema and are not members of
+// the rotating, US-tagged company-source pool.
+const companies = splitEntries(section('tracked_companies', 'cross_company_feeds')).map((entry) => ({
+  ...entry,
+  enabled: field(entry.block, 'enabled') !== 'false',
+  tags: parseInlineList(field(entry.block, 'tags')),
+  careersUrl: field(entry.block, 'careers_url'),
+}));
+
+const enabledCompanies = companies.filter((company) => company.enabled);
+const enabledNameCounts = new Map();
+for (const company of enabledCompanies) {
+  enabledNameCounts.set(company.name.toLowerCase(), (enabledNameCounts.get(company.name.toLowerCase()) || 0) + 1);
+  if (!company.careersUrl) error(`${company.name}: enabled company is missing careers_url`);
+  if (!company.tags.length) warn(`${company.name}: enabled company has no tags and cannot contribute to source-mix coverage`);
+}
+
+for (const [name, count] of enabledNameCounts) {
+  if (count > 1) warn(`enabled company name appears ${count} times: ${name}`);
+}
+
+console.log(`Portal diversity check: ${regions.length} regions, ${queries.filter((q) => q.enabled).length} enabled queries, ${enabledCompanies.length} enabled company entries`);
+
+for (const region of regions) {
+  if (!region.locationTerms.length) error(`${region.id}: job_location_terms must not be empty`);
+  if (!Number.isInteger(region.minimumQueries) || region.minimumQueries < 1) {
+    error(`${region.id}: minimum_enabled_queries must be a positive integer`);
+  }
+  if (!Number.isInteger(region.targetResults) || region.targetResults < 1) {
+    error(`${region.id}: target_minimum_results must be a positive integer`);
+  }
+  if (!Number.isInteger(region.targetCompanies) || region.targetCompanies < 1) {
+    error(`${region.id}: target_minimum_distinct_companies must be a positive integer`);
+  }
+  if (region.countryCodes.length !== 1 || region.countryCodes[0] !== 'US') {
+    error(`${region.id}: country_codes must be [US] for US-only discovery`);
+  }
+
+  const coverageQueries = queries.filter(
+    (query) => query.enabled && query.coverageRegions.includes(region.id),
+  );
+  if (coverageQueries.length < region.minimumQueries) {
+    error(`${region.id}: ${coverageQueries.length} enabled coverage queries; requires ${region.minimumQueries}`);
+  }
+
+  console.log(`  ${region.id}: ${coverageQueries.length} coverage queries`);
+}
+
+const sourceCompanies = enabledCompanies.filter(
+  (company) => company.tags.some((tag) => sourceCompanyTags.includes(tag)),
+);
+const requiredSourceCompanies = Math.max(
+  Number.parseInt(field(diversityBlock, 'minimum_distinct_companies') || '1', 10),
+  ...regions.map((region) => region.targetCompanies),
+);
+if (sourceCompanies.length < requiredSourceCompanies) {
+  error(`US source pool has ${sourceCompanies.length} enabled companies; requires ${requiredSourceCompanies}`);
+} else if (sourceCompanies.length === requiredSourceCompanies) {
+  warn(`US source coverage has no headroom (${sourceCompanies.length} companies for a target of ${requiredSourceCompanies})`);
+}
+console.log(`  US source pool: ${sourceCompanies.length} catalog sources`);
+
+const termOwner = new Map();
+for (const region of regions) {
+  for (const term of region.locationTerms) {
+    const key = term.toLowerCase();
+    if (termOwner.has(key)) error(`job location term "${term}" belongs to both ${termOwner.get(key)} and ${region.id}`);
+    termOwner.set(key, region.id);
+  }
+}
+
+const unknownLocation = field(diversityBlock, 'unknown_location');
+if (unknownLocation !== 'exclude') {
+  error(`diversity_policy.unknown_location must be exclude for US-only discovery; got "${unknownLocation}"`);
+}
+const searchLocationConstraint = field(diversityBlock, 'search_location_constraint');
+if (!searchLocationConstraint || !/(United States|USA)/.test(searchLocationConstraint)) {
+  error('diversity_policy.search_location_constraint must explicitly constrain queries to the United States');
+}
+
+const integerValues = {};
+for (const integerField of ['shortlist_size', 'max_results_per_company', 'minimum_distinct_companies', 'tracked_company_scan_budget']) {
+  const value = Number.parseInt(field(diversityBlock, integerField) || '', 10);
+  integerValues[integerField] = value;
+  if (!Number.isInteger(value) || value < 1) error(`diversity_policy.${integerField} must be a positive integer`);
+}
+const maxRegionShare = Number.parseFloat(field(diversityBlock, 'max_region_share') || '');
+if (!(maxRegionShare > 0 && maxRegionShare <= 1)) error('diversity_policy.max_region_share must be greater than 0 and at most 1');
+if (integerValues.minimum_distinct_companies > integerValues.shortlist_size) {
+  error('diversity_policy.minimum_distinct_companies cannot exceed shortlist_size');
+}
+if (integerValues.tracked_company_scan_budget < integerValues.minimum_distinct_companies) {
+  error('diversity_policy.tracked_company_scan_budget cannot be lower than minimum_distinct_companies');
+}
+const targetResultTotal = regions.reduce((sum, region) => sum + region.targetResults, 0);
+if (targetResultTotal > integerValues.shortlist_size) {
+  error(`regional target_minimum_results total ${targetResultTotal} exceeds shortlist_size ${integerValues.shortlist_size}`);
+}
+const maxRegionCount = Math.floor(integerValues.shortlist_size * maxRegionShare);
+for (const region of regions) {
+  if (region.targetCompanies > region.targetResults) {
+    error(`${region.id}: distinct-company target cannot exceed result target`);
+  }
+  if (Number.isInteger(maxRegionCount) && region.targetResults > maxRegionCount) {
+    error(`${region.id}: target_minimum_results exceeds max_region_share capacity (${maxRegionCount})`);
+  }
+}
+if (field(diversityBlock, 'tracked_company_strategy') !== 'rotating_source_pool') {
+  error('diversity_policy.tracked_company_strategy must be rotating_source_pool in the distributable template');
+}
+
+if (profilePath) validateProfileScanPolicy(profilePath, configuredRegionIds);
+
+if (upgradeRequired) {
+  console.error(`
+UPGRADE REQUIRED: JobForge left your personal YAML unchanged because nested YAML
+cannot be merged safely without risking your custom profile, queries, or company
+list. Make these targeted edits, then rerun the check:
+
+  1. portals.yml: merge diversity_policy and the five "Coverage — US ..."
+     search queries from templates/portals.example.yml; add the "us" tag only
+     to tracked companies you want in the rotating US source pool.
+  2. config/profile.yml: merge the US scan fields from the top-level location
+     block in config/profile.example.yml, keeping your existing personal values.
+  3. npx job-forge verify:diversity portals.yml --profile config/profile.yml
+
+Scanning must stop before any network request until this check passes.`);
+}
+
+console.log(`Result: ${errors} errors, ${warnings} warnings${strict ? ' (strict)' : ''}`);
+process.exit(errors > 0 || (strict && warnings > 0) ? 1 : 0);
+
+function validateProfileScanPolicy(path, regionIds) {
+  const profile = readFileSync(path, 'utf8');
+  const locationBlock = yamlBlock(profile, 'location', 0);
+  if (!locationBlock) {
+    upgradeError('config/profile.yml is missing the top-level location block required for US-only scanning');
+    return;
+  }
+
+  const eligibleCountries = yamlListField(locationBlock, 'eligible_work_country_codes', 2);
+  if (!eligibleCountries.present) {
+    upgradeError('config/profile.yml location.eligible_work_country_codes is missing');
+  } else if (!eligibleCountries.values.includes('US')) {
+    upgradeError('config/profile.yml location.eligible_work_country_codes must include US');
+  }
+
+  const preferredRegions = yamlListField(locationBlock, 'preferred_region_ids', 2);
+  validateProfileRegions(preferredRegions, 'location.preferred_region_ids', regionIds);
+
+  const exploratory = yamlScalarField(locationBlock, 'include_exploratory_regions', 2);
+  if (!exploratory.present) {
+    upgradeError('config/profile.yml location.include_exploratory_regions is missing');
+  } else if (exploratory.value !== 'false') {
+    upgradeError('config/profile.yml location.include_exploratory_regions must be false for fail-closed US-only scanning');
+  }
+
+  const relocation = yamlScalarField(locationBlock, 'willing_to_relocate', 2);
+  if (!relocation.present || !['true', 'false'].includes(relocation.value)) {
+    upgradeError('config/profile.yml location.willing_to_relocate must be an explicit true or false');
+  }
+
+  const remoteBlock = yamlBlock(locationBlock, 'remote', 2);
+  if (!remoteBlock) {
+    upgradeError('config/profile.yml location.remote scan policy is missing');
+    return;
+  }
+
+  const remoteEnabled = yamlScalarField(remoteBlock, 'enabled', 4);
+  if (!remoteEnabled.present || !['true', 'false'].includes(remoteEnabled.value)) {
+    upgradeError('config/profile.yml location.remote.enabled must be an explicit true or false');
+  }
+
+  const remoteRegions = yamlListField(remoteBlock, 'allowed_region_ids', 4);
+  validateProfileRegions(remoteRegions, 'location.remote.allowed_region_ids', regionIds);
+
+  const explicitEligibility = yamlScalarField(remoteBlock, 'require_explicit_location_eligibility', 4);
+  if (!explicitEligibility.present) {
+    upgradeError('config/profile.yml location.remote.require_explicit_location_eligibility is missing');
+  } else if (explicitEligibility.value !== 'true') {
+    upgradeError('config/profile.yml location.remote.require_explicit_location_eligibility must be true');
+  }
+
+  if (!upgradeRequired) console.log('  profile scan policy: explicit US-only constraints');
+}
+
+function validateProfileRegions(parsed, label, regionIds) {
+  if (!parsed.present) {
+    upgradeError(`config/profile.yml ${label} is missing`);
+    return;
+  }
+  const duplicates = parsed.values.filter((value, index, values) => values.indexOf(value) !== index);
+  if (duplicates.length) {
+    upgradeError(`config/profile.yml ${label} contains duplicate ids: ${[...new Set(duplicates)].join(', ')}`);
+  }
+  const unknown = parsed.values.filter((value) => !regionIds.has(value));
+  if (unknown.length) {
+    upgradeError(`config/profile.yml ${label} references unknown portal region ids: ${[...new Set(unknown)].join(', ')}`);
+  }
+}
+
+function yamlBlock(document, name, indent) {
+  const lines = document.replace(/\r\n?/g, '\n').split('\n');
+  const prefix = ' '.repeat(indent);
+  const start = lines.findIndex((line) => new RegExp(`^${prefix}${name}:\\s*(?:#.*)?$`).test(line));
+  if (start < 0) return '';
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const lineIndent = line.match(/^ */)[0].length;
+    if (lineIndent <= indent) {
+      end = index;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n');
+}
+
+function yamlScalarField(block, name, indent) {
+  const prefix = ' '.repeat(indent);
+  const match = block.match(new RegExp(`^${prefix}${name}:[ \\t]*(.*?)[ \\t]*$`, 'm'));
+  if (!match) return { present: false, value: '' };
+  return {
+    present: true,
+    value: match[1].replace(/\s+#.*$/, '').trim().replace(/^['"]|['"]$/g, ''),
+  };
+}
+
+function yamlListField(block, name, indent) {
+  const scalar = yamlScalarField(block, name, indent);
+  if (!scalar.present) return { present: false, values: [] };
+  if (scalar.value.startsWith('[') && scalar.value.endsWith(']')) {
+    return { present: true, values: parseInlineList(scalar.value) };
+  }
+  if (scalar.value) return { present: true, values: [scalar.value] };
+
+  const lines = block.replace(/\r\n?/g, '\n').split('\n');
+  const prefix = ' '.repeat(indent);
+  const start = lines.findIndex((line) => new RegExp(`^${prefix}${name}:\\s*(?:#.*)?$`).test(line));
+  const values = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const lineIndent = line.match(/^ */)[0].length;
+    if (lineIndent <= indent) break;
+    const item = line.match(new RegExp(`^${' '.repeat(indent + 2)}-\\s*(.+?)\\s*$`));
+    if (item) values.push(item[1].replace(/\s+#.*$/, '').trim().replace(/^['"]|['"]$/g, ''));
+  }
+  return { present: true, values };
+}
diff --git a/templates/context.json b/templates/context.json
index 8fcb810..d61853e 100644
--- a/templates/context.json
+++ b/templates/context.json
@@ -7,7 +7,7 @@
     {
       "name": "base",
       "description": "Shared JobForge orchestration contract.",
-      "tokenBudget": 4000,
+      "tokenBudget": 4200,
       "files": [
         {
           "path": "AGENTS.harness.md",
@@ -19,7 +19,7 @@
         },
         {
           "path": "iso/instructions.md",
-          "maxTokens": 3500,
+          "maxTokens": 4100,
           "required": false,
           "notes": [
             "Harness-source fallback; mode/reference files should be selected through narrower bundles."
@@ -46,11 +46,11 @@
       "name": "auto-pipeline",
       "extends": "shared",
       "description": "Default JD/URL pipeline context.",
-      "tokenBudget": 12000,
+      "tokenBudget": 14000,
       "files": [
         {
           "path": "modes/auto-pipeline.md",
-          "maxTokens": 2000
+          "maxTokens": 2500
         },
         {
           "path": "modes/reference-setup.md",
@@ -122,11 +122,11 @@
       "name": "apply",
       "extends": "shared",
       "description": "Application form-fill context with Geometra recovery rules.",
-      "tokenBudget": 23000,
+      "tokenBudget": 28000,
       "files": [
         {
           "path": "modes/apply.md",
-          "maxTokens": 7800
+          "maxTokens": 9000
         },
         {
           "path": "modes/reference-geometra.md",
@@ -163,11 +163,11 @@
       "name": "scan",
       "extends": "shared",
       "description": "Portal scanning context.",
-      "tokenBudget": 18000,
+      "tokenBudget": 22000,
       "files": [
         {
           "path": "modes/scan.md",
-          "maxTokens": 6500
+          "maxTokens": 8500
         },
         {
           "path": "modes/reference-portals.md",
diff --git a/templates/facts.json b/templates/facts.json
index b36aecf..398b27f 100644
--- a/templates/facts.json
+++ b/templates/facts.json
@@ -124,7 +124,19 @@
           "fact": "job.url",
           "key": "url:{url}",
           "value": "{url}",
-          "fields": ["date", "company", "role", "url", "ats"],
+          "fields": [
+            "url",
+            "first_seen",
+            "portal",
+            "title",
+            "company",
+            "status",
+            "location",
+            "country_code",
+            "region",
+            "location_status",
+            "note"
+          ],
           "tags": ["scan", "url"]
         }
       ]
@@ -136,18 +148,20 @@
       "records": [
         {
           "fact": "candidate.ready",
-          "path": "$.candidates[]",
-          "key": "{companyRoleKey}",
-          "value": "{url}",
+          "path": "$.candidates[].facts",
+          "key": "{companyRoleKey.value}",
+          "value": "{url.value}",
           "fields": {
-            "id": "{id}",
-            "company": "{company}",
-            "role": "{role}",
-            "companyRoleKey": "{companyRoleKey}",
-            "url": "{url}",
-            "score": "{score}",
-            "gateStatus": "{gate.status}",
-            "locationStatus": "{location.status}"
+            "id": "{id.value}",
+            "company": "{company.value}",
+            "role": "{role.value}",
+            "companyRoleKey": "{companyRoleKey.value}",
+            "url": "{url.value}",
+            "score": "{score.value}",
+            "country_code": "{country_code.value}",
+            "region": "{region.value}",
+            "location_status": "{location_status.value}",
+            "locationStatus": "{location_status.value}"
           },
           "tags": ["candidate", "preflight"]
         }
@@ -160,18 +174,20 @@
       "records": [
         {
           "fact": "candidate.ready",
-          "path": "$[]",
-          "key": "{companyRoleKey}",
-          "value": "{url}",
+          "path": "$[].facts",
+          "key": "{companyRoleKey.value}",
+          "value": "{url.value}",
           "fields": {
-            "id": "{id}",
-            "company": "{company}",
-            "role": "{role}",
-            "companyRoleKey": "{companyRoleKey}",
-            "url": "{url}",
-            "score": "{score}",
-            "gateStatus": "{gate.status}",
-            "locationStatus": "{location.status}"
+            "id": "{id.value}",
+            "company": "{company.value}",
+            "role": "{role.value}",
+            "companyRoleKey": "{companyRoleKey.value}",
+            "url": "{url.value}",
+            "score": "{score.value}",
+            "country_code": "{country_code.value}",
+            "region": "{region.value}",
+            "location_status": "{location_status.value}",
+            "locationStatus": "{location_status.value}"
           },
           "tags": ["candidate", "preflight"]
         }
diff --git a/templates/index.json b/templates/index.json
index cb3bcf0..2053b13 100644
--- a/templates/index.json
+++ b/templates/index.json
@@ -115,8 +115,8 @@
         {
           "kind": "jobforge.scan.url",
           "key": "url:{url}",
-          "value": "{company} - {role}",
-          "fields": ["date", "company", "role", "url", "ats"],
+          "value": "{company} - {title}",
+          "fields": ["url", "first_seen", "portal", "title", "company", "status", "location", "country_code", "region", "location_status", "note"],
           "tags": ["scan", "url"]
         }
       ]
diff --git a/templates/portals.example.yml b/templates/portals.example.yml
index aba211b..1f3e45e 100644
--- a/templates/portals.example.yml
+++ b/templates/portals.example.yml
@@ -7,6 +7,8 @@
 #   3. WebSearch with site: filters (broad discovery, may be stale)
 #
 # IMPORTANT: Each company in tracked_companies MUST have careers_url.
+# Geographic tags on companies describe source/catalog coverage only. The scanner
+# must use each posting's actual job location for eligibility and diversity.
 #
 # HOW TO CUSTOMIZE:
 #   1. Copy this file to portals.yml in the project root
@@ -88,11 +90,92 @@ title_filter:
     - "Head"
     - "Director"
 
+# -- US-only discovery and company diversity --
+# Discover only jobs whose posting explicitly supports work in the United
+# States. Company diversity is preserved, but non-US and location-ambiguous
+# roles are excluded rather than used to fill the shortlist.
+diversity_policy:
+  enabled: true
+  eligibility_first: true
+  unknown_location: exclude      # required for US-only discovery
+  shortlist_size: 30
+  max_results_per_company: 3
+  max_region_share: 0.40
+  minimum_distinct_companies: 8
+  tracked_company_scan_budget: 60
+  tracked_company_strategy: rotating_source_pool
+  source_company_tags: [us]
+  # Append this clause to every enabled generic WebSearch query at scan time.
+  search_location_constraint: '("United States" OR USA OR "US Remote" OR "Remote - United States" OR "Remote, US")'
+  regions:
+    - id: us_northeast
+      label: US Northeast
+      country_codes: [US]
+      job_location_terms: [Connecticut, Maine, Massachusetts, New Hampshire, Rhode Island, Vermont, New Jersey, New York, Pennsylvania, Boston, NYC, Philadelphia]
+      minimum_enabled_queries: 1
+      target_minimum_results: 2
+      target_minimum_distinct_companies: 2
+    - id: us_midwest
+      label: US Midwest
+      country_codes: [US]
+      job_location_terms: [Illinois, Indiana, Michigan, Ohio, Wisconsin, Iowa, Kansas, Minnesota, Missouri, Nebraska, North Dakota, South Dakota, Chicago, Detroit, Minneapolis]
+      minimum_enabled_queries: 1
+      target_minimum_results: 2
+      target_minimum_distinct_companies: 2
+    - id: us_south
+      label: US South
+      country_codes: [US]
+      job_location_terms: [Alabama, Arkansas, Delaware, Florida, Georgia, Kentucky, Louisiana, Maryland, Mississippi, North Carolina, Oklahoma, South Carolina, Tennessee, Texas, Virginia, West Virginia, District of Columbia, Atlanta, Austin, Dallas, Miami, Washington DC]
+      minimum_enabled_queries: 1
+      target_minimum_results: 2
+      target_minimum_distinct_companies: 2
+    - id: us_west
+      label: US West
+      country_codes: [US]
+      job_location_terms: [Alaska, Arizona, California, Colorado, Hawaii, Idaho, Montana, Nevada, New Mexico, Oregon, Utah, Washington State, Wyoming, Denver, Los Angeles, Portland Oregon, San Francisco, Seattle]
+      minimum_enabled_queries: 1
+      target_minimum_results: 2
+      target_minimum_distinct_companies: 2
+    - id: us_nationwide
+      label: US nationwide / remote
+      country_codes: [US]
+      job_location_terms: [United States, USA, US only, US Remote, Remote - United States, Remote US, Anywhere in the US]
+      minimum_enabled_queries: 1
+      target_minimum_results: 2
+      target_minimum_distinct_companies: 2
+
 # -- Search queries --
 # Each query triggers a WebSearch. Use site: to filter by portal.
 # The scanner extracts title, URL, and company from results.
 
 search_queries:
+  # These queries require explicit US location evidence. The scanner also adds
+  # the same US constraint to every enabled generic query below.
+  - name: Coverage — US Northeast
+    query: '(site:jobs.ashbyhq.com OR site:job-boards.greenhouse.io OR site:jobs.lever.co) ("New York" OR Boston OR Philadelphia) (Engineer OR "Product Manager" OR Data OR AI)'
+    coverage_regions: [us_northeast]
+    enabled: true
+
+  - name: Coverage — US Midwest
+    query: '(site:jobs.ashbyhq.com OR site:job-boards.greenhouse.io OR site:jobs.lever.co) (Chicago OR Detroit OR Minneapolis OR Ohio) (Engineer OR "Product Manager" OR Data OR AI)'
+    coverage_regions: [us_midwest]
+    enabled: true
+
+  - name: Coverage — US South
+    query: '(site:jobs.ashbyhq.com OR site:job-boards.greenhouse.io OR site:jobs.lever.co) (Texas OR Atlanta OR Miami OR "North Carolina") (Engineer OR "Product Manager" OR Data OR AI)'
+    coverage_regions: [us_south]
+    enabled: true
+
+  - name: Coverage — US West
+    query: '(site:jobs.ashbyhq.com OR site:job-boards.greenhouse.io OR site:jobs.lever.co) (California OR Seattle OR Denver OR Arizona) (Engineer OR "Product Manager" OR Data OR AI)'
+    coverage_regions: [us_west]
+    enabled: true
+
+  - name: Coverage — US nationwide / remote
+    query: '(site:jobs.ashbyhq.com OR site:job-boards.greenhouse.io OR site:jobs.lever.co) ("Remote - United States" OR "Remote, US" OR "US Remote") (Engineer OR "Product Manager" OR Data OR AI)'
+    coverage_regions: [us_nationwide]
+    enabled: true
+
   # -- Ashby --
   - name: Ashby — AI PM
     query: 'site:jobs.ashbyhq.com "AI Product Manager" OR "Senior Product Manager AI" remote'
@@ -343,18 +426,20 @@ search_queries:
     query: 'site:bamboohr.com "Software Engineer" OR "DevOps" OR "Data Engineer" remote'
     enabled: true
 
-  # -- European Job Boards --
+  # -- European Job Boards (disabled by the US-only default) --
+  # These domains are intentionally retained as customization examples. Do not
+  # enable them unless the US-only diversity and eligibility policy is changed.
   - name: Landing.jobs — Engineering
     query: 'site:landing.jobs "Software Engineer" OR "Backend" OR "Full Stack" OR "Data Engineer"'
-    enabled: true
+    enabled: false
 
   - name: SwissDevJobs — Engineering
     query: 'site:swissdevjobs.ch "Software Engineer" OR "Backend" OR "Full Stack" OR "DevOps"'
-    enabled: true
+    enabled: false
 
   - name: Berlin Startup Jobs — Engineering
     query: 'site:berlinstartupjobs.com "Software Engineer" OR "Backend" OR "Frontend" OR "Data"'
-    enabled: true
+    enabled: false
 
   # -- Role-Specific Cross-Board: Senior/Staff/Principal --
   - name: Staff Engineer — All platforms
@@ -888,7 +973,7 @@ tracked_companies:
   - name: Cohere
     careers_url: https://jobs.ashbyhq.com/cohere
     notes: "AI/LLM provider. Toronto + remote."
-    tags: ["ai-lab", "remote-first"]
+    tags: ["ai-lab", "canada", "remote-first"]
     enabled: true
 
   - name: Together AI
@@ -2114,7 +2199,7 @@ tracked_companies:
   - name: Voiceflow
     careers_url: https://jobs.ashbyhq.com/voiceflow
     notes: "Conversational AI agent builder. Toronto."
-    tags: ["automation", "ai-agents", "conversational-ai", "no-code", "us"]
+    tags: ["automation", "ai-agents", "conversational-ai", "no-code", "canada"]
     enabled: true
 
   - name: Tray.io
@@ -2628,7 +2713,7 @@ tracked_companies:
   - name: ContentSquare
     careers_url: https://job-boards.greenhouse.io/contentsquare
     notes: "Paris. Digital experience analytics + AI."
-    tags: ["eu", "fintech", "us", "analytics"]
+    tags: ["eu", "analytics"]
     enabled: true
 
   - name: Dataiku
@@ -2656,7 +2741,7 @@ tracked_companies:
     careers_url: https://job-boards.greenhouse.io/collibra
     api: https://boards-api.greenhouse.io/v1/boards/collibra/jobs
     notes: "Brussels. Data intelligence + AI governance."
-    tags: ["eu", "defense", "analytics", "compliance"]
+    tags: ["eu", "analytics", "compliance"]
     enabled: true
 
   - name: MessageBird (Bird)
@@ -3012,7 +3097,7 @@ tracked_companies:
   - name: Liveblocks
     careers_url: https://jobs.ashbyhq.com/liveblocks
     notes: "Real-time collaboration infrastructure."
-    tags: ["developer-tools", "fintech", "us", "collaboration"]
+    tags: ["developer-tools", "us", "collaboration"]
     enabled: true
 
   - name: Convex
@@ -3179,6 +3264,11 @@ tracked_companies:
 #   - weworkremotely  → RSS 2.0 XML per category
 #   - remoteok        → JSON array, first element is a legal disclaimer (skipped)
 #
+# US-only rule: every enabled global feed must define a fail-closed
+# location_filter. Apply it before category/tag/title filtering, then verify the
+# full posting. Missing or ambiguous location metadata is excluded, never sent
+# to review or used to satisfy a diversity target.
+#
 # See modes/scan.md → "Level 2 — ATS / Aggregator APIs" for full shape docs.
 
 cross_company_feeds:
@@ -3189,6 +3279,16 @@ cross_company_feeds:
     type: weworkremotely
     feed: remote-programming-jobs
     url: https://weworkremotely.com/categories/remote-programming-jobs.rss
+    # WWR RSS exposes <region>; "USA Only" is its explicit US-only value.
+    # "Anywhere in the World", "North America Only", and "Americas Only" do
+    # not satisfy this distributable's strict explicit-US gate.
+    location_filter:
+      source_field: region
+      allowed_values: ["USA Only"]
+      country_codes: [US]
+      require_explicit_match: true
+      on_missing: exclude
+      on_ambiguous: exclude
     # Optional pre-filter applied BEFORE title_filter. Drops obviously
     # off-target entries without cluttering scan-history.
     category_filter:
@@ -3200,18 +3300,39 @@ cross_company_feeds:
     type: weworkremotely
     feed: remote-devops-sysadmin-jobs
     url: https://weworkremotely.com/categories/remote-devops-sysadmin-jobs.rss
+    location_filter:
+      source_field: region
+      allowed_values: ["USA Only"]
+      country_codes: [US]
+      require_explicit_match: true
+      on_missing: exclude
+      on_ambiguous: exclude
     enabled: true
 
   - name: WeWorkRemotely — Product
     type: weworkremotely
     feed: remote-product-jobs
     url: https://weworkremotely.com/categories/remote-product-jobs.rss
+    location_filter:
+      source_field: region
+      allowed_values: ["USA Only"]
+      country_codes: [US]
+      require_explicit_match: true
+      on_missing: exclude
+      on_ambiguous: exclude
     enabled: true
 
   - name: WeWorkRemotely — All Other
     type: weworkremotely
     feed: all-other-remote-jobs
     url: https://weworkremotely.com/categories/all-other-remote-jobs.rss
+    location_filter:
+      source_field: region
+      allowed_values: ["USA Only"]
+      country_codes: [US]
+      require_explicit_match: true
+      on_missing: exclude
+      on_ambiguous: exclude
     # This category is very broad — start disabled, enable if signal is good.
     enabled: false
 
@@ -3223,6 +3344,16 @@ cross_company_feeds:
     url: https://remoteok.com/api
     # Required — RemoteOK returns 403 without a browser-like UA.
     user_agent: "Mozilla/5.0 (compatible; JobForgeScanner/1.0; +https://github.com/Agent-Pattern-Labs/JobForge)"
+    # RemoteOK's `location` field is optional. Normalize an explicit location
+    # to ISO country code US; never infer eligibility from the company, tags,
+    # salary currency, or the word "remote". Missing/ambiguous values fail
+    # closed before tag/title filtering, and the full posting is still checked.
+    location_filter:
+      source_field: location
+      country_codes: [US]
+      require_explicit_match: true
+      on_missing: exclude
+      on_ambiguous: exclude
     # Pre-filter on entry.tags (case-insensitive substring match against the
     # array). Row passes if ANY positive matches AND NO negative matches.
     tag_filter:
diff --git a/templates/preflight.json b/templates/preflight.json
index fc5b1b8..b302974 100644
--- a/templates/preflight.json
+++ b/templates/preflight.json
@@ -3,7 +3,7 @@
   "workflows": [
     {
       "name": "jobforge.apply",
-      "description": "Plan safe JobForge application dispatch rounds before Geometra/task work starts.",
+      "description": "Plan safe US-eligible JobForge application dispatch rounds before Geometra/task work starts.",
       "roundSize": 2,
       "idFact": "id",
       "conflictFact": "companyRoleKey",
@@ -13,14 +13,20 @@
         "role",
         "companyRoleKey",
         "url",
-        "score"
+        "score",
+        "country_code",
+        "region",
+        "location_status"
       ],
       "sourceRequiredFacts": [
         "company",
         "role",
         "companyRoleKey",
         "url",
-        "score"
+        "score",
+        "country_code",
+        "region",
+        "location_status"
       ],
       "requireGateSources": true,
       "gatePolicy": {
diff --git a/test/context-mode-budgets.test.mjs b/test/context-mode-budgets.test.mjs
new file mode 100644
index 0000000..398c846
--- /dev/null
+++ b/test/context-mode-budgets.test.mjs
@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import { planJobForgeContextBundle } from '../lib/jobforge-context.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+for (const [bundleName, modePath] of [
+  ['auto-pipeline', 'modes/auto-pipeline.md'],
+  ['apply', 'modes/apply.md'],
+  ['scan', 'modes/scan.md'],
+]) {
+  test(`${bundleName} context preserves the complete mode file`, () => {
+    const plan = planJobForgeContextBundle(bundleName, { root: ROOT }, ROOT);
+    const mode = plan.files.find((file) => file.path === modePath);
+    assert.ok(mode, `${modePath} must be part of the ${bundleName} bundle`);
+    assert.ok(mode.maxTokens >= mode.tokens, `${modePath} is ${mode.tokens} tokens but capped at ${mode.maxTokens}`);
+    assert.ok(plan.tokenBudget >= plan.totals.tokens, `${bundleName} bundle is ${plan.totals.tokens} tokens but capped at ${plan.tokenBudget}`);
+  });
+}
diff --git a/test/diversity-cli.test.mjs b/test/diversity-cli.test.mjs
new file mode 100644
index 0000000..f1aafd5
--- /dev/null
+++ b/test/diversity-cli.test.mjs
@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = join(ROOT, 'bin', 'job-forge.mjs');
+
+function runCli(projectDir, args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    env: { ...process.env, JOB_FORGE_PROJECT: projectDir },
+  });
+}
+
+test('consumer CLI verifies its portals file and balances its candidate file', (t) => {
+  const projectDir = mkdtempSync(join(tmpdir(), 'jobforge-diversity-cli-'));
+  t.after(() => rmSync(projectDir, { recursive: true, force: true }));
+  writeFileSync(
+    join(projectDir, 'portals.yml'),
+    readFileSync(join(ROOT, 'templates', 'portals.example.yml'), 'utf8'),
+  );
+  mkdirSync(join(projectDir, 'config'));
+  writeFileSync(
+    join(projectDir, 'config', 'profile.yml'),
+    readFileSync(join(ROOT, 'config', 'profile.example.yml'), 'utf8'),
+  );
+  writeFileSync(
+    join(projectDir, 'candidates.json'),
+    JSON.stringify([
+      {
+        company: 'Acme',
+        title: 'Engineer',
+        url: 'https://example.test/jobs/1',
+        country_code: 'US',
+        region: 'us_northeast',
+        location_status: 'eligible',
+        relevance_score: 4.5,
+      },
+    ]),
+  );
+
+  const verify = runCli(projectDir, [
+    'verify:diversity',
+    'portals.yml',
+    '--profile',
+    'config/profile.yml',
+    '--strict',
+  ]);
+  assert.equal(verify.status, 0, verify.stderr || verify.stdout);
+  assert.match(verify.stdout, /0 errors, 0 warnings/);
+
+  const balance = runCli(projectDir, ['balance:scan', 'candidates.json']);
+  assert.equal(balance.status, 0, balance.stderr || balance.stdout);
+  const result = JSON.parse(balance.stdout);
+  assert.equal(result.selected.length, 1);
+  assert.equal(result.selected[0].country_code, 'US');
+});
diff --git a/test/facts-us-location.test.mjs b/test/facts-us-location.test.mjs
new file mode 100644
index 0000000..81747dd
--- /dev/null
+++ b/test/facts-us-location.test.mjs
@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import { buildFacts, loadFactsConfig } from '@agent-pattern-labs/iso-facts';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG = loadFactsConfig(JSON.parse(readFileSync(join(ROOT, 'templates/facts.json'), 'utf8')));
+
+function sourced(value, source = 'reports/001-acme.md:1') {
+  return { value, source };
+}
+
+function preflightCandidate() {
+  return {
+    facts: {
+      id: sourced('job-1'),
+      company: sourced('Acme'),
+      role: sourced('Staff Engineer'),
+      companyRoleKey: sourced('company-role:acme:staff-engineer', 'templates/canon.json'),
+      url: sourced('https://jobs.example.com/1', 'data/pipeline.md:1'),
+      score: sourced('4.2/5'),
+      country_code: sourced('US'),
+      region: sourced('us_west'),
+      location_status: sourced('eligible'),
+    },
+    // This legacy field must not override the canonical sourced fact.
+    location: { status: 'location_review' },
+  };
+}
+
+function buildFrom(relativePath, contents) {
+  const root = mkdtempSync(join(tmpdir(), 'jobforge-facts-'));
+  try {
+    const target = join(root, relativePath);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, contents);
+    return buildFacts(CONFIG, { root });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const [label, input] of [
+  ['object wrapper', { candidates: [preflightCandidate()] }],
+  ['top-level array', [preflightCandidate()]],
+]) {
+  test(`preflight ${label} retains canonical US location facts`, () => {
+    const factSet = buildFrom('batch/preflight-candidates.json', `${JSON.stringify(input)}\n`);
+    const facts = factSet.facts.filter((fact) => fact.fact === 'candidate.ready');
+    assert.equal(facts.length, 1);
+    assert.equal(facts[0].fields.country_code, 'US');
+    assert.equal(facts[0].fields.region, 'us_west');
+    assert.equal(facts[0].fields.location_status, 'eligible');
+    assert.equal(facts[0].fields.locationStatus, 'eligible');
+    assert.notEqual(facts[0].fields.location_status, 'location_review');
+  });
+}
+
+test('scan history uses the canonical URL-first 11-column schema', () => {
+  const header = 'url\tfirst_seen\tportal\ttitle\tcompany\tstatus\tlocation\tcountry_code\tregion\tlocation_status\tnote';
+  const row = 'https://jobs.example.com/1\t2026-07-17\tAshby\tStaff Engineer\tAcme\tadded\tSeattle, WA\tUS\tus_west\teligible\t-';
+  const factSet = buildFrom('data/scan-history.tsv', `${header}\n${row}\n`);
+  const fact = factSet.facts.find((item) => item.source.name === 'scan-history');
+  assert.ok(fact);
+  assert.deepEqual(fact.fields, {
+    url: 'https://jobs.example.com/1',
+    first_seen: '2026-07-17',
+    portal: 'Ashby',
+    title: 'Staff Engineer',
+    company: 'Acme',
+    status: 'added',
+    location: 'Seattle, WA',
+    country_code: 'US',
+    region: 'us_west',
+    location_status: 'eligible',
+    note: '-',
+  });
+});
diff --git a/test/index-scan-history.test.mjs b/test/index-scan-history.test.mjs
new file mode 100644
index 0000000..19a6ac5
--- /dev/null
+++ b/test/index-scan-history.test.mjs
@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import { buildIndex, loadIndexConfig } from '@agent-pattern-labs/iso-index';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG = loadIndexConfig(JSON.parse(readFileSync(join(ROOT, 'templates/index.json'), 'utf8')));
+
+test('scan history index uses canonical URL-first title and US location fields', (t) => {
+  const root = mkdtempSync(join(tmpdir(), 'jobforge-index-scan-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const target = join(root, 'data', 'scan-history.tsv');
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(
+    target,
+    [
+      'url\tfirst_seen\tportal\ttitle\tcompany\tstatus\tlocation\tcountry_code\tregion\tlocation_status\tnote',
+      'https://jobs.example.com/1\t2026-07-17\tAshby\tStaff Engineer\tAcme\tadded\tSeattle, WA\tUS\tus_west\teligible\t-',
+      '',
+    ].join('\n'),
+  );
+
+  const index = buildIndex(CONFIG, { root });
+  const record = index.records.find((item) => item.kind === 'jobforge.scan.url');
+  assert.ok(record);
+  assert.equal(record.value, 'Acme - Staff Engineer');
+  assert.equal(record.fields.title, 'Staff Engineer');
+  assert.equal(record.fields.country_code, 'US');
+  assert.equal(record.fields.region, 'us_west');
+  assert.equal(record.fields.location_status, 'eligible');
+});
diff --git a/test/portal-diversity.test.mjs b/test/portal-diversity.test.mjs
new file mode 100644
index 0000000..552351b
--- /dev/null
+++ b/test/portal-diversity.test.mjs
@@ -0,0 +1,290 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const validator = join(root, 'scripts/verify-portal-diversity.mjs');
+const template = join(root, 'templates/portals.example.yml');
+
+function run(path) {
+  return spawnSync(process.execPath, [validator, path], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+}
+
+function runWithProfile(portalsPath, profile) {
+  const dir = mkdtempSync(join(tmpdir(), 'jobforge-profile-policy-'));
+  try {
+    const configDir = join(dir, 'config');
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(join(configDir, 'profile.yml'), profile);
+    return spawnSync(
+      process.execPath,
+      [validator, portalsPath, '--profile', 'config/profile.yml'],
+      {
+        cwd: root,
+        encoding: 'utf8',
+        env: { ...process.env, JOB_FORGE_PROJECT: dir },
+      },
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const validProfilePolicy = `location:
+  country: United States
+  eligible_work_country_codes: [US]
+  preferred_region_ids:
+    - us_northeast
+    - us_midwest
+    - us_south
+    - us_west
+    - us_nationwide
+  remote:
+    enabled: true
+    allowed_region_ids: [us_northeast, us_midwest, us_south, us_west, us_nationwide]
+    require_explicit_location_eligibility: true
+  include_exploratory_regions: false
+  willing_to_relocate: false
+`;
+
+function withMutatedTemplate(mutate, assertion) {
+  const dir = mkdtempSync(join(tmpdir(), 'jobforge-diversity-'));
+  try {
+    const path = join(dir, 'portals.yml');
+    writeFileSync(path, mutate(readFileSync(template, 'utf8')));
+    assertion(run(path));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('real portal template has feasible US-only source coverage', () => {
+  const result = run(template);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /Portal diversity check: 5 regions/);
+  assert.doesNotMatch(result.stderr, /tags cover .*enabled catalog entries/);
+});
+
+test('policy parsing does not depend on distributable section comments', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(/^# -- .+ --\n/gm, ''),
+    (result) => assert.equal(result.status, 0, result.stderr || result.stdout),
+  );
+});
+
+test('a consumer profile with explicit US scan constraints passes', () => {
+  const result = runWithProfile(template, validProfilePolicy);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /profile scan policy: explicit US-only constraints/);
+});
+
+test('a legacy consumer profile fails closed with non-destructive upgrade guidance', () => {
+  const result = runWithProfile(template, `location:\n  country: United States\n  city: Boston\n`);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /location\.eligible_work_country_codes is missing/);
+  assert.match(result.stderr, /JobForge left your personal YAML unchanged/);
+  assert.match(result.stderr, /Scanning must stop before any network request/);
+});
+
+test('additional truthful work authorizations do not broaden US-only discovery', () => {
+  const result = runWithProfile(
+    template,
+    validProfilePolicy.replace('eligible_work_country_codes: [US]', 'eligible_work_country_codes: [US, CA]'),
+  );
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+});
+
+test('profile work eligibility must include the US', () => {
+  const result = runWithProfile(
+    template,
+    validProfilePolicy.replace('eligible_work_country_codes: [US]', 'eligible_work_country_codes: [CA]'),
+  );
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /eligible_work_country_codes must include US/);
+});
+
+test('profile region ids must exist in the personal portal policy', () => {
+  const result = runWithProfile(
+    template,
+    validProfilePolicy.replace('preferred_region_ids:', 'preferred_region_ids: [us_northeast, europe]\n  unused_regions:'),
+  );
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /preferred_region_ids references unknown portal region ids: europe/);
+});
+
+test('unknown coverage region fails validation', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('coverage_regions: [us_northeast]', 'coverage_regions: [unknown_region]'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /unknown id "unknown_region"/);
+    },
+  );
+});
+
+test('a legacy portal file without diversity_policy fails with merge guidance', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(/diversity_policy:[\s\S]*?# -- Search queries --/, '# -- Search queries --'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /portals\.yml is missing diversity_policy/);
+      assert.match(result.stderr, /merge diversity_policy and the five "Coverage — US/);
+      assert.match(result.stderr, /left your personal YAML unchanged/);
+    },
+  );
+});
+
+test('the distributable policy requires all five US coverage buckets', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replaceAll('us_midwest', 'us_central'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /must define the five US coverage buckets/);
+    },
+  );
+});
+
+test('disabled regional query does not satisfy its minimum', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(
+      /(coverage_regions: \[us_midwest\]\n\s+)enabled: true/g,
+      '$1enabled: false',
+    ),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /us_midwest: 0 enabled coverage queries; requires [1-9]/);
+    },
+  );
+});
+
+test('eligibility-first cannot be disabled', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('eligibility_first: true', 'eligibility_first: false'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /eligibility_first must be true/);
+    },
+  );
+});
+
+test('unknown locations must be excluded in the US-only template', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('unknown_location: exclude', 'unknown_location: review'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /unknown_location must be exclude for US-only discovery/);
+    },
+  );
+});
+
+test('generic queries require an explicit US location constraint', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(/  search_location_constraint:.*\n/, ''),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /search_location_constraint must explicitly constrain queries to the United States/);
+    },
+  );
+});
+
+test('explicitly European boards stay disabled in the US-only template', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(
+      /(- name: Landing\.jobs — Engineering[\s\S]*?enabled:) false/,
+      '$1 true',
+    ),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /explicitly non-US board landing\.jobs must be disabled/);
+    },
+  );
+});
+
+test('enabled WWR feeds permit only the explicit USA Only region', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(
+      'allowed_values: ["USA Only"]',
+      'allowed_values: ["USA Only", "Anywhere in the World"]',
+    ),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /WeWorkRemotely allowed_values must be \["USA Only"\]/);
+    },
+  );
+});
+
+test('enabled global feeds fail closed when location metadata is missing', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('on_missing: exclude', 'on_missing: review'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /missing and ambiguous feed locations must be excluded/);
+    },
+  );
+});
+
+test('RemoteOK prefilters its structured location field', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace(
+      'source_field: location\n      country_codes: [US]',
+      'source_field: description\n      country_codes: [US]',
+    ),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /RemoteOK location_filter\.source_field must be location/);
+    },
+  );
+});
+
+test('impossible regional targets fail validation', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('shortlist_size: 30', 'shortlist_size: 5'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /regional target_minimum_results total \d+ exceeds shortlist_size 5/);
+    },
+  );
+});
+
+test('non-US country codes fail validation', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('country_codes: [US]', 'country_codes: [US, CA]'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /country_codes must be \[US\] for US-only discovery/);
+    },
+  );
+});
+
+test('the shared source pool must use the US catalog tag', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('source_company_tags: [us]', 'source_company_tags: [canada]'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /source_company_tags must be \[us\] for the US source pool/);
+    },
+  );
+});
+
+test('the rotating source budget must be able to satisfy the company floor', () => {
+  withMutatedTemplate(
+    (yaml) => yaml.replace('tracked_company_scan_budget: 60', 'tracked_company_scan_budget: 7'),
+    (result) => {
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /tracked_company_scan_budget cannot be lower than minimum_distinct_companies/);
+    },
+  );
+});
+
+test('missing portal file fails cleanly', () => {
+  const result = run(join(root, 'does-not-exist.yml'));
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /portal configuration not found/);
+});
diff --git a/test/preflight-us.test.mjs b/test/preflight-us.test.mjs
new file mode 100644
index 0000000..0084f24
--- /dev/null
+++ b/test/preflight-us.test.mjs
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { planJobForgePreflight, withUsLocationGate } from '../lib/jobforge-preflight.mjs';
+
+function sourced(value, source = 'reports/001-acme.md:1') {
+  return { value, source };
+}
+
+function candidate(overrides = {}) {
+  return {
+    facts: {
+      id: sourced('job-1'),
+      company: sourced('Acme'),
+      role: sourced('Staff Engineer'),
+      companyRoleKey: sourced('company-role:acme:staff-engineer'),
+      url: sourced('https://jobs.example.com/1'),
+      score: sourced(4.2),
+      country_code: sourced('US'),
+      region: sourced('us_northeast'),
+      location_status: sourced('eligible'),
+      ...overrides,
+    },
+    gates: [{ id: 'duplicate', status: 'pass', source: '.jobforge-index.json' }],
+  };
+}
+
+test('US-eligible preflight candidate is ready', () => {
+  const result = planJobForgePreflight({ candidates: [candidate()] });
+  assert.equal(result.ok, true);
+  assert.equal(result.totals.ready, 1);
+  assert.equal(result.ready[0].gates.find((gate) => gate.id === 'us-location')?.status, 'pass');
+});
+
+test('non-US country is blocked even when the score and status pass', () => {
+  const result = planJobForgePreflight({
+    candidates: [candidate({ country_code: sourced('DE') })],
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.totals.blocked, 1);
+  assert.match(result.blocked[0].issues[0].message, /country_code is DE, not US/);
+});
+
+test('unknown region or ambiguous status materializes a blocking gate', () => {
+  const gated = withUsLocationGate({
+    candidates: [candidate({ region: sourced('europe'), location_status: sourced('location_review') })],
+  });
+  const gate = gated.candidates[0].gates.find((item) => item.id === 'us-location');
+  assert.equal(gate.status, 'block');
+  assert.match(gate.reason, /not a configured US bucket/);
+  assert.match(gate.reason, /not eligible/);
+});
+
+test('custom configured US bucket can pass the application gate', () => {
+  const gated = withUsLocationGate(
+    { candidates: [candidate({ region: sourced('us_great_lakes') })] },
+    { regionIds: ['us_great_lakes'] },
+  );
+  const gate = gated.candidates[0].gates.find((item) => item.id === 'us-location');
+  assert.equal(gate.status, 'pass');
+});
diff --git a/test/scan-balance.test.mjs b/test/scan-balance.test.mjs
new file mode 100644
index 0000000..91ee57e
--- /dev/null
+++ b/test/scan-balance.test.mjs
@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { balanceCandidates, parseDiversityPolicy } from '../scripts/balance-scan-results.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const policy = {
+  unknownLocation: 'exclude',
+  shortlistSize: 10,
+  maxResultsPerCompany: 2,
+  maxRegionShare: 0.4,
+  minimumDistinctCompanies: 6,
+  regions: [
+    { id: 'us_northeast', targetMinimumResults: 1, targetMinimumDistinctCompanies: 1 },
+    { id: 'us_midwest', targetMinimumResults: 1, targetMinimumDistinctCompanies: 1 },
+    { id: 'us_south', targetMinimumResults: 1, targetMinimumDistinctCompanies: 1 },
+    { id: 'us_west', targetMinimumResults: 1, targetMinimumDistinctCompanies: 1 },
+    { id: 'us_nationwide', targetMinimumResults: 1, targetMinimumDistinctCompanies: 1 },
+  ],
+};
+
+function candidate(company, score, suffix = '', region = 'us_northeast') {
+  return {
+    company,
+    title: `Engineer ${suffix || company}`,
+    url: `https://jobs.example/${encodeURIComponent(company)}-${region}-${suffix || score}`,
+    country_code: 'US',
+    region,
+    location_status: 'eligible',
+    relevance_score: score,
+  };
+}
+
+test('US location floors and company diversity survive a much larger Northeast pool', () => {
+  const candidates = [
+    ...Array.from({ length: 10 }, (_, index) => candidate(`Northeast ${index}`, 100 - index)),
+    candidate('Midwest A', 70, 'one', 'us_midwest'),
+    candidate('Midwest B', 69, 'two', 'us_midwest'),
+    candidate('South A', 68, 'one', 'us_south'),
+    candidate('South B', 67, 'two', 'us_south'),
+    candidate('West A', 66, 'one', 'us_west'),
+    candidate('West B', 65, 'two', 'us_west'),
+    candidate('Remote A', 64, 'one', 'us_nationwide'),
+    candidate('Remote B', 63, 'two', 'us_nationwide'),
+  ];
+  const result = balanceCandidates(candidates, policy);
+  assert.equal(result.selected.length, 10);
+  assert.ok(result.summary.distinct_companies >= 6);
+  for (const region of policy.regions) {
+    assert.ok(result.summary.coverage[region.id].results >= 1, `${region.id} should be represented`);
+  }
+  assert.deepEqual(result.summary.gaps, []);
+});
+
+test('the per-company cap prevents one employer from dominating the shortlist', () => {
+  const candidates = [
+    ...Array.from({ length: 6 }, (_, index) => candidate('Large Co', 100 - index, `role-${index}`)),
+    candidate('Company B', 70),
+    candidate('Company C', 69),
+    candidate('Company D', 68),
+    candidate('Company E', 67),
+    candidate('Company F', 66),
+    candidate('Company G', 65),
+  ];
+  const result = balanceCandidates(candidates, policy);
+  assert.equal(result.selected.filter((row) => row.company === 'Large Co').length, 2);
+});
+
+test('the overall company floor is filled before extra roles from represented companies', () => {
+  const companyFloorPolicy = {
+    ...policy,
+    maxResultsPerCompany: 10,
+  };
+  const candidates = [
+    candidate('Company A', 100, 'ne', 'us_northeast'),
+    candidate('Company B', 99, 'mw', 'us_midwest'),
+    candidate('Company A', 98, 'south', 'us_south'),
+    candidate('Company B', 97, 'west', 'us_west'),
+    candidate('Company A', 96, 'national', 'us_nationwide'),
+    candidate('Company A', 90, 'extra-a'),
+    candidate('Company B', 89, 'extra-b'),
+    ...['C', 'D', 'E', 'F', 'G', 'H'].map((name, index) => candidate(`Company ${name}`, 20 - index, `unique-${name}`)),
+  ];
+  const result = balanceCandidates(candidates, companyFloorPolicy);
+  assert.ok(result.summary.distinct_companies >= companyFloorPolicy.minimumDistinctCompanies);
+});
+
+test('non-US and ambiguous locations are excluded rather than reviewed', () => {
+  const review = { ...candidate('Review Co', 99), location_status: 'location_review' };
+  const exploratory = { ...candidate('Explore Co', 98), location_status: 'exploratory' };
+  const missingStatus = { ...candidate('Unknown Co', 97) };
+  delete missingStatus.location_status;
+  const nonUs = { ...candidate('Canada Co', 96), country_code: 'CA' };
+  const missingCountry = candidate('No Country Co', 95);
+  delete missingCountry.country_code;
+  const ineligible = { ...candidate('No Co', 94), location_status: 'ineligible' };
+  const eligible = candidate('Yes Co', 50);
+  const result = balanceCandidates([review, exploratory, missingStatus, nonUs, missingCountry, ineligible, eligible], policy);
+  assert.deepEqual(result.selected.map((row) => row.company), ['Yes Co']);
+  assert.deepEqual(result.review, []);
+  assert.deepEqual(
+    new Set(result.excluded.map((row) => row.company)),
+    new Set(['Review Co', 'Explore Co', 'Unknown Co', 'Canada Co', 'No Country Co', 'No Co']),
+  );
+});
+
+test('company cap and exact duplicate protection are deterministic', () => {
+  const first = candidate('One Co', 90, 'one');
+  const duplicate = { ...first, relevance_score: 1 };
+  const candidates = [
+    first,
+    duplicate,
+    candidate('One Co', 80, 'two'),
+    candidate('One Co', 70, 'three'),
+    candidate('Other Co', 60),
+  ];
+  const result = balanceCandidates(candidates, policy);
+  assert.equal(result.selected.filter((row) => row.company === 'One Co').length, 2);
+  assert.equal(new Set(result.selected.map((row) => row.url)).size, result.selected.length);
+});
+
+test('real YAML policy parses into the runtime balancer', () => {
+  const yaml = readFileSync(resolve(root, 'templates/portals.example.yml'), 'utf8');
+  const parsed = parseDiversityPolicy(yaml);
+  assert.equal(parsed.unknownLocation, 'exclude');
+  assert.equal(parsed.regions.length, 5);
+  assert.deepEqual(
+    parsed.regions.map((region) => region.id),
+    ['us_northeast', 'us_midwest', 'us_south', 'us_west', 'us_nationwide'],
+  );
+  assert.equal(parsed.shortlistSize, 30);
+  assert.equal(parsed.maxResultsPerCompany, 3);
+});
+
+test('runtime policy parser does not depend on section comments', () => {
+  const yaml = readFileSync(resolve(root, 'templates/portals.example.yml'), 'utf8')
+    .replace(/^# -- .+ --\n/gm, '');
+  const parsed = parseDiversityPolicy(yaml);
+  assert.equal(parsed.regions.length, 5);
+  assert.equal(parsed.unknownLocation, 'exclude');
+});
diff --git a/test/scan-history.test.mjs b/test/scan-history.test.mjs
new file mode 100644
index 0000000..75a69b7
--- /dev/null
+++ b/test/scan-history.test.mjs
@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { scanHistoryDates } from '../lib/jobforge-timeline.mjs';
+
+test('scan history dates support canonical URL-first and legacy date-first rows', (t) => {
+  const projectDir = mkdtempSync(join(tmpdir(), 'jobforge-scan-history-'));
+  t.after(() => rmSync(projectDir, { recursive: true, force: true }));
+  mkdirSync(join(projectDir, 'data'));
+  writeFileSync(
+    join(projectDir, 'data', 'scan-history.tsv'),
+    [
+      'https://example.test/new\t2026-07-17\tGreenhouse\tEngineer\tAcme\tadded\tRemote - US\tUS\tus_nationwide\teligible\t-',
+      '2026-07-16\tLegacy Co\tLegacy Role\thttps://example.test/legacy\tgreenhouse\tadded',
+      '',
+    ].join('\n'),
+  );
+
+  const dates = scanHistoryDates(projectDir);
+  assert.equal(dates.get('https://example.test/new'), '2026-07-17');
+  assert.equal(dates.get('https://example.test/legacy'), '2026-07-16');
+});

From fea3eb5fc3730ac78b1baebf3e3ed211cd26a550 Mon Sep 17 00:00:00 2001
From: Charlie Greenman <charlie@razroo.com>
Date: Fri, 17 Jul 2026 12:06:23 -0400
Subject: [PATCH 2/2] chore(release): v2.14.49

---
 package-lock.json | 26 +++++++++++++-------------
 package.json      |  2 +-
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 078f940..d791a4f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "job-forge",
-  "version": "2.14.48",
+  "version": "2.14.49",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "job-forge",
-      "version": "2.14.48",
+      "version": "2.14.49",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -1356,17 +1356,17 @@
       }
     },
     "node_modules/form-data": {
-      "version": "4.0.5",
-      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
-      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+      "version": "4.0.6",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.6.tgz",
+      "integrity": "sha512-vKatAh4SlVfgbv+YtmhiRjhEMJsYpsG1Y2rMQtR+SVSbytsSD1YGzDIcrAJmdFec88u/+VoGmxnl+80gL1tRCQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "asynckit": "^0.4.0",
         "combined-stream": "^1.0.8",
         "es-set-tostringtag": "^2.1.0",
-        "hasown": "^2.0.2",
-        "mime-types": "^2.1.12"
+        "hasown": "^2.0.4",
+        "mime-types": "^2.1.35"
       },
       "engines": {
         "node": ">= 6"
@@ -1524,9 +1524,9 @@
       }
     },
     "node_modules/hasown": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
-      "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
+      "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
       "license": "MIT",
       "dependencies": {
         "function-bind": "^1.1.2"
@@ -1536,9 +1536,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.23",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.23.tgz",
-      "integrity": "sha512-eIaZ9qDgu7XV0pxOCrg7/WhnQ6Ivm22UcxhXx/A3dcbqbbYgBEkc6e/J/s7j2tS96zoB0S9VBdLwQNCWwUo4LA==",
+      "version": "4.12.30",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.30.tgz",
+      "integrity": "sha512-emn+JoJjrN9YTpRDS5it/UI2SO9BAE37T6I3d963RxcZ81G9A4pr2SZTEiiaiKbzx+NKRg5BZ89fCL7gCJCUog==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
diff --git a/package.json b/package.json
index d7215d5..a946695 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.48",
+  "version": "2.14.49",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {