job-forge 2.14.19 → 2.14.21

package/.cursor/rules/main.mdc

@@ -68,11 +68,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D10] Treat `templates/capabilities.json` as the source of truth for role capability boundaries. Use `npx job-forge capabilities:explain <role>` or `npx job-forge capabilities:check <role> ...` when changing or validating subagent tool/MCP/filesystem/command permissions; do not paste the full capability matrix into task prompts.
   why: executable local policy prevents role-permission drift without adding MCP/tool-schema tokens or loading a capability matrix into the shared prefix
 
+- [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
+  why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
+
 ## Procedure
 
 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]; decide inline vs delegated work [D1].
+3. Read the active mode file [D3]; use context bundle checks when changing context loads [D11]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].

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

@@ -80,6 +80,10 @@ Artifact contracts (terminal, outside opencode):
 Role capabilities (terminal, outside opencode):
   npx job-forge capabilities:explain general-free
   npx job-forge capabilities:check general-free --tool browser --mcp geometra --filesystem write
+
+Context bundles (terminal, outside opencode):
+  npx job-forge context:plan apply
+  npx job-forge context:check apply --budget 23000
 ```
 
 ---

package/AGENTS.md

@@ -63,11 +63,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D10] Treat `templates/capabilities.json` as the source of truth for role capability boundaries. Use `npx job-forge capabilities:explain <role>` or `npx job-forge capabilities:check <role> ...` when changing or validating subagent tool/MCP/filesystem/command permissions; do not paste the full capability matrix into task prompts.
   why: executable local policy prevents role-permission drift without adding MCP/tool-schema tokens or loading a capability matrix into the shared prefix
 
+- [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
+  why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
+
 ## Procedure
 
 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]; decide inline vs delegated work [D1].
+3. Read the active mode file [D3]; use context bundle checks when changing context loads [D11]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].

package/CLAUDE.md

@@ -63,11 +63,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D10] Treat `templates/capabilities.json` as the source of truth for role capability boundaries. Use `npx job-forge capabilities:explain <role>` or `npx job-forge capabilities:check <role> ...` when changing or validating subagent tool/MCP/filesystem/command permissions; do not paste the full capability matrix into task prompts.
   why: executable local policy prevents role-permission drift without adding MCP/tool-schema tokens or loading a capability matrix into the shared prefix
 
+- [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
+  why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
+
 ## Procedure
 
 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]; decide inline vs delegated work [D1].
+3. Read the active mode file [D3]; use context bundle checks when changing context loads [D11]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].

package/README.md

@@ -31,7 +31,7 @@ The scaffolded `opencode.json` already has three MCPs wired up — they launch a
 - **Gmail** — reads replies from recruiters
 - **state-trace** — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with `python3 -m pip install "state-trace[mcp]"`; the MCP command is `state-trace-mcp`.
 
-JobForge also keeps MCP-free local workflow state: `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. None of these add prompt or tool-schema tokens.
+JobForge also keeps MCP-free local workflow state: `templates/contracts.json` defines tracker/apply artifact shapes via `@razroo/iso-contract`, `templates/capabilities.json` defines role capability boundaries via `@razroo/iso-capabilities`, `templates/context.json` defines deterministic mode/reference bundles via `@razroo/iso-context`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. None of these add always-on prompt or tool-schema tokens.
 
 `npm install` also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run `opencode`, `cursor`, `claude`, or `codex` in the same project and each picks up the shared MCP config and instructions.
 
@@ -78,7 +78,7 @@ JobForge turns opencode into a full job search command center. Instead of manual
 | **Durable Batch Orchestration** | `batch-runner.sh` uses `@razroo/iso-orchestrator` for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in `.jobforge-runs/`. |
 | **Pipeline Integrity** | Automated merge, dedup, status normalization, health checks |
 | **Cost-Aware Agent Routing** | Three subagents (`@general-free`, `@general-paid`, `@glm-minimal`) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to `opencode-go/deepseek-v4-flash` so application runs avoid overloaded free-model pools. See [Subagent Routing in AGENTS.md](AGENTS.md) for the task-to-agent mapping. |
-| **Trace + Telemetry + Guard + Contract + Ledger + Capabilities** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge ledger:*` queries append-only workflow state, and `job-forge capabilities:*` checks role boundaries without MCP/token overhead. |
+| **Trace + Telemetry + Guard + Contract + Ledger + Capabilities + Context** | `job-forge trace:*` exposes local OpenCode transcripts, `job-forge telemetry:*` summarizes runs, `job-forge guard:*` audits deterministic policy rules, `templates/contracts.json` enforces artifact shape with `iso-contract`, `job-forge ledger:*` queries append-only workflow state, `job-forge capabilities:*` checks role boundaries, and `job-forge context:*` plans mode/reference context bundles without MCP/tool-schema overhead. |
 | **Token Cost Visibility** | `job-forge tokens --days 1` for per-session breakdown; `job-forge session-report --since-minutes 60 --log` to flag sessions over budget and append history to `data/token-usage.tsv`. Auto-logged after every batch run. |
 
 ## Usage
@@ -162,7 +162,7 @@ my-search/
 ├── .opencode/skills/job-forge.md # → skill router
 ├── .opencode/agents/             # → @general-free, @general-paid, @glm-minimal
 ├── modes/                        # → _shared.md + skill modes
-├── templates/                    # → states.yml, portals.example.yml, cv-template.html, capabilities.json
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, capabilities.json, context.json
 ├── batch/batch-prompt.md         # → batch worker prompt
 ├── batch/batch-runner.sh         # → parallel orchestrator
 │
@@ -188,7 +188,7 @@ JobForge/
 │   ├── sync.mjs                  # postinstall: creates symlinks in consumer project
 │   └── create-job-forge.mjs      # scaffolder
 ├── modes/                        # _shared.md + 16 skill modes
-├── templates/                    # cv-template.html, portals.example.yml, states.yml, capabilities.json
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, capabilities.json, context.json
 ├── config/profile.example.yml    # template for consumer's profile.yml
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
@@ -196,6 +196,7 @@ JobForge/
 │   ├── tracker-line.mjs          # iso-contract-backed tracker TSV renderer
 │   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
 │   ├── capabilities.mjs          # iso-capabilities-backed role policy CLI
+│   ├── context.mjs               # iso-context-backed context bundle CLI
 │   ├── token-usage-report.mjs    # opencode cost analyzer
 │   └── release/check-source.mjs  # version gate for npm publish
 ├── tracker-lib.mjs / merge-tracker.mjs / dedup-tracker.mjs / verify-pipeline.mjs

package/bin/job-forge.mjs

@@ -22,6 +22,7 @@
  *   guard:*        Audit JobForge trace policy with iso-guard
  *   ledger:*       Query local deterministic workflow state via iso-ledger
  *   capabilities:* Query role capability policy via iso-capabilities
+ *   context:*      Query/render deterministic context bundles via iso-context
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -93,6 +94,15 @@ const capabilitiesAliases = {
   'capabilities:path': 'path',
 };
 
+const contextAliases = {
+  'context:list': 'list',
+  'context:explain': 'explain',
+  'context:plan': 'plan',
+  'context:check': 'check',
+  'context:render': 'render',
+  'context:path': 'path',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -127,6 +137,11 @@ Commands:
   capabilities:explain    Explain one role capability policy
   capabilities:check      Validate requested tool/MCP/command/fs/network access
   capabilities:render     Render compact role guidance for an agent harness
+  context:list            List JobForge context bundles
+  context:explain         Explain one context bundle
+  context:plan            Estimate files/tokens for one context bundle
+  context:check           Fail if a context bundle exceeds its budget
+  context:render          Render context bundle content as markdown/json
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -158,6 +173,8 @@ Pass --help after a command to see its own flags, e.g.:
   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
+  job-forge context:plan apply
+  job-forge context:check apply --budget 23000
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -242,6 +259,21 @@ if (cmd === 'capabilities' || capabilitiesAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'context' || contextAliases[cmd]) {
+  const contextArgs = cmd === 'context'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [contextAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/context.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...contextArgs], {
+    stdio: 'inherit',
+    cwd: PROJECT_DIR,
+    env: process.env,
+  });
+
+  process.exit(result.status ?? 1);
+}
+
 const rel = commands[cmd];
 if (!rel) {
   console.error(`Unknown command: ${cmd}\n`);

package/docs/ARCHITECTURE.md

@@ -163,6 +163,7 @@ data/pipeline.md        →  Pending URLs and `local:jds/...` inbox (see modes/p
 .jobforge-ledger/events.jsonl → Append-only workflow events for cheap local duplicate/status checks
 jds/*.md                 →  Saved job descriptions referenced from the pipeline (`local:jds/{file}`)
 templates/states.yml     →  Canonical status values
+templates/context.json    →  Deterministic mode/reference context bundle policy
 templates/cv-template.html → PDF generation template
 examples/*.md            →  Fictional layouts only (not read by scripts; see examples/README.md)
 ```
@@ -176,6 +177,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 - Tracker TSVs: `batch/tracker-additions/{num}-{company-slug}.tsv` (one file per evaluation; merged files move under `batch/tracker-additions/merged/`; shape enforced by `templates/contracts.json`)
 - Ledger: `.jobforge-ledger/events.jsonl` (created by `job-forge ledger:rebuild`, `tracker-line --write`, or `merge`; gitignored personal state)
 - Capabilities: `templates/capabilities.json` (role boundary policy inspected with `job-forge capabilities:*`)
+- Context: `templates/context.json` (mode/reference file bundles inspected with `job-forge context:*`)
 
 ## Pipeline Integrity
 
@@ -217,6 +219,7 @@ Scripts maintain data consistency. In a consumer project they're invoked via the
 | `scripts/telemetry.mjs` | `npx job-forge telemetry:status` / `telemetry:show` | JobForge operational telemetry derived from OpenCode traces plus tracker TSV state |
 | `scripts/guard.mjs` | `npx job-forge guard:audit` / `guard:explain` | Deterministic `@razroo/iso-guard` policy audits over local OpenCode traces |
 | `scripts/ledger.mjs` | `npx job-forge ledger:status` / `ledger:has` / `ledger:rebuild` | Deterministic `@razroo/iso-ledger` state over tracker, TSV, and pipeline files |
+| `scripts/context.mjs` | `npx job-forge context:list` / `context:plan` / `context:check` / `context:render` | Deterministic `@razroo/iso-context` mode/reference context bundle planning and rendering |
 | `tracker-lib.mjs` | _(library)_ | Shared helpers for reading/writing day-based tracker files — imported by merge/dedup/verify/normalize |
 | `bin/sync.mjs` | `npx job-forge sync` | Creates the harness symlinks in a consumer project (also runs as `postinstall`) |
 | `bin/create-job-forge.mjs` | `npx create-job-forge <dir>` | Scaffolds a new personal project |

package/docs/CUSTOMIZATION.md

@@ -146,6 +146,10 @@ Machine-readable artifact shapes live in `templates/contracts.json` and are enfo
 
 Role capability boundaries live in `templates/capabilities.json` and are enforced locally by `@razroo/iso-capabilities`. Use `job-forge capabilities:explain <role>` to inspect a role and `job-forge capabilities:check <role> ...` to validate a tool, MCP, command, filesystem, or network boundary before changing agent frontmatter. Custom forks can extend the policy, but keep it aligned with `.opencode/agents/` and the routing rules in `iso/instructions.md`.
 
+## JobForge context bundles
+
+Mode/reference context bundles live in `templates/context.json` and are planned locally by `@razroo/iso-context`. Use `job-forge context:plan <mode>` to see the files and estimated tokens, `job-forge context:check <mode>` to fail on budget drift, and `job-forge context:render <mode>` when you intentionally need a compact markdown or JSON context bundle. This is not an MCP and does not add tool-schema tokens; rendered context only consumes prompt tokens when a workflow deliberately asks for it.
+
 ## JobForge guard audits
 
 Guard audits run deterministic `@razroo/iso-guard` policies over the same local OpenCode traces. The default policy lives at `templates/guards/jobforge-baseline.yaml` and checks rules that are reliable from transcript data, including max two task dispatches per assistant message, no task-status polling via `task`, no raw proxy configuration in task prompts, and no child session task recursion.

package/docs/MODEL-ROUTING.md

@@ -55,6 +55,8 @@ Disables ~30 MCP tool schemas globally; each agent re-enables only what it needs
 
 `templates/capabilities.json` is the executable source for intended role boundaries. Inspect it with `job-forge capabilities:explain general-free`, or validate a boundary with `job-forge capabilities:check general-free --tool browser --mcp geometra --command "npx job-forge merge" --filesystem write --network restricted`. Native harness frontmatter still enforces permissions where supported; `iso-capabilities` gives JobForge a local audit/check contract for changes and reviews.
 
+`templates/context.json` is the executable source for intended mode/reference context loads. Inspect a bundle with `job-forge context:plan apply`, fail CI or local reviews on drift with `job-forge context:check apply`, or render the bundle only when a workflow deliberately needs it. `iso-context` is local CLI/library policy, not an MCP, so it avoids tool-schema overhead and prevents accidental "load every mode file" prompt bloat.
+
 **3. Thinking budgets** (`reasoningEffort` in agent frontmatter):
 - `@general-free`: `minimal` — procedural work shouldn't need chain-of-thought
 - `@general-paid`: `medium` — writing quality benefits from thinking

package/docs/README.md

@@ -31,7 +31,7 @@ The harness exposes a single CLI (`job-forge`) installed as a `bin` entry. In a
 
 | What you need | Where to read |
 |---------------|---------------|
-| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
+| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `trace`, `telemetry`, `guard`, `ledger`, `context`, `sync`). | [SETUP.md — Tracker and scripts (terminal)](SETUP.md#tracker-and-scripts-terminal). |
 | What each harness `.mjs` script does. | [ARCHITECTURE.md — Pipeline integrity](ARCHITECTURE.md#pipeline-integrity) and the scripts table underneath. |
 | Batch runner, TSV layout, and `batch/tracker-additions/` merge flow. | [batch/README.md](../batch/README.md). |
 | PR gate for harness contributions (`npm run verify` + `npm run build:dashboard`). | [CONTRIBUTING.md — Development](../CONTRIBUTING.md#development). |

package/docs/SETUP.md

@@ -127,6 +127,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Merge `batch/tracker-additions/*.tsv` into the tracker | `npx job-forge merge` | `npm run merge` |
 | Inspect tracker row contract | `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` | _(none)_ |
 | Inspect role capabilities | `npx job-forge capabilities:explain general-free` | `npm run capabilities:explain -- general-free` |
+| Inspect context bundle budget | `npx job-forge context:plan apply` | `npm run context:plan -- apply` |
 | Map status column to canonical labels | `npx job-forge normalize` | `npm run normalize` |
 | Merge duplicate company/role rows | `npx job-forge dedup` | `npm run dedup` |
 | Generate ATS-optimized CV PDF | `npx job-forge pdf` | `npm run pdf` |

package/iso/commands/job-forge.md

@@ -83,6 +83,10 @@ Artifact contracts (terminal, outside opencode):
 Role capabilities (terminal, outside opencode):
   npx job-forge capabilities:explain general-free
   npx job-forge capabilities:check general-free --tool browser --mcp geometra --filesystem write
+
+Context bundles (terminal, outside opencode):
+  npx job-forge context:plan apply
+  npx job-forge context:check apply --budget 23000
 ```
 
 ---

package/iso/instructions.md

@@ -63,11 +63,14 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D10] Treat `templates/capabilities.json` as the source of truth for role capability boundaries. Use `npx job-forge capabilities:explain <role>` or `npx job-forge capabilities:check <role> ...` when changing or validating subagent tool/MCP/filesystem/command permissions; do not paste the full capability matrix into task prompts.
   why: executable local policy prevents role-permission drift without adding MCP/tool-schema tokens or loading a capability matrix into the shared prefix
 
+- [D11] Treat `templates/context.json` as the source of truth for mode/reference context bundles. Use `npx job-forge context:plan <mode>` or `npx job-forge context:check <mode>` when changing or validating what a mode loads; do not paste the full context matrix into prompts.
+  why: deterministic context bundles prevent reference-file drift and accidental token bloat without adding MCP/tool-schema tokens
+
 ## Procedure
 
 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]; decide inline vs delegated work [D1].
+3. Read the active mode file [D3]; use context bundle checks when changing context loads [D11]; decide inline vs delegated work [D1].
 4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2, D10], proxy prompt hygiene [H8].
 5. Dispatch at most 2 tasks per round [H1]; wait for final outcomes, not just task ids [H5b].
 6. Keep multi-job form-filling out of the orchestrator [H4].

package/lib/jobforge-context.mjs

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  bundleNames,
+  formatContextPlan,
+  formatResolvedContextBundle,
+  loadContextPolicy,
+  planContext,
+  renderContextPlan,
+  resolveContextBundle,
+} from '@razroo/iso-context';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+export const CONTEXT_RELATIVE_PATH = 'templates/context.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeContextPath(projectDir = resolveProjectDir()) {
+  const projectPath = join(projectDir, CONTEXT_RELATIVE_PATH);
+  if (existsSync(projectPath)) return projectPath;
+  return join(PKG_ROOT, CONTEXT_RELATIVE_PATH);
+}
+
+export function loadJobForgeContextPolicy(projectDir = resolveProjectDir()) {
+  const path = jobForgeContextPath(projectDir);
+  return loadContextPolicy(JSON.parse(readFileSync(path, 'utf-8')));
+}
+
+export function listJobForgeContextBundles(projectDir = resolveProjectDir()) {
+  return bundleNames(loadJobForgeContextPolicy(projectDir));
+}
+
+export function resolveJobForgeContextBundle(name, projectDir = resolveProjectDir()) {
+  return resolveContextBundle(loadJobForgeContextPolicy(projectDir), name);
+}
+
+export function planJobForgeContextBundle(name, options = {}, projectDir = resolveProjectDir()) {
+  return planContext(loadJobForgeContextPolicy(projectDir), name, options);
+}
+
+export function formatJobForgeContextPlan(plan) {
+  return formatContextPlan(plan);
+}
+
+export function formatJobForgeContextBundle(bundle) {
+  return formatResolvedContextBundle(bundle);
+}
+
+export function renderJobForgeContextPlan(plan, target = 'markdown') {
+  return renderContextPlan(plan, target);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.19",
+  "version": "2.14.21",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -36,6 +36,11 @@
     "capabilities:explain": "node bin/job-forge.mjs capabilities:explain",
     "capabilities:check": "node bin/job-forge.mjs capabilities:check",
     "capabilities:render": "node bin/job-forge.mjs capabilities:render",
+    "context:list": "node bin/job-forge.mjs context:list",
+    "context:explain": "node bin/job-forge.mjs context:explain",
+    "context:plan": "node bin/job-forge.mjs context:plan",
+    "context:check": "node bin/job-forge.mjs context:check",
+    "context:render": "node bin/job-forge.mjs context:render",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -101,6 +106,7 @@
   },
   "dependencies": {
     "@razroo/iso-capabilities": "^0.1.0",
+    "@razroo/iso-context": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",

package/scripts/context.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  formatJobForgeContextBundle,
+  formatJobForgeContextPlan,
+  jobForgeContextPath,
+  listJobForgeContextBundles,
+  planJobForgeContextBundle,
+  renderJobForgeContextPlan,
+  resolveJobForgeContextBundle,
+} from '../lib/jobforge-context.mjs';
+
+const USAGE = `job-forge context - deterministic mode/reference context policy
+
+Usage:
+  job-forge context:list [--json]
+  job-forge context:explain <bundle> [--json]
+  job-forge context:plan <bundle> [--root <dir>] [--budget N] [--chars-per-token N] [--json]
+  job-forge context:check <bundle> [--root <dir>] [--budget N] [--chars-per-token N] [--json]
+  job-forge context:render <bundle> [--root <dir>] [--target markdown|json] [--json]
+  job-forge context:path
+
+The policy is templates/context.json. It is local project policy, not an MCP
+and not always-loaded prompt context.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const { positional, opts } = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeContextPath(PROJECT_DIR));
+  } else if (cmd === 'list') {
+    list(opts);
+  } else if (cmd === 'explain') {
+    explain(positional, opts);
+  } else if (cmd === 'plan') {
+    plan(positional, opts, false);
+  } else if (cmd === 'check') {
+    check(positional, opts);
+  } else if (cmd === 'render') {
+    render(positional, opts);
+  } else {
+    console.error(`unknown context command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const positional = [];
+  const opts = {
+    json: false,
+    help: false,
+    target: 'markdown',
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--root') {
+      opts.root = valueAfter(args, ++i, '--root');
+    } else if (arg.startsWith('--root=')) {
+      opts.root = arg.slice('--root='.length);
+    } else if (arg === '--budget' || arg === '--token-budget') {
+      opts.tokenBudget = parsePositiveInteger(valueAfter(args, ++i, arg), arg);
+    } else if (arg.startsWith('--budget=')) {
+      opts.tokenBudget = parsePositiveInteger(arg.slice('--budget='.length), '--budget');
+    } else if (arg.startsWith('--token-budget=')) {
+      opts.tokenBudget = parsePositiveInteger(arg.slice('--token-budget='.length), '--token-budget');
+    } else if (arg === '--chars-per-token') {
+      opts.charsPerToken = parsePositiveInteger(valueAfter(args, ++i, '--chars-per-token'), '--chars-per-token');
+    } else if (arg.startsWith('--chars-per-token=')) {
+      opts.charsPerToken = parsePositiveInteger(arg.slice('--chars-per-token='.length), '--chars-per-token');
+    } else if (arg === '--target') {
+      opts.target = parseTarget(valueAfter(args, ++i, '--target'));
+    } else if (arg.startsWith('--target=')) {
+      opts.target = parseTarget(arg.slice('--target='.length));
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown flag "${arg}"`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { positional, opts };
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function list(opts) {
+  const names = listJobForgeContextBundles(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(names, null, 2));
+    return;
+  }
+  console.log(names.join('\n'));
+}
+
+function explain(positional, opts) {
+  const bundle = readBundle(positional);
+  if (opts.json) {
+    console.log(JSON.stringify(bundle, null, 2));
+    return;
+  }
+  console.log(formatJobForgeContextBundle(bundle));
+}
+
+function plan(positional, opts, includeContent) {
+  const bundleName = readBundleName(positional);
+  const result = planJobForgeContextBundle(bundleName, planOptions(opts, includeContent), PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  console.log(formatJobForgeContextPlan(result));
+  return result;
+}
+
+function check(positional, opts) {
+  const result = plan(positional, opts, false);
+  process.exit(result.ok ? 0 : 1);
+}
+
+function render(positional, opts) {
+  const bundleName = readBundleName(positional);
+  const result = planJobForgeContextBundle(bundleName, planOptions(opts, true), PROJECT_DIR);
+  const text = renderJobForgeContextPlan(result, opts.target);
+  if (opts.json) {
+    console.log(JSON.stringify({ target: opts.target, plan: result, text }, null, 2));
+  } else {
+    console.log(text);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function readBundle(positional) {
+  return resolveJobForgeContextBundle(readBundleName(positional), PROJECT_DIR);
+}
+
+function readBundleName(positional) {
+  const bundleName = positional[0];
+  if (!bundleName) throw new Error('missing bundle name');
+  return bundleName;
+}
+
+function planOptions(opts, includeContent) {
+  return {
+    root: opts.root || PROJECT_DIR,
+    includeContent,
+    tokenBudget: opts.tokenBudget,
+    charsPerToken: opts.charsPerToken,
+  };
+}
+
+function parseTarget(value) {
+  if (value === 'markdown' || value === 'json') return value;
+  throw new Error('--target must be markdown or json');
+}
+
+function parsePositiveInteger(value, flag) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) throw new Error(`${flag} must be a positive integer`);
+  return number;
+}

package/templates/capabilities.json

@@ -10,6 +10,7 @@
           "npx job-forge verify",
           "npx job-forge ledger:*",
           "npx job-forge capabilities:*",
+          "npx job-forge context:*",
           "rg *"
         ],
         "deny": [

package/templates/context.json

@@ -0,0 +1,292 @@
+{
+  "defaults": {
+    "tokenBudget": 12000,
+    "charsPerToken": 4
+  },
+  "bundles": [
+    {
+      "name": "base",
+      "description": "Shared JobForge orchestration contract.",
+      "tokenBudget": 4000,
+      "files": [
+        {
+          "path": "AGENTS.harness.md",
+          "maxTokens": 3500,
+          "required": false,
+          "notes": [
+            "Consumer-project symlink to the shared harness contract."
+          ]
+        },
+        {
+          "path": "iso/instructions.md",
+          "maxTokens": 3500,
+          "required": false,
+          "notes": [
+            "Harness-source fallback; mode/reference files should be selected through narrower bundles."
+          ]
+        }
+      ]
+    },
+    {
+      "name": "shared",
+      "extends": "base",
+      "description": "Shared scoring model plus JobForge orchestration contract.",
+      "tokenBudget": 8000,
+      "files": [
+        {
+          "path": "modes/_shared.md",
+          "maxTokens": 4500,
+          "notes": [
+            "Loaded for evaluation-style modes that need archetypes, scoring, and profile references."
+          ]
+        }
+      ]
+    },
+    {
+      "name": "auto-pipeline",
+      "extends": "shared",
+      "description": "Default JD/URL pipeline context.",
+      "tokenBudget": 12000,
+      "files": [
+        {
+          "path": "modes/auto-pipeline.md",
+          "maxTokens": 2000
+        },
+        {
+          "path": "modes/reference-setup.md",
+          "maxTokens": 2600,
+          "required": false,
+          "notes": [
+            "Load when onboarding, tracker layout, or setup rules are the blocker."
+          ]
+        }
+      ]
+    },
+    {
+      "name": "offer",
+      "extends": "shared",
+      "description": "Single-offer evaluation context.",
+      "tokenBudget": 11000,
+      "files": [
+        {
+          "path": "modes/offer.md",
+          "maxTokens": 2400
+        },
+        {
+          "path": "modes/_shared-calibration.md",
+          "maxTokens": 2500,
+          "required": false,
+          "notes": [
+            "Load when score calibration or anchor examples are needed."
+          ]
+        }
+      ]
+    },
+    {
+      "name": "compare",
+      "extends": "shared",
+      "description": "Offer comparison context.",
+      "tokenBudget": 8500,
+      "files": [
+        {
+          "path": "modes/compare.md",
+          "maxTokens": 600
+        }
+      ]
+    },
+    {
+      "name": "contact",
+      "extends": "shared",
+      "description": "LinkedIn outreach context.",
+      "tokenBudget": 9000,
+      "files": [
+        {
+          "path": "modes/contact.md",
+          "maxTokens": 1200
+        }
+      ]
+    },
+    {
+      "name": "pdf",
+      "extends": "shared",
+      "description": "CV/PDF generation context.",
+      "tokenBudget": 10000,
+      "files": [
+        {
+          "path": "modes/pdf.md",
+          "maxTokens": 2200
+        }
+      ]
+    },
+    {
+      "name": "apply",
+      "extends": "shared",
+      "description": "Application form-fill context with Geometra recovery rules.",
+      "tokenBudget": 23000,
+      "files": [
+        {
+          "path": "modes/apply.md",
+          "maxTokens": 7800
+        },
+        {
+          "path": "modes/reference-geometra.md",
+          "maxTokens": 5600
+        },
+        {
+          "path": "modes/reference-portals.md",
+          "maxTokens": 2500,
+          "required": false,
+          "notes": [
+            "Load when OTP, proxy, or portal configuration is the blocker."
+          ]
+        }
+      ]
+    },
+    {
+      "name": "pipeline",
+      "extends": "shared",
+      "description": "Pending URL inbox context.",
+      "tokenBudget": 12000,
+      "files": [
+        {
+          "path": "modes/pipeline.md",
+          "maxTokens": 1500
+        },
+        {
+          "path": "modes/reference-setup.md",
+          "maxTokens": 2600,
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "scan",
+      "extends": "shared",
+      "description": "Portal scanning context.",
+      "tokenBudget": 18000,
+      "files": [
+        {
+          "path": "modes/scan.md",
+          "maxTokens": 6500
+        },
+        {
+          "path": "modes/reference-portals.md",
+          "maxTokens": 2500
+        }
+      ]
+    },
+    {
+      "name": "batch",
+      "extends": "shared",
+      "description": "Batch processing and durable runner context.",
+      "tokenBudget": 16000,
+      "files": [
+        {
+          "path": "modes/batch.md",
+          "maxTokens": 1500
+        },
+        {
+          "path": "batch/batch-prompt.md",
+          "maxTokens": 4800,
+          "required": false,
+          "notes": [
+            "Needed when invoking or auditing the standalone batch runner prompt."
+          ]
+        },
+        {
+          "path": "modes/reference-setup.md",
+          "maxTokens": 2600,
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "tracker",
+      "extends": "base",
+      "description": "Tracker/status context with setup reference.",
+      "tokenBudget": 7000,
+      "files": [
+        {
+          "path": "modes/tracker.md",
+          "maxTokens": 500
+        },
+        {
+          "path": "modes/reference-setup.md",
+          "maxTokens": 2600
+        }
+      ]
+    },
+    {
+      "name": "deep",
+      "extends": "base",
+      "description": "Company research context.",
+      "tokenBudget": 5500,
+      "files": [
+        {
+          "path": "modes/deep.md",
+          "maxTokens": 1200
+        }
+      ]
+    },
+    {
+      "name": "training",
+      "extends": "base",
+      "description": "Course/certification evaluation context.",
+      "tokenBudget": 4500,
+      "files": [
+        {
+          "path": "modes/training.md",
+          "maxTokens": 400
+        }
+      ]
+    },
+    {
+      "name": "project",
+      "extends": "base",
+      "description": "Portfolio project evaluation context.",
+      "tokenBudget": 4500,
+      "files": [
+        {
+          "path": "modes/project.md",
+          "maxTokens": 400
+        }
+      ]
+    },
+    {
+      "name": "followup",
+      "extends": "base",
+      "description": "Follow-up triage context.",
+      "tokenBudget": 5500,
+      "files": [
+        {
+          "path": "modes/followup.md",
+          "maxTokens": 1000
+        }
+      ]
+    },
+    {
+      "name": "rejection",
+      "extends": "base",
+      "description": "Rejection logging and pattern review context.",
+      "tokenBudget": 5500,
+      "files": [
+        {
+          "path": "modes/rejection.md",
+          "maxTokens": 1100
+        }
+      ]
+    },
+    {
+      "name": "negotiation",
+      "extends": "base",
+      "description": "Offer negotiation context.",
+      "tokenBudget": 6500,
+      "files": [
+        {
+          "path": "modes/negotiation.md",
+          "maxTokens": 1600
+        }
+      ]
+    }
+  ]
+}