job-forge 2.14.42 → 2.14.43

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/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/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({ ..., headless: true, 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({ ..., headless: true, 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({ ..., headless: true, 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({ ..., headless: true, 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-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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.42",
+  "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/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",