job-forge 2.14.41 → 2.14.43

package/.cursor/rules/main.mdc

@@ -33,8 +33,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, emitted score JSON validated by `npx job-forge score:check --input ...`, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, materialized fact records returned by `npx job-forge facts:query ...`, selected next actions returned by `npx job-forge prioritize:select ...`, and lineage records returned by `npx job-forge lineage:explain ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
-- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
-  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`, which belongs with JobForge portal sessions instead of stock Playwright Chromium
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
 ## Defaults
 
@@ -67,7 +67,7 @@ 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/stealth prompt hygiene [H8].
+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/stealth prompt hygiene [H8].
 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].

package/.opencode/skills/job-forge.md

@@ -231,7 +231,8 @@ Step 5  — Loop in rounds of 2 (Hard Limit #1)
     pair = candidates[round*2 : round*2 + 2]
     # If proxy is configured, do not paste proxy values into prompts.
     # Say: "Proxy is configured; read config/profile.yml and pass its
-    # top-level proxy object plus stealth: true to every geometra_connect call."
+    # top-level proxy object plus headless: true and stealth: true to every
+    # Geometra connect or auto-connect call."
     # Dispatch 1 or 2 task() calls in ONE message (never 3+)
     task(subagent_type=<tier per AGENTS.md routing>, prompt=<apply prompt for pair[0]>)
     task(subagent_type=<tier>, prompt=<apply prompt for pair[1]>)  # only if pair has 2

package/AGENTS.md

@@ -28,8 +28,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, emitted score JSON validated by `npx job-forge score:check --input ...`, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, materialized fact records returned by `npx job-forge facts:query ...`, selected next actions returned by `npx job-forge prioritize:select ...`, and lineage records returned by `npx job-forge lineage:explain ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
-- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
-  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`, which belongs with JobForge portal sessions instead of stock Playwright Chromium
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
 ## Defaults
 
@@ -62,7 +62,7 @@ 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/stealth prompt hygiene [H8].
+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/stealth prompt hygiene [H8].
 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].

package/CLAUDE.md

@@ -28,8 +28,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, emitted score JSON validated by `npx job-forge score:check --input ...`, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, materialized fact records returned by `npx job-forge facts:query ...`, selected next actions returned by `npx job-forge prioritize:select ...`, and lineage records returned by `npx job-forge lineage:explain ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
-- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
-  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`, which belongs with JobForge portal sessions instead of stock Playwright Chromium
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
 ## Defaults
 
@@ -62,7 +62,7 @@ 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/stealth prompt hygiene [H8].
+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/stealth prompt hygiene [H8].
 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].

package/bin/create-job-forge.mjs

@@ -110,6 +110,9 @@ const consumerPkg = {
     tokens: 'job-forge tokens',
     'tokens:today': 'job-forge tokens --days 1',
     'tokens:log': 'job-forge tokens --days 1 --append',
+    'portal:snapshot': 'job-forge portal:snapshot',
+    'portal:form-schema': 'job-forge portal:form-schema',
+    'portal:explain': 'job-forge portal:explain',
     'trace:list': 'job-forge trace:list',
     'trace:stats': 'job-forge trace:stats',
     'trace:show': 'job-forge trace:show',

package/bin/geometra-mcp-launcher.mjs

@@ -5,7 +5,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const DEFAULT_FALLBACK_PACKAGE = '@geometra/mcp@1.61.3';
+const DEFAULT_FALLBACK_PACKAGE = '@geometra/mcp@1.62.1';
 const RESOLVE_ONLY_FLAG = '--job-forge-resolve-target';
 
 function normalizeEnv(value) {

package/bin/job-forge.mjs

@@ -17,6 +17,7 @@
  *   pdf            Run generate-pdf.mjs
  *   sync-check     Run cv-sync-check.mjs
  *   mcp:geometra   Launch Geometra MCP via JobForge's local/npm resolver
+ *   portal:*       One-shot direct-Geometra browser snapshots/form schemas
  *   tokens         Run scripts/token-usage-report.mjs
  *   trace:*        Inspect local agent transcripts via iso-trace
  *   telemetry:*    Summarize JobForge pipeline status from traces + tracker files
@@ -91,6 +92,12 @@ const guardAliases = {
   'guard:explain': 'explain',
 };
 
+const portalAliases = {
+  'portal:snapshot': 'snapshot',
+  'portal:form-schema': 'form-schema',
+  'portal:explain': 'explain',
+};
+
 const ledgerAliases = {
   'ledger:status': 'status',
   'ledger:rebuild': 'rebuild',
@@ -247,6 +254,9 @@ Commands:
   pdf            Generate ATS-optimized CV PDF from cv.md
   sync-check     Lint: verify cv.md and profile.yml are filled in
   mcp:geometra   Launch Geometra MCP, preferring local JobForge/Geometra dev wiring
+  portal:snapshot      Render a URL with direct Geometra and print page model/snapshot
+  portal:form-schema   Render a URL with direct Geometra and print form schema
+  portal:explain       Show direct Geometra module/defaults
   tokens         Show opencode token usage and cost by session/day
   trace          Pass through to iso-trace (e.g. job-forge trace sources)
   trace:list     List recent local agent sessions (defaults: --since 7d --cwd project)
@@ -354,6 +364,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge telemetry:show ses_...
   job-forge guard:audit
   job-forge guard:explain
+  job-forge portal:snapshot --url https://example.test/jobs/123 --json
+  job-forge portal:form-schema --url https://example.test/apply --json
   job-forge ledger:has --company "Acme" --role "Staff Engineer" --status Applied
   job-forge capabilities:explain general-free
   job-forge capabilities:check general-free --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write
@@ -438,6 +450,21 @@ if (cmd === 'guard' || guardAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'portal' || portalAliases[cmd]) {
+  const portalArgs = cmd === 'portal'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [portalAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/portal.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...portalArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 if (cmd === 'ledger' || ledgerAliases[cmd]) {
   const ledgerArgs = cmd === 'ledger'
     ? (rest.length === 0 ? ['help'] : rest)

package/config/profile.example.yml

@@ -92,17 +92,18 @@ location_constraints:
 # mobile / SOCKS proxy you already pay for. Bypasses the datacenter-IP
 # fingerprinting that drives ~80-90% of Ashby / Lever / Cloudflare-fronted
 # "flagged as possible spam" submit failures in headless mode. JobForge passes
-# `stealth: true` by default so Geometra MCP >= 1.61.3 launches CloakBrowser's
-# patched Chromium for portal sessions.
+# `headless: true` and `stealth: true` by default so Geometra MCP >= 1.61.3
+# launches CloakBrowser's patched Chromium for portal sessions without opening
+# visible browser windows.
 #
 # BYO — JobForge does NOT bundle or resell proxy bandwidth. Pick a residential
 # or mobile provider (Bright Data, Oxylabs, SOAX, Smartproxy, etc.), or a
 # mobile hotspot, or your own SOCKS relay. Required: Geometra MCP >= 1.61.3.
 #
 # When present, the apply / scan / auto-pipeline modes thread this into every
-# `geometra_connect` call as `proxy: {...}` alongside `stealth: true`. Pool is
-# partitioned by proxy identity and stealth mode so direct and proxied sessions
-# never share a Chromium.
+# `geometra_connect` call as `proxy: {...}` alongside `headless: true` and
+# `stealth: true`. Pool is partitioned by proxy identity and stealth mode so
+# direct and proxied sessions never share a Chromium.
 #
 # proxy:
 #   server: "http://residential.example.com:8080"   # http://, https://, or socks5://

package/docs/ARCHITECTURE.md

@@ -115,7 +115,7 @@ For customization (archetypes, weights, tone), start with `_shared.md` and [CUST
 ## Evaluation Flow (Single Offer)
 
 1. **Input**: User pastes JD text or URL
-2. **Extract**: Geometra MCP/WebFetch extracts JD from URL
+2. **Extract**: `job-forge portal:*`, Geometra MCP, or WebFetch extracts JD/form context from URL
 3. **Classify**: Detect archetype (one row from the archetype table in `modes/_shared.md`)
 4. **Evaluate**: 6 blocks (A-F).
    - A: Role summary.
@@ -251,6 +251,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `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 |
 | `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@agent-pattern-labs/iso-guard` policy audits over local normalized traces (with OpenCode `task` rules still available where relevant) |
+| `scripts/portal.mjs` | `npx job-forge portal:snapshot` / `portal:form-schema` | Deterministic direct-Geometra one-shot browser snapshots and form schemas with JobForge browser defaults enforced in code |
 | `scripts/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@agent-pattern-labs/iso-ledger` state over tracker, TSV, and pipeline files |
 | `scripts/capabilities.mjs` | `npx job-forge capabilities:check` / `capabilities:explain` | Deterministic `@agent-pattern-labs/iso-capabilities` role boundary checks for tools, MCPs, commands, filesystem, and network access |
 | `scripts/cache.mjs` | `npx job-forge cache:has` / `cache:get` / `cache:put` | Deterministic `@agent-pattern-labs/iso-cache` JD and artifact reuse keyed by stable job/url inputs |

package/docs/SETUP.md

@@ -214,7 +214,7 @@ Use it to identify which sessions or models are consuming the most tokens. The `
 `sync-check` requires `cv.md` and `config/profile.yml` with the fields checked in `cv-sync-check.mjs`. Until you finish the profile and CV steps, that is normal.
 
 **PDF generation fails**  
-The scaffolded `opencode.json` already registers Geometra MCP; if it's not running, check `opencode mcp list` and verify the scaffolded config under the `mcp.geometra` key — its `command` MUST be `["npx", "--no-install", "job-forge", "mcp:geometra"]`, `enabled: true`, and its `environment` should include `GEOMETRA_STEALTH=1` (or equivalently `GEOMETRA_BROWSER=stealth`) so proxy-backed portal sessions default to CloakBrowser's patched Chromium. `job-forge mcp:geometra` resolves Geometra in this order: `JOB_FORGE_GEOMETRA_MCP_PATH`, then a consumer-project override from `package.json -> jobForge.geometraMcpPath`, then `opencode.json -> mcp.geometra.environment.JOB_FORGE_GEOMETRA_MCP_PATH`, then a sibling `../geometra/mcp/dist/index.js` checkout for local JobForge development, and finally the pinned npm package. Geometra manages Chromium via its built-in proxy. JobForge still passes `stealth: true` for portal sessions explicitly; the env block keeps the default aligned for auto-spawned sessions and local debugging. For standalone CLI usage (outside opencode), `generate-pdf.mjs` also works with standalone Playwright/Chromium — install with `npx playwright install chromium`.
+The scaffolded `opencode.json` already registers Geometra MCP; if it's not running, check `opencode mcp list` and verify the scaffolded config under the `mcp.geometra` key — its `command` MUST be `["npx", "--no-install", "job-forge", "mcp:geometra"]`, `enabled: true`, and its `environment` should include `GEOMETRA_STEALTH=1` (or equivalently `GEOMETRA_BROWSER=stealth`) so proxy-backed portal sessions default to CloakBrowser's patched Chromium. `job-forge mcp:geometra` resolves Geometra in this order: `JOB_FORGE_GEOMETRA_MCP_PATH`, then a consumer-project override from `package.json -> jobForge.geometraMcpPath`, then `opencode.json -> mcp.geometra.environment.JOB_FORGE_GEOMETRA_MCP_PATH`, then a sibling `../geometra/mcp/dist/index.js` checkout for local JobForge development, and finally the pinned npm package. Geometra manages Chromium via its built-in proxy. JobForge still passes `headless: true` and `stealth: true` for portal sessions explicitly; the env block keeps the default aligned for auto-spawned sessions and local debugging. For standalone CLI usage (outside opencode), `generate-pdf.mjs` also works with standalone Playwright/Chromium — install with `npx playwright install chromium`.
 
 For consumer projects that should always use a local Geometra checkout across Opencode, Codex, Cursor, and Claude, prefer a local `package.json` override instead of editing symlinked MCP configs:
 

package/iso/commands/job-forge.md

@@ -234,7 +234,8 @@ Step 5  — Loop in rounds of 2 (Hard Limit #1)
     pair = candidates[round*2 : round*2 + 2]
     # If proxy is configured, do not paste proxy values into prompts.
     # Say: "Proxy is configured; read config/profile.yml and pass its
-    # top-level proxy object plus stealth: true to every geometra_connect call."
+    # top-level proxy object plus headless: true and stealth: true to every
+    # Geometra connect or auto-connect call."
     # Dispatch 1 or 2 task() calls in ONE message (never 3+)
     task(subagent_type=<tier per AGENTS.md routing>, prompt=<apply prompt for pair[0]>)
     task(subagent_type=<tier>, prompt=<apply prompt for pair[1]>)  # only if pair has 2

package/iso/instructions.md

@@ -28,8 +28,8 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [H7] Load-bearing facts passed to downstream subagents must originate from a file, not from prior subagent prose. Authoritative sources: `data/pipeline.md`, `data/scan-history.tsv`, `batch/scan-output-*.md`, `reports/{num}-*.md` with `**URL:**` / `**Score:**` headers, emitted score JSON validated by `npx job-forge score:check --input ...`, `batch/tracker-additions/*.tsv`, cached JD content returned by `npx job-forge cache:get --url ...`, source path/line pointers returned by `npx job-forge index:query ...`, materialized fact records returned by `npx job-forge facts:query ...`, selected next actions returned by `npx job-forge prioritize:select ...`, and lineage records returned by `npx job-forge lineage:explain ...`.
   why: 2026-04-18 scan subagent returned 30 fabricated Greenhouse IDs in prose (plausible-looking, non-existent); orchestrator dispatched 30 downstream subagents that all 404'd. Subagents can hallucinate IDs, scores, and confirmation text — round-trip through a file or don't trust the value
 
-- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
-  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`, which belongs with JobForge portal sessions instead of stock Playwright Chromium
+- [H8] Never paste proxy values from `config/profile.yml` into `task` prompts, status text, or summaries. If a proxy is configured, tell the subagent exactly: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `headless: true` and `stealth: true` to every `geometra_connect` call and every Geometra auto-connect call that passes `pageUrl` or `url`." Do not transcribe `server`, `username`, `password`, or `bypass`, even if you just read them from disk.
+  why: a 2026-04-25 OpenCode trace showed raw proxy credentials copied into an apply subagent prompt; trace logs are local, but prompts must still avoid replicating secrets across subagent sessions. Geometra MCP opens visible Chromium unless `headless: true` is explicit, and Geometra MCP >=1.61.3 can launch CloakBrowser stealth Chromium via `stealth: true`; both flags belong with JobForge portal sessions instead of stock visible Playwright Chromium
 
 ## Defaults
 
@@ -62,7 +62,7 @@ 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/stealth prompt hygiene [H8].
+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/stealth prompt hygiene [H8].
 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].

package/modes/apply.md

@@ -42,8 +42,8 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 - [D6] Use `fieldLabel` over `fieldId` everywhere it works.
   why: labels are stable across DOM refreshes; IDs are regenerated
 
-- [D7] If the orchestrator says a proxy is configured, read the top-level `proxy:` block from `config/profile.yml` and pass that object plus `stealth: true` into every `geometra_connect` call — including Call 3 of the recovery sequence. If the task prompt includes a legacy inline `proxy` object, pass it through and still set `stealth: true`, but do not echo credentials in status text. If absent, run with `stealth: true` and no proxy; never invent a proxy URL.
-  why: class-B Ashby / Cloudflare-fronted portals need a residential outbound IP plus a stealth Chromium fingerprint. Geometra MCP v1.59.0 added proxy plumbing, and v1.61.3 added CloakBrowser stealth Chromium via `stealth: true`; the orchestrator owns the config pipe. See "BYO Residential Proxy" in modes/reference-portals.md.
+- [D7] If the orchestrator says a proxy is configured, read the top-level `proxy:` block from `config/profile.yml` and pass that object plus `headless: true` and `stealth: true` into every `geometra_connect` call — including Call 3 of the recovery sequence — and every Geometra auto-connect call that passes `pageUrl` or `url`. If the task prompt includes a legacy inline `proxy` object, pass it through and still set `headless: true` and `stealth: true`, but do not echo credentials in status text. If absent, run with `headless: true`, `stealth: true`, and no proxy; never invent a proxy URL.
+  why: class-B Ashby / Cloudflare-fronted portals need a residential outbound IP plus a stealth Chromium fingerprint, and Geometra opens visible Chromium unless `headless: true` is explicit. Geometra MCP v1.59.0 added proxy plumbing, and v1.61.3 added CloakBrowser stealth Chromium via `stealth: true`; the orchestrator owns the config pipe. See "BYO Residential Proxy" in modes/reference-portals.md.
 
 - [D8] Upgrade application routing to `@general-paid` when the offer score is ≥ 4.0/5, the user flags "top-tier", "dream job", or "high-stakes", or the candidate is late-stage/post-screen.
   why: high-stakes applications need the quality-sensitive prompt and medium reasoning budget even though OpenCode now routes both application tiers through DeepSeek V4 Flash by default
@@ -53,23 +53,24 @@ Live application assistant. Reads the active application form in Chrome (via Geo
 
 ## Procedure
 
-1. `geometra_connect` with `stealth: true` + `geometra_page_model`; thread `proxy` if present [D7]; no WebFetch [D5].
-2. If Geometra is unavailable, ask for screenshot or pasted text [D2].
-3. Extract company + role; Grep `reports/` for a matching evaluation.
-4. Load full report + Section G if present.
-5. Compare role on screen vs evaluated role [D3].
-6. If different, pause for the candidate's decision [D3].
-7. Before dispatch, run Geometra cleanup [H4] and location filter [D1].
-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 as ONE `run_actions` call [H1] using labels [D6] with `imeFriendly: true` [D4].
-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.
+1. `geometra_connect`: `headless: true`, `stealth: true`, `isolated: true` [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.
+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 as ONE `run_actions` call [H1] using labels [D6] with `imeFriendly: true` [D4].
+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.
 
 ## Routing
 
@@ -211,7 +212,7 @@ If a subagent fails, report it in the summary and let the user decide whether to
 
 ## Verify these requirements
 
-- **Best with Geometra MCP**: In visible proxy mode, the candidate sees the browser and opencode can interact with the page via `geometra_connect`, `geometra_form_schema`, and `geometra_fill_form`.
+- **Best with Geometra MCP**: In headless proxy mode, opencode can interact with the page via `geometra_connect`, `geometra_form_schema`, and `geometra_fill_form` without opening a visible browser window.
 - **Without Geometra**: the candidate shares a screenshot or pastes the questions manually.
 
 ## Run this workflow

package/modes/auto-pipeline.md

@@ -9,7 +9,7 @@ Fetch the JD content once. If the input is a **URL** (not pasted JD text), fetch
 **Pick exactly one method, in this priority order:**
 
 1. **Greenhouse JSON API (first try, if the URL is Greenhouse-backed):** If the pipeline.md entry carries `| gh={slug}/{id}` OR the URL host matches `*.greenhouse.io` / a known Greenhouse customer front-end (`*.pinterestcareers.com`, `okta.com/company/careers/opportunity/*`, `samsara.com/company/careers/roles/*`, `zoominfo.com/careers?gh_jid=*`, `collibra.com/.../?gh_jid=*`, `careers.toasttab.com/jobs?gh_jid=*`, `careers.airbnb.com/positions/*?gh_jid=*`, `coinbase.com/careers/positions/*?gh_jid=*`, `instacart.careers/job/?gh_jid=*`), extract `slug` and `id` and WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` is the authoritative JD. 404 = genuinely closed (mark CLOSED and stop). **OpenCode WebFetch compatibility:** do not pass `format: "json"`; omit `format` or use `format: "text"` and parse the returned JSON text. **If 200, STOP — do not fall back to Geometra or WebFetch of the front-end.** The API is faster, cheaper (no Geometra session), and never returns a bot-shell.
-2. **Geometra MCP:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `geometra_connect({ ..., stealth: true })` + `geometra_page_model` to render and read the JD. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
+2. **Direct Geometra helper:** Most non-Greenhouse job portals (Lever, Ashby, Workday) are SPAs. Use `npx job-forge portal:snapshot --url "{url}" --json` to render and read the page model/snapshot. This helper enforces `headless: true`, `stealth: true`, and `isolated: true` in code, reads `config/profile.yml` proxy config, and closes Chromium before exit. **If this returns non-empty JD text, STOP — do not WebFetch the same URL.**
 3. **WebFetch (only if Geometra is unavailable OR returned only a shell with no JD text):** For static pages (ZipRecruiter, WeLoveProduct, company career pages).
 4. **WebSearch (only if methods 1–3 all failed):** Search for the role title + company on secondary portals that index the JD in static HTML.
 
@@ -38,7 +38,7 @@ Execute the full `pdf` pipeline (read `modes/pdf.md`).
 
 Generate draft answers for the application form when the final score is >= 3.5. If the final score is >= 3.5 (per Canonical Scoring Model thresholds in `_shared.md`), generate draft answers for the application form:
 
-1. **Extract form questions**: Use Geometra MCP (`geometra_connect({ ..., stealth: true })` + `geometra_form_schema`) to discover all form fields. **Reuse the same `sessionId` from Step 0** when the apply URL is the same rendered page; only connect again if the prior session ended or the URL changed. If questions cannot be extracted, use the generic questions.
+1. **Extract form questions**: Prefer `npx job-forge portal:form-schema --url "{apply_url}" --json` to discover all form fields without leaving a browser open. Use Geometra MCP only when a live multi-step browser session already exists and must be reused. If questions cannot be extracted, use the generic questions.
 2. **Generate answers** following the tone guidelines (see below).
 3. **Save in the report** as a `## G) Draft Application Answers` section.
 

package/modes/pipeline.md

@@ -7,7 +7,7 @@ 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 Geometra MCP (`geometra_connect({ ..., stealth: true })` + geometra_page_model) → WebFetch → WebSearch
+   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 ✅/❌`
@@ -34,9 +34,10 @@ Processes accumulated job offer URLs from `data/pipeline.md`. The user adds URLs
 ## Detect JD From URL
 
 1. **Greenhouse JSON API (FIRST, when the entry has `| gh={slug}/{id}` OR the host looks Greenhouse-backed):** WebFetch `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs/{id}`. 200 + JSON with `content` = LIVE, use it as the JD; 404 = genuinely CLOSED (mark `- [!]` and continue). **OpenCode WebFetch compatibility:** do not pass `format: "json"`; omit `format` or use `format: "text"` and parse the returned JSON text. Bot-hostile customer fronts (`pinterestcareers.com`, `okta.com`, `samsara.com`, `zoominfo.com`, `collibra.com`, `careers.toasttab.com`, `careers.airbnb.com`, `coinbase.com`, `instacart.careers`, `careers.toasttab.com`) MUST be verified via this API first — WebFetch/Geometra of those domains returns a shell or 403 and causes false CLOSED marks.
-2. **Geometra MCP:** `geometra_connect({ ..., stealth: true })` + `geometra_page_model`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), uses fewer tokens than raw DOM snapshots.
-3. **WebFetch (fallback):** For static pages or when Geometra is not available.
-4. **WebSearch (last resort):** Search on secondary portals that index the JD.
+2. **Direct Geometra helper:** `npx job-forge portal:snapshot --url "{url}" --json`. Works with non-Greenhouse SPAs (Lever, Ashby, Workday), enforces `headless: true`, `stealth: true`, and `isolated: true` in code, reads `config/profile.yml` proxy config, and closes Chromium before exit.
+3. **Geometra MCP (interactive fallback):** Use only when the one-shot helper is not enough and a live multi-step browser session is required.
+4. **WebFetch (fallback):** For static pages or when Geometra is not available.
+5. **WebSearch (last resort):** Search on secondary portals that index the JD.
 
 **Special cases:**
 - **LinkedIn**: May require login → mark `[!]` and ask the user to paste the text
@@ -68,6 +69,7 @@ Step 1  — Read data/pipeline.md; collect "- [ ]" URLs into `pending = [url_1,
 Step 2  — Pre-flight cleanup (once, before loop):
             geometra_list_sessions()
             geometra_disconnect({ closeBrowser: true })
+            # portal:* helpers are direct-package one-shots and auto-close.
 Step 3  — For round in ceil(N/2):
             pair = pending[round*2 : round*2 + 2]
             # ONE message, 1 or 2 task() calls. Never 3.

package/modes/reference-geometra.md

@@ -50,7 +50,7 @@ These blocks come from two distinct root causes and require different responses:
 
 **Rule — do NOT loop retrying a class B block.** One retry with `imeFriendly: true` is the correct test for class A. If the same spam message fires after a clean `imeFriendly` refill, stop, mark Failed, move on. Repeated retries waste subagent time and do not change the outcome.
 
-**Class B fix — BYO residential proxy + stealth Chromium.** When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile. JobForge also passes `stealth: true` so Geometra MCP >=1.61.3 launches CloakBrowser's patched Chromium instead of stock Playwright Chromium. See the "BYO Residential Proxy" reference section below. Without a configured proxy, stealth still helps browser fingerprinting, but the outbound IP remains datacenter.
+**Class B fix — BYO residential proxy + headless stealth Chromium.** When the candidate has configured `proxy:` in `config/profile.yml`, every `geometra_connect` call threads that proxy through to Chromium, which flips the outbound IP from datacenter to residential/mobile. JobForge also passes `headless: true` and `stealth: true` so Geometra MCP runs without opening a visible browser and Geometra MCP >=1.61.3 launches CloakBrowser's patched Chromium instead of stock Playwright Chromium. See the "BYO Residential Proxy" reference section below. Without a configured proxy, stealth still helps browser fingerprinting, but the outbound IP remains datacenter.
 
 **Known-block Ashby tenants (2026-04-19 empirical observations).** These tenants fired class B on every attempted submit from a headless datacenter-IP proxy. Orchestrators planning apply dispatches should assume these tenants will Fail in headless — prioritize other portals, or skip same-tenant siblings after a confirmed class B to avoid burning subagent slots:
 
@@ -143,7 +143,7 @@ geometra_connect({ pageUrl: "https://...", isolated: true, headless: true, slowM
 
 **Wrong:** running `geometra_connect` without `isolated: true` when submitting multiple forms concurrently. The forms may share state and produce incorrect submissions.
 
-**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe. Keep `stealth: true` either way so JobForge uses Geometra's CloakBrowser Chromium path for portal sessions.
+**With a configured proxy,** add `proxy: { server, username?, password?, bypass? }` to the same call — see "BYO Residential Proxy" below. The reusable-proxy pool is partitioned by proxy identity, so mixing direct and proxied sessions across parallel rounds is safe. Keep `headless: true` and `stealth: true` either way so JobForge uses Geometra's CloakBrowser Chromium path for portal sessions without opening visible windows.
 
 ### Session Reuse — When Subagents Cannot Reach Existing Sessions
 

package/modes/reference-local-helpers.md

@@ -10,6 +10,7 @@ Prefer a local helper when the workflow needs:
 - Machine-readable artifact validation.
 - Context, capability, or migration policy.
 - Dispatch planning or settlement.
+- One-shot rendered browser snapshots or form schemas.
 - Scoring, timing, priority, or lineage decisions.
 - Safe export checks.
 
@@ -26,6 +27,7 @@ Do not paste whole helper outputs into prompts unless the downstream agent needs
 | Artifact contracts | `templates/contracts.json` | `npx job-forge tracker-line ... --write`; `npx job-forge verify` |
 | Role capability policy | `templates/capabilities.json` | `npx job-forge capabilities:*` |
 | Context bundle policy | `templates/context.json` | `npx job-forge context:*` |
+| Browser snapshots / form schemas | Direct `@geometra/mcp` session module | `npx job-forge portal:*` |
 | JD/artifact reuse | `.jobforge-cache/` | `npx job-forge cache:*` |
 | Artifact lookup | `.jobforge-index.json` from `templates/index.json` | `npx job-forge index:*` |
 | Source-backed facts | `.jobforge-facts.json` from `templates/facts.json` | `npx job-forge facts:*` |
@@ -49,6 +51,7 @@ Do not paste whole helper outputs into prompts unless the downstream agent needs
 - For generated reports or PDFs reused after input changes, run `lineage:check --artifact <file>` if lineage exists; after creating derived artifacts, record them with `lineage:record --artifact <file> --input <source>...`.
 - Before exporting traces, prompts, reports, or fixtures outside the project, run `redact:scan`, `redact:apply`, or `redact:verify`.
 - When diagnosing consumer harness drift, run `migrate:plan` or `migrate:check`; `job-forge sync` applies safe migrations automatically unless `JOB_FORGE_SKIP_MIGRATIONS=1` is set.
+- When you only need a rendered page model, compact snapshot, or form schema from one URL, prefer `portal:snapshot` / `portal:form-schema` over Geometra MCP tool calls. Use MCP for interactive multi-step browser sessions.
 
 ## Enforcement
 

package/modes/reference-portals.md

@@ -53,9 +53,9 @@ When a form says "enter the code we sent to your email", you MUST retrieve the c
 
 **Problem:** on 2026-04-19 cycle 4, 5/5 untested Ashby tenants and 100% of Dropbox-class Cloudflare-fronted portals fingerprint-blocked headless Chromium from datacenter IPs. `imeFriendly: true` fixes class A (React validation lag) but has zero effect on class B (environment fingerprint). There is no in-session software-only fix for class B: the server decided the session is a bot before the form response was rendered.
 
-**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for, and launch Geometra's CloakBrowser stealth Chromium with `stealth: true`. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser`; v1.61.3 added `stealth: true` for CloakBrowser. The outbound IP becomes residential/mobile, the browser fingerprint moves off stock Playwright Chromium, and the class-B checks have fewer signals to trip.
+**Fix:** route the spawned Chromium through a residential or mobile proxy the candidate already pays for, and launch Geometra's headless CloakBrowser stealth Chromium with `headless: true` and `stealth: true`. Geometra MCP v1.59.0 added a `proxy: { server, username?, password?, bypass? }` parameter on `geometra_connect` and `geometra_prepare_browser`; v1.61.3 added `stealth: true` for CloakBrowser. The outbound IP becomes residential/mobile, the browser fingerprint moves off stock Playwright Chromium, and the class-B checks have fewer signals to trip.
 
-**Proxy is opt-in, stealth is default.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge still passes `stealth: true`, but the outbound IP remains the machine or hosting environment running Chromium.
+**Proxy is opt-in; headless and stealth are default.** JobForge does NOT bundle or resell proxy bandwidth — the candidate brings their own provider (Bright Data, Oxylabs, SOAX, Smartproxy, mobile hotspot, self-hosted SOCKS). Without a configured proxy, JobForge still passes `headless: true` and `stealth: true`, but the outbound IP remains the machine or hosting environment running Chromium.
 
 ### Where the proxy config lives
 
@@ -76,15 +76,15 @@ See `config/profile.example.yml` for the commented-out template.
 **Orchestrator responsibilities:**
 
 1. On session start, read `config/profile.yml` once. If a `proxy:` block is present, remember that a proxy is configured, but do not paste username/password values into task prompts or user-visible status.
-2. When dispatching any subagent whose work involves a `geometra_connect` call, tell it to read `config/profile.yml` and pass the top-level `proxy:` block plus `stealth: true` to every `geometra_connect` call. Example dispatch prompt line: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `stealth: true` to every `geometra_connect` call."
-3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object from `config/profile.yml` and `stealth: true` in its own `geometra_connect` call.
+2. When dispatching any subagent whose work involves a `geometra_connect` call or a Geometra auto-connect call with `pageUrl` / `url`, tell it to read `config/profile.yml` and pass the top-level `proxy:` block plus `headless: true` and `stealth: true` to every connect. Example dispatch prompt line: "Proxy is configured; read `config/profile.yml` and pass its top-level `proxy:` object plus `headless: true` and `stealth: true` to every Geometra connect or auto-connect call."
+3. When the orchestrator itself opens a Chromium session (single-application interactive flow), include the same `proxy` object from `config/profile.yml`, `headless: true`, and `stealth: true` in its own `geometra_connect` call.
 4. If `proxy:` is absent from `profile.yml`, skip the param entirely. Do NOT invent a proxy URL or leave a stale placeholder.
 
 **Subagent responsibilities:**
 
-1. If the task prompt says proxy is configured, read `config/profile.yml` and pass the top-level `proxy:` object plus `stealth: true` through to `geometra_connect` and any `geometra_prepare_browser` calls unchanged.
-2. If the task prompt includes a legacy inline `proxy` object, pass it through unchanged and still set `stealth: true`, but never print the credentials back in status text.
-3. If the task prompt does NOT mention a proxy and `config/profile.yml` has no `proxy:` block, run with `stealth: true` and no proxy.
+1. If the task prompt says proxy is configured, read `config/profile.yml` and pass the top-level `proxy:` object plus `headless: true` and `stealth: true` through to `geometra_connect`, any Geometra auto-connect call with `pageUrl` / `url`, and any `geometra_prepare_browser` calls unchanged.
+2. If the task prompt includes a legacy inline `proxy` object, pass it through unchanged and still set `headless: true` and `stealth: true`, but never print the credentials back in status text.
+3. If the task prompt does NOT mention a proxy and `config/profile.yml` has no `proxy:` block, run with `headless: true`, `stealth: true`, and no proxy.
 4. Never second-guess the proxy field — if it comes from `profile.yml`, it's authoritative.
 
 ### When proxy use is load-bearing
@@ -100,6 +100,10 @@ Apply these rules when deciding whether the proxy is worth waiting for:
 
 The Geometra MCP partitions its reusable-proxy pool by proxy identity and browser flavor — proxy partitioning landed in `@geometra/mcp@1.59.0`, and stealth partitioning is available in `@geometra/mcp@1.61.3`. A direct session and a proxied session NEVER share a Chromium instance, and stock and stealth sessions do not pool together. Practical consequence: flipping `proxy:` on or off in `profile.yml` mid-session is safe — the next `geometra_connect` just opens a fresh Chromium in its own pool partition.
 
+### Direct helper for one-shot reads
+
+Use `npx job-forge portal:snapshot --url "{url}" --json` or `npx job-forge portal:form-schema --url "{url}" --json` when you only need a rendered page model, compact snapshot, or form schema. These commands import Geometra's session module directly instead of going through MCP, enforce `headless: true`, `stealth: true`, and `isolated: true`, pass the `config/profile.yml` proxy block if configured, and close Chromium before exit. Keep MCP for interactive multi-step browser automation where a live `sessionId` must be driven across actions.
+
 ### Troubleshooting
 
 | Symptom | Diagnosis |

package/modes/scan.md

@@ -25,7 +25,7 @@ Read `portals.yml` which contains:
 
 ### Use Level 1 — Direct Geometra (PRIMARY)
 
-**For each company in `tracked_companies`:** Connect to its `careers_url` with Geometra MCP (`geometra_connect({ ..., stealth: true })` + `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 each company in `tracked_companies`:** Connect to its `careers_url` with Geometra MCP (`geometra_connect({ ..., headless: true, stealth: true })` + `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:
 
 - It sees the page in real time (not cached Google results).
 - It works with SPAs (Ashby, Lever, Workday).
@@ -138,7 +138,7 @@ The levels are additive — all are executed, results are merged and deduplicate
 
 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:
-   a. `geometra_connect` to the `careers_url` with `stealth: true`
+   a. `geometra_connect` to the `careers_url` with `headless: true` and `stealth: true`
    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}`
@@ -317,7 +317,7 @@ Each company in `tracked_companies` MUST have a `careers_url` — the direct URL
 **If `careers_url` doesn't exist** for a company:
 1. Try the pattern for its known platform
 2. If that fails, do a quick WebSearch: `"{company}" careers jobs`
-3. Navigate with Geometra (`geometra_connect` with `stealth: true`) to confirm it works
+3. Navigate with Geometra (`geometra_connect` with `headless: true` and `stealth: true`) to confirm it works
 4. **Save the found URL in portals.yml** for future scans
 
 **If `careers_url` returns 404 or redirect:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.41",
+  "version": "2.14.43",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -18,6 +18,9 @@
     "tokens": "node scripts/token-usage-report.mjs",
     "tokens:today": "node scripts/token-usage-report.mjs --days 1",
     "tokens:log": "node scripts/token-usage-report.mjs --days 1 --append",
+    "portal:snapshot": "node bin/job-forge.mjs portal:snapshot",
+    "portal:form-schema": "node bin/job-forge.mjs portal:form-schema",
+    "portal:explain": "node bin/job-forge.mjs portal:explain",
     "trace:list": "node bin/job-forge.mjs trace:list",
     "trace:stats": "node bin/job-forge.mjs trace:stats",
     "trace:show": "node bin/job-forge.mjs trace:show",
@@ -196,6 +199,7 @@
     "@agent-pattern-labs/iso-score": "^0.1.1",
     "@agent-pattern-labs/iso-timeline": "^0.1.1",
     "@agent-pattern-labs/iso-trace": "^0.5.1",
+    "@geometra/mcp": "1.62.1",
     "playwright": "^1.58.1"
   },
   "devDependencies": {

package/scripts/check-helper-integration.mjs

@@ -20,6 +20,7 @@ const groups = [
   helper('trace', '@agent-pattern-labs/iso-trace', ['list', 'stats', 'show']),
   helper('telemetry', '', ['list', 'status', 'show', 'watch']),
   helper('guard', '@agent-pattern-labs/iso-guard', ['audit', 'explain'], { template: 'templates/guards/jobforge-baseline.yaml' }),
+  helper('portal', '@geometra/mcp', ['snapshot', 'form-schema', 'explain'], { migrated: true }),
   helper('ledger', '@agent-pattern-labs/iso-ledger', ['status', 'rebuild', 'verify', 'has', 'query'], { artifacts: ['.jobforge-ledger/'] }),
   helper('capabilities', '@agent-pattern-labs/iso-capabilities', ['list', 'explain', 'check', 'render'], { template: 'templates/capabilities.json', migrated: true }),
   helper('context', '@agent-pattern-labs/iso-context', ['list', 'explain', 'plan', 'check', 'render'], { template: 'templates/context.json', migrated: true }),

package/scripts/check-iso-smoke.mjs

@@ -21,12 +21,13 @@ const checks = [
   ["H5 blocks same-company concurrent retry", () => every(files.instructions, ["Re-dispatch the same company only AFTER", "previous subagent returns"])],
   ["H6 requires merge and verify", () => every(files.instructions, ["batch/tracker-additions/*.tsv", "npx job-forge merge", "npx job-forge verify"])],
   ["H7 distrusts subagent prose", () => every(files.instructions, ["must originate from a file", "not from prior subagent prose"])],
-  ["H8 keeps proxy secret and requires stealth", () => every(files.instructions, ["[H8]", "Do not transcribe `server`, `username`, `password`, or `bypass`", "`stealth: true`"])],
+  ["H8 keeps proxy secret and requires headless stealth", () => every(files.instructions, ["[H8]", "Do not transcribe `server`, `username`, `password`, or `bypass`", "`headless: true`", "`stealth: true`"])],
   ["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:*"])],
   ["root helper defaults are consolidated", () => !/\[D(?:9|1\d|2[0-9])\]/.test(files.instructions)],
   ["shared prompt points to on-demand references", () => every(files.instructions, ["modes/{mode}.md", "modes/reference-setup.md", "modes/reference-portals.md", "modes/reference-geometra.md"])],
+  ["apply mode requires headless stealth Geometra", () => every(files.apply, ["`headless: true`", "`stealth: true`", "`isolated: true`", "every Geometra auto-connect call"])],
   ["apply mode owns high-stakes upgrade", () => every(files.apply, ["[D8]", "@general-paid", "4.0/5", "high-stakes"])],
   ["apply mode blocks provider auto-downgrade", () => every(files.apply, ["[D9]", "do not auto-downgrade", "inspect telemetry before retrying"])],
   ["models policy pins OpenCode to DeepSeek V4 Flash", () => /extends:\s*standard/.test(files.models) && count(files.models, "opencode-go/deepseek-v4-flash") >= 4],

package/scripts/portal.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+
+const DEFAULT_WIDTH = 1024;
+const DEFAULT_HEIGHT = 768;
+const DEFAULT_SLOW_MO = 350;
+const DEFAULT_MAX_NODES = 120;
+
+const USAGE = `job-forge portal - deterministic direct-Geometra browser helpers
+
+Usage:
+  job-forge portal:snapshot --url <url> [--json] [--forms] [--max-nodes N]
+  job-forge portal:form-schema --url <url> [--json] [--include-options]
+  job-forge portal:explain [--json]
+
+Defaults are enforced in code for every browser launch:
+  isolated: true
+  headless: true
+  stealth: true
+  slowMo: 350
+
+The helper imports Geometra's session module directly. It does not call the
+MCP tool protocol, does not leave a reusable browser pool behind, and closes
+its isolated Chromium before exit. If config/profile.yml contains a top-level
+proxy: block with server/username/password/bypass, it is threaded into the
+browser unless --no-profile-proxy is passed.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'snapshot') {
+    await snapshot(opts);
+  } else if (cmd === 'form-schema') {
+    await formSchema(opts);
+  } else if (cmd === 'explain') {
+    await explain(opts);
+  } else {
+    console.error(`unknown portal command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+async function snapshot(opts) {
+  if (!opts.url) throw new Error('portal:snapshot requires --url <url>');
+  const geometra = await loadGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const session = await connect(geometra, opts, proxy);
+
+  try {
+    const root = buildRoot(geometra, session);
+    const pageModel = geometra.buildPageModel(root, {
+      maxPrimaryActions: opts.maxPrimaryActions,
+      maxSectionsPerKind: opts.maxSectionsPerKind,
+    });
+    const compact = geometra.buildCompactUiIndex(root, {
+      maxNodes: opts.maxNodes,
+      viewportWidth: opts.width,
+      viewportHeight: opts.height,
+    });
+    const result = {
+      url: opts.url,
+      session: connectionSummary(session, proxy),
+      defaults: launchDefaults(opts, proxy),
+      pageModel,
+      compact,
+      ...(opts.forms ? { forms: geometra.buildFormSchemas(root, formOptions(opts)) } : {}),
+    };
+    output(result, opts, () => {
+      console.log(`url: ${opts.url}`);
+      console.log(`session: ${session.id}`);
+      console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+      if (proxy) console.log(`proxy: ${redactProxy(proxy)}`);
+      console.log(geometra.summarizePageModel(pageModel, 12));
+      console.log(geometra.summarizeCompactIndex(compact.nodes, 24));
+      if (opts.forms) {
+        console.log(`forms: ${result.forms.length}`);
+      }
+    });
+  } finally {
+    geometra.disconnect({ sessionId: session.id, closeProxy: true });
+  }
+}
+
+async function formSchema(opts) {
+  if (!opts.url) throw new Error('portal:form-schema requires --url <url>');
+  const geometra = await loadGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const session = await connect(geometra, opts, proxy);
+
+  try {
+    const root = buildRoot(geometra, session);
+    const forms = geometra.buildFormSchemas(root, formOptions(opts));
+    const result = {
+      url: opts.url,
+      session: connectionSummary(session, proxy),
+      defaults: launchDefaults(opts, proxy),
+      forms,
+    };
+    output(result, opts, () => {
+      console.log(`url: ${opts.url}`);
+      console.log(`session: ${session.id}`);
+      console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+      if (proxy) console.log(`proxy: ${redactProxy(proxy)}`);
+      for (const form of forms) {
+        const name = form.name ? ` "${form.name}"` : '';
+        console.log(`${form.formId}${name}: ${form.fieldCount} fields, ${form.requiredCount} required, ${form.invalidCount} invalid`);
+        for (const field of form.fields.slice(0, opts.maxFields)) {
+          const required = field.required ? ' required' : '';
+          const invalid = field.invalid ? ' invalid' : '';
+          const label = field.label || field.name || field.id;
+          console.log(`  - ${field.kind}: ${label}${required}${invalid}`);
+        }
+      }
+    });
+  } finally {
+    geometra.disconnect({ sessionId: session.id, closeProxy: true });
+  }
+}
+
+async function explain(opts) {
+  const moduleTarget = resolveGeometraSessionModule();
+  const proxy = opts.profileProxy ? readProfileProxy(PROJECT_DIR) : null;
+  const result = {
+    projectDir: PROJECT_DIR,
+    module: moduleTarget,
+    defaults: launchDefaults(opts, proxy),
+    profileProxy: proxy ? redactProxy(proxy) : null,
+  };
+  output(result, opts, () => {
+    console.log(`project: ${PROJECT_DIR}`);
+    console.log(`module: ${moduleTarget.source} ${moduleTarget.path}`);
+    console.log(`defaults: isolated=true headless=true stealth=true slowMo=${opts.slowMo}`);
+    console.log(`profile proxy: ${proxy ? redactProxy(proxy) : 'none'}`);
+  });
+}
+
+async function connect(geometra, opts, proxy) {
+  return await geometra.connectThroughProxy({
+    pageUrl: opts.url,
+    isolated: true,
+    headless: true,
+    stealth: true,
+    slowMo: opts.slowMo,
+    width: opts.width,
+    height: opts.height,
+    awaitInitialFrame: true,
+    eagerInitialExtract: true,
+    ...(proxy ? { proxy } : {}),
+  });
+}
+
+function buildRoot(geometra, session) {
+  if (!session.tree || !session.layout) {
+    throw new Error(`Geometra session ${session.id} did not return an accessibility tree`);
+  }
+  return geometra.buildA11yTree(session.tree, session.layout);
+}
+
+async function loadGeometraSessionModule() {
+  const target = resolveGeometraSessionModule();
+  try {
+    return await import(pathToFileURL(target.path).href);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to load Geometra session module from ${target.path}: ${detail}`);
+  }
+}
+
+function resolveGeometraSessionModule() {
+  const explicit = normalizeEnv(process.env.JOB_FORGE_GEOMETRA_SESSION_MODULE);
+  if (explicit) return existingModulePath('env', resolve(explicit));
+
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const siblingPath = resolve(scriptDir, '../../geometra/mcp/dist/session.js');
+  if (existsSync(siblingPath)) return { source: 'sibling-repo', path: siblingPath };
+
+  const require = createRequire(import.meta.url);
+  try {
+    return {
+      source: 'package',
+      path: require.resolve('@geometra/mcp/dist/session.js'),
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not resolve @geometra/mcp/dist/session.js. Install dependencies with npm install. Resolution error: ${detail}`);
+  }
+}
+
+function existingModulePath(source, path) {
+  if (!existsSync(path)) throw new Error(`${source} Geometra session module not found: ${path}`);
+  return { source, path };
+}
+
+function parseArgs(args) {
+  const opts = {
+    help: false,
+    json: false,
+    forms: false,
+    includeOptions: false,
+    profileProxy: true,
+    width: DEFAULT_WIDTH,
+    height: DEFAULT_HEIGHT,
+    slowMo: DEFAULT_SLOW_MO,
+    maxNodes: DEFAULT_MAX_NODES,
+    maxFields: 80,
+    maxPrimaryActions: 6,
+    maxSectionsPerKind: 8,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--url' || arg === '-u') {
+      opts.url = valueAfter(args, ++i, arg);
+    } else if (arg.startsWith('--url=')) {
+      opts.url = arg.slice('--url='.length);
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--forms') {
+      opts.forms = true;
+    } else if (arg === '--include-options') {
+      opts.includeOptions = true;
+    } else if (arg === '--no-profile-proxy') {
+      opts.profileProxy = false;
+    } else if (arg === '--width') {
+      opts.width = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--width=')) {
+      opts.width = parsePositiveInt(arg.slice('--width='.length), '--width');
+    } else if (arg === '--height') {
+      opts.height = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--height=')) {
+      opts.height = parsePositiveInt(arg.slice('--height='.length), '--height');
+    } else if (arg === '--slow-mo') {
+      opts.slowMo = parseNonNegativeInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--slow-mo=')) {
+      opts.slowMo = parseNonNegativeInt(arg.slice('--slow-mo='.length), '--slow-mo');
+    } else if (arg === '--max-nodes') {
+      opts.maxNodes = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--max-nodes=')) {
+      opts.maxNodes = parsePositiveInt(arg.slice('--max-nodes='.length), '--max-nodes');
+    } else if (arg === '--max-fields') {
+      opts.maxFields = parsePositiveInt(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--max-fields=')) {
+      opts.maxFields = parsePositiveInt(arg.slice('--max-fields='.length), '--max-fields');
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function formOptions(opts) {
+  return {
+    includeOptions: opts.includeOptions,
+    maxFields: opts.maxFields,
+  };
+}
+
+function readProfileProxy(projectDir) {
+  const profilePath = join(projectDir, 'config', 'profile.yml');
+  if (!existsSync(profilePath)) return null;
+  const proxy = parseTopLevelProxy(readFileSync(profilePath, 'utf8'));
+  return proxy?.server ? proxy : null;
+}
+
+function parseTopLevelProxy(source) {
+  const lines = source.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^proxy:\s*(?:#.*)?$/.test(line));
+  if (start === -1) return null;
+  const proxy = {};
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line) && line.trim() !== '') break;
+    const match = line.match(/^\s+([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/);
+    if (!match) continue;
+    const key = match[1];
+    if (!['server', 'username', 'password', 'bypass'].includes(key)) continue;
+    const value = parseYamlScalar(match[2]);
+    if (value !== '') proxy[key] = value;
+  }
+  return Object.keys(proxy).length > 0 ? proxy : null;
+}
+
+function parseYamlScalar(raw) {
+  const withoutComment = raw.replace(/\s+#.*$/, '').trim();
+  if ((withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+      (withoutComment.startsWith("'") && withoutComment.endsWith("'"))) {
+    return withoutComment.slice(1, -1);
+  }
+  return withoutComment;
+}
+
+function output(result, opts, textPrinter) {
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    textPrinter();
+  }
+}
+
+function launchDefaults(opts, proxy) {
+  return {
+    isolated: true,
+    headless: true,
+    stealth: true,
+    slowMo: opts.slowMo,
+    width: opts.width,
+    height: opts.height,
+    profileProxy: Boolean(proxy),
+  };
+}
+
+function connectionSummary(session, proxy) {
+  return {
+    id: session.id,
+    url: session.url,
+    proxy: Boolean(proxy),
+  };
+}
+
+function redactProxy(proxy) {
+  try {
+    const url = new URL(proxy.server);
+    const auth = proxy.username || proxy.password || url.username || url.password ? ' auth=present' : '';
+    return `${url.protocol}//${url.host}${auth}${proxy.bypass ? ' bypass=present' : ''}`;
+  } catch {
+    return 'configured';
+  }
+}
+
+function normalizeEnv(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function valueAfter(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parsePositiveInt(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+  return parsed;
+}
+
+function parseNonNegativeInt(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
+  return parsed;
+}

package/templates/migrations.json

@@ -19,6 +19,9 @@
             "context:plan": "job-forge context:plan",
             "context:check": "job-forge context:check",
             "context:render": "job-forge context:render",
+            "portal:snapshot": "job-forge portal:snapshot",
+            "portal:form-schema": "job-forge portal:form-schema",
+            "portal:explain": "job-forge portal:explain",
             "cache:key": "job-forge cache:key",
             "cache:has": "job-forge cache:has",
             "cache:get": "job-forge cache:get",