job-forge 2.0.0

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,101 @@
+# Customization Guide
+
+> **Note on customizing mode files.** In a consumer project (scaffolded via `npx create-job-forge`), `modes/` is a symlink to `node_modules/job-forge/modes/`. If you edit a file through the symlink you're editing the shared harness copy, which gets overwritten on the next `npm update job-forge`. To customize a specific mode file locally, **remove the symlink and replace it with a real copy**:
+>
+> ```bash
+> cp node_modules/job-forge/modes/_shared.md modes/_shared.md.new
+> rm modes/_shared.md               # remove the symlink (breaks the whole modes/ dir link)
+> mkdir -p modes                    # recreate as a real dir
+> cp node_modules/job-forge/modes/*.md modes/
+> mv modes/_shared.md.new modes/_shared.md
+> # edit modes/_shared.md — npx job-forge sync will leave it alone from now on
+> ```
+>
+> A cleaner path is to keep customization in `config/profile.yml` where possible (the shared mode files already read from it). Open an issue against `razroo/JobForge` if a piece of personal data is currently stuck in a mode file and ought to be in `profile.yml`.
+
+## Profile (config/profile.yml)
+
+The `config/profile.yml` file is the single source of truth for your identity. All modes read from here.
+
+Key sections:
+
+- **candidate**: Name, email, phone, location, LinkedIn, portfolio.
+- **target_roles**: Your North Star roles and archetypes.
+- **narrative**: Your headline, exit story, superpowers, proof points.
+- **compensation**: Target range, minimum, currency.
+- **location**: Country, timezone, visa status, on-site availability.
+
+## Target Roles (modes/_shared.md)
+
+The archetype table in `_shared.md` determines how offers are scored and CVs are framed. Edit the table to match YOUR career targets:
+
+```markdown
+| Archetype | Thematic axes | What they buy |
+|-----------|---------------|---------------|
+| **Your Role 1** | key skills | what they need |
+| **Your Role 2** | key skills | what they need |
+```
+
+Also update the "Adaptive Framing" table to map YOUR specific projects to each archetype.
+
+## Portals (portals.yml)
+
+Copy from `templates/portals.example.yml` and customize:
+
+1. **title_filter.positive**: Keywords matching your target roles
+2. **title_filter.negative**: Tech stacks or domains to exclude
+3. **search_queries**: WebSearch queries for job boards (Ashby, Greenhouse, Lever)
+4. **tracked_companies**: Companies to check directly
+
+## CV Template (templates/cv-template.html)
+
+The HTML template uses these design tokens:
+- **Fonts**: Space Grotesk (headings) + DM Sans (body) -- self-hosted in `fonts/`
+- **Colors**: Cyan primary (`hsl(187,74%,32%)`) + Purple accent (`hsl(270,70%,45%)`)
+- **Layout**: Single-column, ATS-optimized
+
+To customize fonts/colors, edit the CSS in the template. Update font files in `fonts/` if switching fonts.
+
+## Examples (`examples/`)
+
+Fictional samples for structure and tone — not real candidates. See [`examples/README.md`](../examples/README.md) for markdown CVs, an optional article-digest example, and a sample report layout. Use them as templates, then replace every detail with your own before applying.
+
+## Interview prep (`interview-prep/story-bank.md`)
+
+Optional file that holds curated STAR+R stories across evaluations. Modes that produce interview prep (for example Block F in a single-offer evaluation) can append or reference stories here so you reuse the same narratives instead of starting from scratch before each interview. The shipped file is a scaffold with formatting comments; replace placeholders with your own content as the bank fills in. If you prefer a different path, keep the same structure and point your workflow at your copy.
+
+## Negotiation Scripts (modes/_shared.md)
+
+The negotiation section provides frameworks for salary discussions. Replace the example scripts with your own:
+- Target ranges
+- Geographic arbitrage strategy
+- Pushback responses
+
+## Hooks (Optional)
+
+JobForge can integrate with external systems via opencode hooks. Example hooks:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "echo 'JobForge session started'"
+      }]
+    }]
+  }
+}
+```
+
+Save hooks in `.opencode/settings.json`.
+
+## States (templates/states.yml)
+
+The canonical states rarely need changing. Since `templates/` is a symlink into the harness in consumer projects, adding new states means contributing back to `razroo/JobForge` (see [CONTRIBUTING.md](../CONTRIBUTING.md)). If you're working in the harness repo directly (Path B), update:
+
+1. `templates/states.yml`
+2. `normalize-statuses.mjs` (alias mappings)
+3. `modes/_shared.md` (any references)
+4. `merge-tracker.mjs` — TSV merges validate the status column against labels in `templates/states.yml`; extend the parser or built-in fallbacks there if you add states before running `npx job-forge merge` / `npm run merge`; see [batch/README.md](../batch/README.md)
+5. `verify-pipeline.mjs` — extend `CANONICAL_STATUSES` (and `ALIASES` when you add new status aliases) so the health check stays aligned with `states.yml`; see [Architecture — Pipeline Integrity](ARCHITECTURE.md#pipeline-integrity)

package/docs/MODEL-ROUTING.md

@@ -0,0 +1,195 @@
+# Model Routing
+
+JobForge routes each piece of work to the cheapest model that can do it well, instead of running every tool call on one expensive model. This doc explains why that matters, how the routing is wired, and how to customize it.
+
+## Why routing matters (the cost math)
+
+A two-day trace early in development showed `$48` in spend, with **84% coming from GLM 5.1** despite the majority of the work being procedural (form fills, tracker updates, OTP retrieval). The root cause:
+
+- **GLM 5.1's provider doesn't discount cache reads.** On Anthropic, a 10K-token cached prefix costs ~$0.03. On GLM 5.1 it bills near-full input rate (~$0.35). Every session that re-loads the prefix pays full price.
+- **Procedural work is the high-volume work.** 1000+ messages per day go to form filling, TSV merges, scan dedup. Running that on GLM 5.1 is ~10× more expensive than running it on a free-tier model that can handle the task just fine.
+- **Free-tier opencode models are genuinely free and genuinely capable.** `opencode/big-pickle` processed 1000+ messages at $0 over the same window with acceptable quality on procedural tasks.
+
+Conclusion: route procedural work to free tier, reserve paid models for tasks that actually need the quality.
+
+## The three subagents
+
+Defined in `.opencode/agents/*.md` (shipped in the harness, symlinked into consumers by `job-forge sync`):
+
+| Agent | Model | Reasoning | Use for |
+|-------|-------|-----------|---------|
+| `@general-free` | `opencode/big-pickle` (free) | `minimal` | Geometra form fills, tracker TSV merges, scan dedup, OTP retrieval via Gmail, scripted pipeline steps |
+| `@general-paid` | `opencode/glm-5.1` | `medium` | Offer evaluation narratives (Blocks A-F), cover letters, "Why X?" answers, STAR+R interview stories, LinkedIn outreach prose |
+| `@glm-minimal` | `opencode/minimax-m2.5-free` (free) | `none` | Narrow one-shot transforms: "extract these 8 fields from this JD text → JSON", "classify this archetype" |
+
+The full task-to-agent mapping lives in [AGENTS.md → Subagent Routing](../AGENTS.md#subagent-routing--which-agent-for-which-task). The orchestrator (your primary session) is expected to delegate before taking any multi-step action — see the **Pre-flight delegation** rule in AGENTS.md.
+
+## How the routing is enforced
+
+Four layers, each reinforcing the others:
+
+**1. Permission layer** (`opencode.json:permission.task`):
+```json
+{
+  "permission": {
+    "task": {
+      "general-free": "allow",
+      "general-paid": "allow",
+      "glm-minimal": "allow"
+    }
+  }
+}
+```
+The orchestrator can only dispatch to these three agents. Accidental self-calls or hallucinated agent names fail loudly.
+
+**2. Tool surface trim** (`opencode.json:tools` + per-agent `tools:`):
+```json
+{
+  "tools": {
+    "geometra_*": false,
+    "gmail_*": false
+  }
+}
+```
+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.
+
+**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
+- `@glm-minimal`: `none` — pure transforms, emit and exit
+
+**4. Prompt rules** (in each agent's `.md` body): explicit instructions on working style, what to do and not do, and structured output expectations.
+
+## Customizing the routing
+
+All three layers are designed to be edited — this is your search, your cost budget, your model preferences.
+
+### Swap the paid model
+
+The default `@general-paid` is `opencode/glm-5.1`. To use Claude instead, edit `.opencode/agents/general-paid.md`:
+
+```yaml
+---
+model: opencode/claude-sonnet-4-6
+reasoningEffort: medium
+---
+```
+
+The `.opencode/agents/general-paid.md` file is a symlink into `node_modules/job-forge/` by default. To customize locally without modifying the harness: delete the symlink and create a real file with the same name — `job-forge sync` will skip it on future updates. Or override in `opencode.json` under `agent.general-paid.model`.
+
+### Swap the free tier
+
+Same idea — edit `.opencode/agents/general-free.md`'s `model:` field. `opencode/minimax-m2.5-free` is another zero-cost option the data shows handles ~900 messages per day cleanly. If you run into quality issues on forms, bump this agent's model to a small paid tier (e.g., Haiku) rather than routing everything through paid.
+
+### Add a custom agent
+
+Create `.opencode/agents/my-agent.md` with the same frontmatter shape, then allow-list it in `opencode.json:permission.task`:
+
+```json
+{
+  "permission": {
+    "task": {
+      "general-free": "allow",
+      "general-paid": "allow",
+      "glm-minimal": "allow",
+      "my-agent": "allow"
+    }
+  }
+}
+```
+
+### Change what tools an agent can call
+
+Edit the `tools:` block in the agent's frontmatter. Use globs to allow-list families (`gmail_*: true`) or individual names (`geometra_connect: true`). Anything not explicitly re-enabled inherits the global `false`.
+
+### Route differently per task
+
+The task-to-agent mapping in AGENTS.md is instruction-level, not enforced by config. If you want evaluation narratives on free tier (saving cost but accepting lower writing quality), update the "Subagent Routing" table in AGENTS.md and the orchestrator will follow it.
+
+## Verifying the routing actually works
+
+Three commands, increasing precision:
+
+```bash
+# 1. Per-day, per-model breakdown — confirms % of cost going to each tier
+npx job-forge tokens --days 2
+
+# 2. Per-session breakdown since N minutes ago, with >$1 budget warning
+npx job-forge session-report --since-minutes 60
+
+# 3. Drill into a specific session to see which agent made which message
+npx job-forge tokens --session <session-id>
+```
+
+Healthy pattern after this architecture lands:
+- **`opencode/big-pickle`** (or your free-tier choice) handles the message majority at $0
+- **`opencode/glm-5.1`** (or your paid choice) costs per session stay under $1 for most evaluations
+- Session titles prefixed `@general-free`, `@general-paid`, `@glm-minimal` appear in the list — confirms delegation actually happened
+- `cache_read` >> `cache_creation` on parallel subagent runs within a 5-min window
+
+Failure pattern to watch for:
+- **All messages showing up under your primary model** (no `@general-*` titles) → orchestrator isn't delegating. Check the Pre-flight delegation rule in AGENTS.md is being followed; tighten wording if not.
+- **High cache-creation with near-zero cache-read across parallel workers** → workers aren't firing within the 5-min cache TTL, or the shared prefix isn't byte-identical (see [batch/README.md](../batch/README.md) for the prompt-cache-friendly batch pattern).
+
+## Automatic fallback on rate limits / 5xx
+
+A rate-limited or overloaded free-tier model would otherwise wedge the whole subagent flow — the delegated task errors and the orchestrator sits stuck. The harness ships with [`@razroo/opencode-model-fallback`](https://www.npmjs.com/package/@razroo/opencode-model-fallback) (added as a dependency in the scaffolder) to rotate agents through a configured `fallback_models` chain automatically.
+
+Default chains ship upstream in each agent's YAML frontmatter (`node_modules/job-forge/.opencode/agents/*.md`, symlinked into your project's `.opencode/agents/`):
+
+| Agent | Primary | Fallback chain (in order) |
+|-------|---------|---------------------------|
+| `@general-free` | `opencode/big-pickle` | `opencode/minimax-m2.5-free` → `opencode/nemotron-3-super-free` → `opencode-go/minimax-m2.7` → `opencode/glm-5.1` (paid escape hatch) |
+| `@general-paid` | `opencode/glm-5.1` | `opencode/claude-haiku-4-5` |
+| `@glm-minimal` | `opencode/minimax-m2.5-free` | `opencode/big-pickle` → `opencode/nemotron-3-super-free` |
+
+Free-tier agents exhaust free models first, then try minimax 2.7 as a cheap buffer before escalating to glm-5.1. Paid agents fall back to Haiku (cheaper unstick escape hatch). **Note:** all model IDs use the `opencode/` or `opencode-go/` prefix — the `anthropic/` prefix does not exist in opencode's model registry and will throw `ProviderModelNotFoundError`.
+
+Consumers **do not need to configure anything** to get these defaults: the chains arrive via the symlinked agent MD files, and `@razroo/opencode-model-fallback` (≥0.3.1) reads them from the `options.fallback_models` field that opencode relocates unknown frontmatter keys into. The consumer's `opencode.json` only needs `"plugin": ["@razroo/opencode-model-fallback"]` — which the scaffolder sets automatically.
+
+**When fallback fires:** the plugin pattern-matches rate-limit / 5xx / quota / "overloaded" / "insufficient credits" errors. Failed models enter a 60-second cooldown before they're retried. Every rotation logs to `~/.config/opencode/opencode-model-fallback.log` with the trigger error, original model, and target model — grep for `"Auto-retrying with fallback model"` to confirm it fired.
+
+### Overriding an upstream chain
+
+Add an `agent.<name>.fallback_models` block to your project's `opencode.json`. Top-level entries win over upstream frontmatter:
+
+```json
+{
+  "agent": {
+    "general-free": {
+      "fallback_models": ["my/preferred-free", "my/preferred-paid"]
+    }
+  }
+}
+```
+
+### Global fallback chain (agents without their own)
+
+Plugin-level config at `.opencode/opencode-model-fallback.json` — applies to any agent whose `fallback_models` is empty:
+
+```json
+{
+  "cooldown_seconds": 60,
+  "timeout_seconds": 30,
+  "notify_on_fallback": true,
+  "fallback_models": ["opencode/minimax-m2.5-free", "opencode/glm-5.1"]
+}
+```
+
+### Disabling fallback
+
+Remove `"@razroo/opencode-model-fallback"` from `opencode.json:plugin` — agents keep their `model:` primary and errors propagate normally.
+
+## Known limitations
+
+- **opencode's 5-minute cache TTL is hardcoded.** The 1-hour cache (Anthropic beta, `extended-cache-ttl-2025-04-11`) is not plumbed through opencode as of 2026-04-15. Long batch runs (>5 min between workers) will miss cache every cycle. Upstream fix would be 2 lines in `packages/opencode/src/provider/`.
+- **`instructions` is top-level, not per-agent.** Files listed in `opencode.json:instructions` load for every agent including free-tier. This is fine for `cv.md` and `_shared.md` (they're small and useful everywhere), but means you can't hide heavy context from free agents via instructions — use per-agent `prompt:` files for that.
+- **`reasoningEffort` support varies by provider.** Anthropic accepts `thinking: { type: "disabled" }`; opencode-labs models may need the `variant` pattern. See the `reasoningEffort` values in the opencode docs.
+
+## See also
+
+- [AGENTS.md — Subagent Routing](../AGENTS.md#subagent-routing--which-agent-for-which-task) — the task-to-agent mapping table
+- [AGENTS.md — Pre-flight delegation](../AGENTS.md#pre-flight-delegation-hard-rule) — the "first tool call must be `task`" rule
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how modes, symlinks, and the consumer/harness split fit together
+- [CUSTOMIZATION.md](CUSTOMIZATION.md) — archetype, CV template, portal, and state customization
+- `.opencode/agents/` — the three agent definitions (YAML frontmatter + markdown prompt body)

package/docs/README.md

@@ -0,0 +1,54 @@
+# JobForge documentation
+
+Guides for installing JobForge, understanding how pieces fit together, and tailoring the system to your search. Use this file as the entry point when browsing the `docs/` folder on GitHub or locally.
+
+## Install paths
+
+JobForge ships as an installable package (v2.0.0+). Pick the path that matches your goal:
+
+| Path | Who it's for | How |
+|------|--------------|-----|
+| **A — Scaffold a personal project** | Most users. You want a job search project with the harness in `node_modules`, updatable via `npm update job-forge`. | `npx github:razroo/JobForge create-job-forge my-search && cd my-search && npm install` |
+| **B — Clone the harness directly** | Contributors and hackers working on modes, scripts, or the scoring model. Personal files are gitignored. | `git clone https://github.com/razroo/JobForge.git && cd JobForge && npm install` |
+
+See [SETUP.md](SETUP.md) for both paths.
+
+## Guides
+
+| Guide | What it covers |
+|-------|----------------|
+| [SETUP.md](SETUP.md) | Prerequisites, both install paths, profile and CV, portals, `npx job-forge verify`, optional Go dashboard, token usage tracking, [troubleshooting](SETUP.md#troubleshooting) |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | [Package architecture](ARCHITECTURE.md#package-architecture-v200) (consumer vs harness split), modes under `modes/`, single-offer flow, batch runner, tracker and scripts, [contributor touchpoints](ARCHITECTURE.md#contributing-touchpoints) |
+| [CUSTOMIZATION.md](CUSTOMIZATION.md) | Profile, archetypes in `_shared.md`, `portals.yml`, CV template, canonical states, optional story bank and opencode hooks. Also: how to customize a symlinked mode file locally |
+| [MODEL-ROUTING.md](MODEL-ROUTING.md) | Why the harness uses three cost-tiered subagents (`@general-free`, `@general-paid`, `@glm-minimal`), how routing is enforced (permission + tool-surface trim + reasoningEffort), how to swap models or add agents, and the automatic fallback-on-rate-limit behavior via [`@razroo/opencode-model-fallback`](https://www.npmjs.com/package/@razroo/opencode-model-fallback) |
+| [examples/README.md](../examples/README.md) | Fictional CV samples (per-role markdown), optional digest, fictional [`sample-jd.md`](../examples/sample-jd.md) for `local:jds/…` shape, and sample report — starting point for new `cv.md`, JD-on-disk layout, or contributor archetypes (cloud infrastructure, agent platform) |
+| [batch/README.md](../batch/README.md) | Batch TSV format, `batch-runner.sh`, `tracker-additions/` merge flow with `npx job-forge merge` |
+| [jds/README.md](../jds/README.md) | Markdown JDs on disk; `local:jds/{file}.md` lines in `data/pipeline.md` |
+
+## Commands and automation
+
+The harness exposes a single CLI (`job-forge`) installed as a `bin` entry. In a consumer project, `npx job-forge <cmd>` invokes any of the scripts; npm script aliases (`npm run verify`, `npm run merge`, `npm run dedup`, `npm run normalize`) are wired up in the scaffolded `package.json`. In the harness repo (Path B), scripts run directly via `node <script>.mjs` or their npm aliases.
+
+| What you need | Where to read |
+|---------------|---------------|
+| Full command list (`verify`, `merge`, `dedup`, `normalize`, `pdf`, `sync-check`, `tokens`, `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). |
+| Optional scripted iterations (harness repo only). | [scripts/cursor-agent-loop.sh](../scripts/cursor-agent-loop.sh). Usage and env vars live in the script header and in [CONTRIBUTING.md — Optional: scripted agent iterations](../CONTRIBUTING.md#optional-scripted-agent-iterations). Verbose JSON output is formatted by [cursor-agent-stream-format.py](../scripts/cursor-agent-stream-format.py). |
+| Work-marker search (`T`ODO, `F`IXME, `H`ACK strings in the source) before picking work. | [CONTRIBUTING.md — Optional: scripted agent iterations](../CONTRIBUTING.md#optional-scripted-agent-iterations) — `rg` one-liner from the harness repo root. |
+
+## Related material (harness repo root)
+
+- [modes/README.md](../modes/README.md) — per-command prompts used with the skill router (archetypes and shared scoring live in `_shared.md`; see **Modes** in [ARCHITECTURE.md](ARCHITECTURE.md)).
+- [.opencode/skills/job-forge.md](../.opencode/skills/job-forge.md) — the skill router that routes `/job-forge <mode>` to the right prompt and loads only the data files that mode needs.
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — branch workflow, quality gate, contribution ideas.
+- [templates/states.yml](../templates/states.yml) — canonical tracker status ids and labels (used by verify, merge, and normalize).
+- [templates/portals.example.yml](../templates/portals.example.yml) — starter portal and scanner config (copied into consumer projects as `portals.yml`).
+- [templates/cv-template.html](../templates/cv-template.html) — HTML layout for ATS-style PDFs from `generate-pdf.mjs`.
+- [config/profile.example.yml](../config/profile.example.yml) — template copied into consumer projects as `config/profile.yml`.
+- [examples/README.md](../examples/README.md) — fictional CV samples and illustrative report layout.
+- [interview-prep/story-bank.md](../interview-prep/story-bank.md) — optional STAR+R story bank (grows as you run evaluations).
+- [batch/README.md](../batch/README.md) — batch TSV input, merge step, and runner prerequisites.
+- [`data/pipeline.md`](../data/) — inbox of pending offer URLs and `local:jds/…` lines (create when you first queue a URL; see [`modes/pipeline.md`](../modes/pipeline.md)).
+- [jds/README.md](../jds/README.md) — markdown job descriptions on disk; the pipeline references them as `local:jds/{filename}.md` from the project root.

package/docs/SETUP.md

@@ -0,0 +1,186 @@
+# Setup Guide
+
+## Prerequisites
+
+- [opencode](https://opencode.ai) installed and configured
+- Node.js 18+ (for the CLI, PDF generation, and tracker scripts)
+- (Optional) Go (for the dashboard TUI) — use a toolchain that satisfies the `go` directive in [`dashboard/go.mod`](../dashboard/go.mod)
+
+## Quick Start (two paths)
+
+### Path A — Scaffold a personal project (recommended)
+
+JobForge is distributed as an installable npm package. Use the scaffolder to create a new project that keeps only your personal data (CV, profile, portals, tracker) while the harness (modes, skills, scripts) lives in `node_modules/job-forge` and updates with one command.
+
+```bash
+# 1. Scaffold
+npx github:razroo/JobForge create-job-forge my-job-search
+cd my-job-search
+
+# 2. Install the harness (pulls razroo/JobForge from GitHub; postinstall
+#    creates symlinks for modes/, templates/, .opencode/skills/job-forge.md,
+#    and batch/{batch-prompt.md,batch-runner.sh,README.md})
+npm install
+
+# 3. Fill in personal files
+#    - cv.md (your CV in markdown)
+#    - config/profile.yml (copied from profile.example.yml — edit with your
+#      name, email, target roles, narrative, proof points)
+#    - portals.yml (copied from templates/portals.example.yml — edit keywords
+#      and tracked companies)
+#    - article-digest.md (optional; proof points with metrics)
+
+# 4. Launch opencode
+opencode
+```
+
+The scaffolded `opencode.json` already registers the Geometra MCP (browser automation + PDF generation) and Gmail MCP (reading interview/offer replies), so they launch automatically the first time opencode starts — no `opencode mcp add` step required.
+
+Paste a job URL or run `/job-forge` to see the command menu.
+
+To **upgrade the harness** later:
+
+```bash
+npm update job-forge       # pulls latest razroo/JobForge
+npx job-forge sync         # refresh symlinks if anything drifted
+```
+
+### Path B — Clone the harness directly
+
+Use this if you want to hack on the harness itself (add modes, tune the scoring model, contribute back). Personal files are gitignored.
+
+```bash
+git clone https://github.com/razroo/JobForge.git
+cd JobForge
+npm install
+
+# Add personal files the same way as Path A
+cp config/profile.example.yml config/profile.yml
+cp templates/portals.example.yml portals.yml
+# Create cv.md in the project root
+```
+
+When you're inside this repo, the `postinstall` symlink step is a no-op (detected and skipped). All npm scripts run the harness code directly. The repo's `opencode.json` at the project root registers the same Geometra + Gmail MCPs as the scaffolder ships to consumers.
+
+## Personalization
+
+For structure and section ideas, see the fictional samples in [`examples/`](../examples/) (for example `cv-example.md`, `cv-example-backend-engineer.md`, `cv-example-fullstack-engineer.md`, `cv-example-data-engineer.md`, `cv-example-frontend-engineer.md`, `cv-example-mobile-engineer.md`, `cv-example-devops-engineer.md`, `cv-example-engineering-manager.md`, `cv-example-security-engineer.md`, `cv-example-qa-engineer.md`, `cv-example-solutions-architect.md`, and `cv-example-product-manager.md`).
+
+> **The system is designed to be customized by opencode itself.** Modes, archetypes, scoring weights, negotiation scripts — just ask opencode to change them. See [Customization](CUSTOMIZATION.md).
+
+## Application tracker (optional until first evaluation)
+
+New rows go to **`data/applications/YYYY-MM-DD.md`** day files when the `data/applications/` directory exists. If it does not exist, utilities and the dashboard fall back to **`data/applications.md`** or the repo root **`applications.md`** (same column layout). A fresh setup often has neither the directory nor the file yet; that is normal, and `npx job-forge verify` still exits successfully.
+
+To start with an empty tracker (for example before you paste your first URL), create the directory:
+
+```bash
+mkdir -p data/applications
+```
+
+The first evaluation will create a day file like `data/applications/2026-04-13.md` with this header:
+
+```markdown
+# Applications Tracker
+
+| # | Date | Company | Role | Score | Status | PDF | Report | Notes |
+|---|------|---------|------|-------|--------|-----|--------|-------|
+```
+
+Status values MUST match [templates/states.yml](../templates/states.yml); see the **States** section in [Customization](CUSTOMIZATION.md). After batch evaluations, run `npx job-forge merge` to pull in `batch/tracker-additions/*.tsv` when your workflow uses those files. For the parallel batch runner that produces those additions, see [batch/README.md](../batch/README.md). If the status column has typos, old labels, or bold markers, run `npx job-forge normalize` to rewrite rows toward the canonical set (use `npx job-forge normalize --dry-run` first to preview changes).
+
+## Available commands (opencode)
+
+Use these inside an opencode session in your project (see the skill at `.opencode/skills/job-forge.md` for the full routing logic):
+
+| Action | How |
+|--------|-----|
+| Evaluate an offer | Paste a URL or JD text |
+| Search for offers | `/job-forge scan` |
+| Process pending URLs | `/job-forge pipeline` |
+| Generate a PDF | `/job-forge pdf` |
+| Batch evaluate | `/job-forge batch` |
+| Check tracker status | `/job-forge tracker` |
+| Fill application form | `/job-forge apply` |
+
+## Tracker and scripts (terminal)
+
+From your project root, these commands maintain the tracker and pipeline checks. They do not require opencode. `merge`, `normalize`, and `dedup` exit successfully when the tracker file is missing (same as a fresh setup).
+
+| Action | Command | npm alias |
+|--------|---------|-----------|
+| 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` |
+| 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` |
+| Setup lint (cv.md + profile.yml) | `npx job-forge sync-check` | `npm run sync-check` |
+| Token usage report (from opencode SQLite DB) | `npx job-forge tokens` | `npm run tokens` |
+| Re-create harness symlinks | `npx job-forge sync` | `npm run sync` |
+| Build optional dashboard TUI (Go on `PATH`) | `(cd node_modules/job-forge/dashboard && go build .)` | `npm run build:dashboard` (harness repo only) |
+
+Path B users (cloning the harness) can keep using the shorter `npm run <script>` aliases since the scripts live at the repo root.
+
+## Verify setup
+
+```bash
+npx job-forge verify           # Pipeline integrity. OK if the tracker file does not exist yet; still warns on unmerged batch/tracker-additions/*.tsv — run npx job-forge merge when you intend to fold those rows into the tracker (see batch/README.md)
+npx job-forge sync-check       # Requires cv.md and config/profile.yml
+```
+
+## Build dashboard (optional, Path B only)
+
+The TUI reads the tracker at the JobForge repo root (day files in `data/applications/`, or `data/applications.md`, or root `applications.md`). If you build inside `dashboard/`, point `-path` at the parent directory:
+
+```bash
+cd dashboard
+go build -o job-forge-dashboard .
+./job-forge-dashboard -path ..   # repo root is one level up
+```
+
+From the repo root, `npm run build:dashboard` runs `go build .` inside `dashboard/`.
+
+Path A users who want the dashboard can either clone the harness separately or run the binary from `node_modules/job-forge/dashboard/` after `go build`.
+
+## Token usage tracking
+
+The harness ships a per-session token/cost report that queries opencode's SQLite database:
+
+```bash
+npx job-forge tokens                  # last 7 days
+npx job-forge tokens --days 1         # today only
+npx job-forge tokens --days 1 --append  # append to data/token-usage.tsv
+npx job-forge tokens --session <id>   # drill into one session
+```
+
+Use it to identify which sessions or models are consuming the most tokens. The `opencode.json` shipped with the scaffolder loads only `templates/states.yml` into every session and lets the skill router load mode/data files on demand, which typically keeps per-call input tokens at ~20-40K instead of ~130-170K.
+
+## Troubleshooting
+
+**`npx job-forge verify` succeeds, but `npx job-forge sync-check` fails**  
+`sync-check` requires `cv.md` and `config/profile.yml` with the fields checked in `cv-sync-check.mjs`. Until you finish the profile and CV steps, that is normal.
+
+**PDF generation fails**  
+The scaffolded `opencode.json` already registers Geometra MCP; if it's not running, check `opencode mcp list` and verify the scaffolded config under the `mcp.geometra` key — its `command` MUST be `["npx", "-y", "@geometra/mcp"]` and `enabled: true`. Geometra manages Chromium via its built-in proxy. For standalone CLI usage (outside opencode), `generate-pdf.mjs` also works with standalone Playwright/Chromium — install with `npx playwright install chromium`.
+
+**Symlinks are missing or pointing to a stale path**  
+Run `npx job-forge sync` (or `npm run sync`) to recreate them. This happens if you move the project directory after installing, or if `postinstall` didn't run (rare — check `npm install` output for errors).
+
+**`npx job-forge sync` says "X already exists as a real file/dir — leaving alone"**  
+You or the scaffolder created a real file where the harness wants to put a symlink. If you want to customize that file locally, keep it as-is — the sync script preserves real files. If you want the harness version, delete your local copy and rerun `npx job-forge sync`.
+
+**Dashboard is empty or points at the wrong data**  
+The `-path` argument must be the project root (where `data/applications/` or `data/applications.md` lives), not the `dashboard/` directory.
+
+**`go build` reports `go: command not found` or a version error**  
+Install Go and put it on your `PATH`, or omit the dashboard; everything else runs with Node.js.
+
+**`npx job-forge merge` says there is nothing to merge, but you have TSV files**  
+Only files directly under `batch/tracker-additions/` with a `.tsv` extension are picked up. After a successful merge, rows are merged into the tracker and those files move to `batch/tracker-additions/merged/`, so a second run correctly finds nothing left. If you created TSVs elsewhere or only have files under `merged/`, move or regenerate them in the top-level `tracker-additions` folder (see [batch/README.md](../batch/README.md)).
+
+**A `local:jds/...` line in the pipeline does not resolve**  
+Paths are relative to the project root: create the markdown file under `jds/` and list it in `data/pipeline.md` as `local:jds/{filename}.md` (same spelling as the file name). See [jds/README.md](../jds/README.md) and [`modes/pipeline.md`](../modes/pipeline.md).
+
+## Contributing
+
+Pull requests and issue reports are welcome on `razroo/JobForge`. See [CONTRIBUTING.md](../CONTRIBUTING.md) for branch workflow, ideas (documentation, `examples/`, `templates/portals.example.yml`, dashboard features, utility scripts), and the checks maintainers expect before a PR (`npm run verify` and `npm run build:dashboard`). Contributors work against Path B (clone the harness directly).