job-forge 2.14.18 → 2.14.19

package/.cursor/rules/main.mdc

@@ -65,12 +65,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
   why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
 
+- [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
+
 ## 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].
-4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+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].
 7. Cross-check subagent facts against authoritative files [H7].

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

@@ -76,6 +76,10 @@ Local workflow ledger (terminal, outside opencode):
 Artifact contracts (terminal, outside opencode):
   npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
   npx job-forge tracker-line ... --write   # renders + validates tracker TSV locally
+
+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
 ```
 
 ---

package/AGENTS.md

@@ -60,12 +60,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
   why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
 
+- [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
+
 ## 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].
-4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+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].
 7. Cross-check subagent facts against authoritative files [H7].

package/CLAUDE.md

@@ -60,12 +60,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
   why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
 
+- [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
+
 ## 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].
-4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+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].
 7. Cross-check subagent facts against authoritative files [H7].

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`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. Neither adds 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`, and `.jobforge-ledger/events.jsonl` records deterministic duplicate/status events via `@razroo/iso-ledger`. None of these add 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** | `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`, and `job-forge ledger:*` queries append-only workflow state without MCP/token overhead. |
+| **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. |
 | **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
+├── templates/                    # → states.yml, portals.example.yml, cv-template.html, capabilities.json
 ├── batch/batch-prompt.md         # → batch worker prompt
 ├── batch/batch-runner.sh         # → parallel orchestrator
 │
@@ -188,13 +188,14 @@ 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
+├── templates/                    # cv-template.html, portals.example.yml, states.yml, capabilities.json
 ├── config/profile.example.yml    # template for consumer's profile.yml
 ├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
 ├── scripts/
 │   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
 │   ├── tracker-line.mjs          # iso-contract-backed tracker TSV renderer
 │   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
+│   ├── capabilities.mjs          # iso-capabilities-backed role policy CLI
 │   ├── 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

@@ -21,6 +21,7 @@
  *   telemetry:*    Summarize JobForge pipeline status from traces + tracker files
  *   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
  *   sync           Re-run the harness symlink sync (bin/sync.mjs)
  *   help, --help   Show this message
  */
@@ -84,6 +85,14 @@ const ledgerAliases = {
   'ledger:path': 'path',
 };
 
+const capabilitiesAliases = {
+  'capabilities:list': 'list',
+  'capabilities:explain': 'explain',
+  'capabilities:check': 'check',
+  'capabilities:render': 'render',
+  'capabilities:path': 'path',
+};
+
 const [, , cmd, ...rest] = process.argv;
 
 function printHelp() {
@@ -114,6 +123,10 @@ Commands:
   ledger:rebuild     Rebuild .jobforge-ledger/events.jsonl from tracker/pipeline files
   ledger:has         Check URL or company+role state without loading tracker files
   ledger:verify      Validate the local workflow ledger
+  capabilities:list       List JobForge role capability policies
+  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
   sync           Re-create harness symlinks in the current project
 
 Deterministic helpers (prefer these over LLM-derived values):
@@ -143,6 +156,8 @@ Pass --help after a command to see its own flags, e.g.:
   job-forge guard:audit
   job-forge guard:explain
   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
 
 Project directory resolves to $JOB_FORGE_PROJECT or cwd.`);
 }
@@ -212,6 +227,21 @@ if (cmd === 'ledger' || ledgerAliases[cmd]) {
   process.exit(result.status ?? 1);
 }
 
+if (cmd === 'capabilities' || capabilitiesAliases[cmd]) {
+  const capabilitiesArgs = cmd === 'capabilities'
+    ? (rest.length === 0 ? ['help'] : rest)
+    : [capabilitiesAliases[cmd], ...rest];
+
+  const scriptPath = join(PKG_ROOT, 'scripts/capabilities.mjs');
+  const result = spawnSync(process.execPath, [scriptPath, ...capabilitiesArgs], {
+    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

@@ -175,6 +175,7 @@ Create `data/pipeline.md` when you start using the URL inbox (`/job-forge pipeli
 - PDFs: `cv-candidate-{company-slug}-{YYYY-MM-DD}.pdf`
 - 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:*`)
 
 ## Pipeline Integrity
 

package/docs/CUSTOMIZATION.md

@@ -142,6 +142,10 @@ npx job-forge ledger:verify
 
 Machine-readable artifact shapes live in `templates/contracts.json` and are enforced by `@razroo/iso-contract`. `job-forge tracker-line` renders tracker additions through the `jobforge.tracker-row` contract, `merge` validates pending TSV/table rows before writing tracker files, and `verify` validates existing tracker rows against the same contract. Custom forks can extend `templates/contracts.json`, but keep the tracker status enum aligned with `templates/states.yml`.
 
+## JobForge role capabilities
+
+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 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

@@ -53,6 +53,8 @@ The orchestrator can only dispatch to these three agents. Accidental self-calls
 ```
 Disables ~30 MCP tool schemas globally; each agent re-enables only what it needs in its own `.opencode/agents/<name>.md` frontmatter. Saves ~2-3K input tokens per request in the orchestrator.
 
+`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.
+
 **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/SETUP.md

@@ -126,6 +126,7 @@ From your project root, these commands maintain the tracker and pipeline checks.
 | Pipeline health check | `npx job-forge verify` | `npm run verify` |
 | 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` |
 | 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

@@ -79,6 +79,10 @@ Local workflow ledger (terminal, outside opencode):
 Artifact contracts (terminal, outside opencode):
   npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json
   npx job-forge tracker-line ... --write   # renders + validates tracker TSV locally
+
+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
 ```
 
 ---

package/iso/instructions.md

@@ -60,12 +60,15 @@ AI-powered job search pipeline: scans portals, evaluates offers, generates CVs v
 - [D9] Treat `templates/contracts.json` as the source of truth for machine-readable artifacts. Prefer `npx job-forge tracker-line ... --write` for tracker additions; if emitting TSV manually, inspect `npx iso-contract explain jobforge.tracker-row --contracts templates/contracts.json` first. `merge` and `verify` enforce the tracker-row contract locally.
   why: deterministic code owns the exact tracker TSV/table shape; repeated prose gets re-tokenized and agents occasionally misremember it
 
+- [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
+
 ## 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].
-4. Prepare Geometra dispatches: cleanup [H3], ledger prefilter when present [D8], dedupe [H2], location filter [D5], routing [D2], proxy prompt hygiene [H8].
+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].
 7. Cross-check subagent facts against authoritative files [H7].

package/lib/jobforge-capabilities.mjs

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  checkRoleCapability,
+  formatCheckResult,
+  formatResolvedRole,
+  loadCapabilityPolicy,
+  renderRole,
+  resolveRole,
+  roleNames,
+} from '@razroo/iso-capabilities';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+export const CAPABILITIES_RELATIVE_PATH = 'templates/capabilities.json';
+
+export function resolveProjectDir(projectDir = process.env.JOB_FORGE_PROJECT || process.cwd()) {
+  return projectDir;
+}
+
+export function jobForgeCapabilitiesPath(projectDir = resolveProjectDir()) {
+  const projectPath = join(projectDir, CAPABILITIES_RELATIVE_PATH);
+  if (existsSync(projectPath)) return projectPath;
+  return join(PKG_ROOT, CAPABILITIES_RELATIVE_PATH);
+}
+
+export function loadJobForgeCapabilityPolicy(projectDir = resolveProjectDir()) {
+  const path = jobForgeCapabilitiesPath(projectDir);
+  return loadCapabilityPolicy(JSON.parse(readFileSync(path, 'utf-8')));
+}
+
+export function listJobForgeCapabilityRoles(projectDir = resolveProjectDir()) {
+  return roleNames(loadJobForgeCapabilityPolicy(projectDir));
+}
+
+export function resolveJobForgeCapabilityRole(name, projectDir = resolveProjectDir()) {
+  return resolveRole(loadJobForgeCapabilityPolicy(projectDir), name);
+}
+
+export function checkJobForgeCapability(name, request, projectDir = resolveProjectDir()) {
+  return checkRoleCapability(loadJobForgeCapabilityPolicy(projectDir), name, request);
+}
+
+export function formatJobForgeCapabilityCheck(result) {
+  return formatCheckResult(result);
+}
+
+export function formatJobForgeCapabilityRole(role) {
+  return formatResolvedRole(role);
+}
+
+export function renderJobForgeCapabilityRole(role, target = 'markdown') {
+  return renderRole(role, target);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job-forge",
-  "version": "2.14.18",
+  "version": "2.14.19",
   "description": "AI-powered job search pipeline built on opencode",
   "type": "module",
   "bin": {
@@ -32,6 +32,10 @@
     "ledger:verify": "node bin/job-forge.mjs ledger:verify",
     "ledger:has": "node bin/job-forge.mjs ledger:has",
     "ledger:query": "node bin/job-forge.mjs ledger:query",
+    "capabilities:list": "node bin/job-forge.mjs capabilities:list",
+    "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",
     "plan": "iso plan .",
     "lint:agentmd": "agentmd lint iso/instructions.md",
     "lint:modes": "isolint lint modes/",
@@ -96,6 +100,7 @@
     "node": ">=20.6.0"
   },
   "dependencies": {
+    "@razroo/iso-capabilities": "^0.1.0",
     "@razroo/iso-contract": "^0.1.0",
     "@razroo/iso-guard": "^0.1.0",
     "@razroo/iso-ledger": "^0.1.0",

package/scripts/capabilities.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  checkJobForgeCapability,
+  formatJobForgeCapabilityCheck,
+  formatJobForgeCapabilityRole,
+  jobForgeCapabilitiesPath,
+  listJobForgeCapabilityRoles,
+  renderJobForgeCapabilityRole,
+  resolveJobForgeCapabilityRole,
+} from '../lib/jobforge-capabilities.mjs';
+
+const USAGE = `job-forge capabilities - deterministic role capability policy
+
+Usage:
+  job-forge capabilities:list [--json]
+  job-forge capabilities:explain <role> [--json]
+  job-forge capabilities:check <role> [--tool <name>] [--mcp <name>] [--command <cmd>] [--filesystem read|write] [--network off|restricted|on] [--json]
+  job-forge capabilities:render <role> [--target markdown|claude|codex|cursor|opencode|json] [--json]
+  job-forge capabilities:path
+
+The policy is templates/capabilities.json. It is local project state, not an
+MCP and not 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(jobForgeCapabilitiesPath(PROJECT_DIR));
+  } else if (cmd === 'list') {
+    list(opts);
+  } else if (cmd === 'explain') {
+    explain(positional, opts);
+  } else if (cmd === 'check') {
+    check(positional, opts);
+  } else if (cmd === 'render') {
+    render(positional, opts);
+  } else {
+    console.error(`unknown capabilities 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',
+    tools: [],
+    mcp: [],
+    commands: [],
+    filesystem: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--tool') {
+      opts.tools.push(valueAfter(args, ++i, '--tool'));
+    } else if (arg.startsWith('--tool=')) {
+      opts.tools.push(arg.slice('--tool='.length));
+    } else if (arg === '--mcp') {
+      opts.mcp.push(valueAfter(args, ++i, '--mcp'));
+    } else if (arg.startsWith('--mcp=')) {
+      opts.mcp.push(arg.slice('--mcp='.length));
+    } else if (arg === '--command') {
+      opts.commands.push(valueAfter(args, ++i, '--command'));
+    } else if (arg.startsWith('--command=')) {
+      opts.commands.push(arg.slice('--command='.length));
+    } else if (arg === '--filesystem') {
+      opts.filesystem.push(parseFilesystem(valueAfter(args, ++i, '--filesystem')));
+    } else if (arg.startsWith('--filesystem=')) {
+      opts.filesystem.push(parseFilesystem(arg.slice('--filesystem='.length)));
+    } else if (arg === '--network') {
+      opts.network = parseNetwork(valueAfter(args, ++i, '--network'));
+    } else if (arg.startsWith('--network=')) {
+      opts.network = parseNetwork(arg.slice('--network='.length));
+    } 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 = listJobForgeCapabilityRoles(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(names, null, 2));
+    return;
+  }
+  console.log(names.join('\n'));
+}
+
+function explain(positional, opts) {
+  const role = readRole(positional);
+  if (opts.json) {
+    console.log(JSON.stringify(role, null, 2));
+    return;
+  }
+  console.log(formatJobForgeCapabilityRole(role));
+}
+
+function check(positional, opts) {
+  const roleName = positional[0];
+  if (!roleName) throw new Error('missing role name');
+  const request = requestFromOptions(opts);
+  if (!hasRequest(request)) {
+    throw new Error('capabilities:check requires at least one --tool, --mcp, --command, --filesystem, or --network');
+  }
+  const result = checkJobForgeCapability(roleName, request, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatJobForgeCapabilityCheck(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function render(positional, opts) {
+  const role = readRole(positional);
+  const text = renderJobForgeCapabilityRole(role, opts.target);
+  if (opts.json) {
+    console.log(JSON.stringify({ target: opts.target, role, text }, null, 2));
+    return;
+  }
+  console.log(text);
+}
+
+function readRole(positional) {
+  const roleName = positional[0];
+  if (!roleName) throw new Error('missing role name');
+  return resolveJobForgeCapabilityRole(roleName, PROJECT_DIR);
+}
+
+function requestFromOptions(opts) {
+  return {
+    tools: opts.tools.length ? opts.tools : undefined,
+    mcp: opts.mcp.length ? opts.mcp : undefined,
+    commands: opts.commands.length ? opts.commands : undefined,
+    filesystem: opts.filesystem.length ? opts.filesystem : undefined,
+    network: opts.network,
+  };
+}
+
+function hasRequest(request) {
+  return Boolean(
+    request.tools?.length ||
+    request.mcp?.length ||
+    request.commands?.length ||
+    request.filesystem?.length ||
+    request.network,
+  );
+}
+
+function parseFilesystem(value) {
+  if (value === 'read' || value === 'write') return value;
+  throw new Error('--filesystem must be read or write');
+}
+
+function parseNetwork(value) {
+  if (value === 'off' || value === 'restricted' || value === 'on') return value;
+  throw new Error('--network must be off, restricted, or on');
+}
+
+function parseTarget(value) {
+  if (
+    value === 'markdown' ||
+    value === 'claude' ||
+    value === 'codex' ||
+    value === 'cursor' ||
+    value === 'opencode' ||
+    value === 'json'
+  ) {
+    return value;
+  }
+  throw new Error('--target must be markdown, claude, codex, cursor, opencode, or json');
+}

package/templates/capabilities.json

@@ -0,0 +1,109 @@
+{
+  "roles": [
+    {
+      "name": "jobforge-base",
+      "description": "Safe local JobForge role for reading project state and running deterministic verification commands.",
+      "tools": ["read", "search", "shell"],
+      "mcp": [],
+      "commands": {
+        "allow": [
+          "npx job-forge verify",
+          "npx job-forge ledger:*",
+          "npx job-forge capabilities:*",
+          "rg *"
+        ],
+        "deny": [
+          "rm -rf *"
+        ]
+      },
+      "filesystem": "read-only",
+      "network": "off",
+      "notes": [
+        "Do not paste secrets from config/profile.yml into prompts, traces, or summaries.",
+        "Prefer deterministic JobForge commands over re-reading growing tracker files when a local command can answer the question."
+      ]
+    },
+    {
+      "name": "orchestrator",
+      "description": "Primary session role that routes work, checks policy, and delegates tool-heavy browser/application work.",
+      "extends": "jobforge-base",
+      "tools": ["task"],
+      "commands": {
+        "allow": [
+          "npx job-forge merge",
+          "npx job-forge guard:*",
+          "npx job-forge telemetry:*",
+          "npx job-forge trace:*"
+        ]
+      },
+      "filesystem": "read-only",
+      "network": "off",
+      "notes": [
+        "Delegate multi-job Geometra work to subagents; do not run browser-heavy application loops inline.",
+        "Use capabilities checks when changing or auditing role boundaries."
+      ]
+    },
+    {
+      "name": "general-free",
+      "description": "Procedural worker for application form fills, TSV writes, merges, verification, OTP retrieval, and portal metadata extraction.",
+      "extends": "jobforge-base",
+      "tools": ["browser", "write"],
+      "mcp": ["geometra", "gmail"],
+      "commands": {
+        "allow": [
+          "npx job-forge tracker-line *",
+          "npx job-forge merge",
+          "npx job-forge verify",
+          "npx job-forge ledger:*",
+          "npx job-forge capabilities:*"
+        ],
+        "deny": [
+          "task *"
+        ]
+      },
+      "filesystem": "project-write",
+      "network": "restricted",
+      "notes": [
+        "Use for procedural, tool-heavy work where output shape is validated by JobForge commands.",
+        "Do not spawn nested tasks."
+      ]
+    },
+    {
+      "name": "general-paid",
+      "description": "Quality-sensitive writing and evaluation worker for reports, cover letters, interview stories, and outreach.",
+      "extends": "jobforge-base",
+      "tools": ["write"],
+      "commands": {
+        "allow": [
+          "npx job-forge render-report-header *",
+          "npx job-forge pdf",
+          "npx job-forge tracker-line *",
+          "npx job-forge verify"
+        ]
+      },
+      "filesystem": "project-write",
+      "network": "restricted",
+      "notes": [
+        "Use for narrative quality, personalization, and scoring explanations rather than browser automation."
+      ]
+    },
+    {
+      "name": "glm-minimal",
+      "description": "Narrow one-shot extractor/classifier role for small structured transforms.",
+      "extends": "jobforge-base",
+      "tools": [],
+      "commands": {
+        "allow": [
+          "npx job-forge slugify *",
+          "npx job-forge today",
+          "npx job-forge next-num"
+        ]
+      },
+      "filesystem": "read-only",
+      "network": "off",
+      "notes": [
+        "Keep input small and output structured; no browser, MCP, or nested task work."
+      ]
+    }
+  ]
+}