tor-to-proposal 2.0.0

package/bin/tor-to-proposal.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// tor-to-proposal: command router. All tools are also directly runnable.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TOOLS = {
+  'pdf-extract': 'pdf-extract.mjs',
+  extract: 'extract.mjs',
+  'cv-gap': 'cv-gap.mjs',
+  'cv-tailor': 'cv-tailor.mjs',
+  'cover-letter': 'cover-letter.mjs',
+  'market-rates': 'market-rates.mjs',
+  'pricing-model': 'pricing-model.mjs',
+  'financial-proposal': 'financial-proposal.mjs',
+  dossier: 'dossier.mjs',
+  simulator: 'simulator.mjs',
+  'template-filler': 'template-filler.mjs',
+  audit: 'audit.mjs',
+  render: 'render.mjs',
+  package: 'package.mjs',
+  'bid-pack': 'bid-pack.mjs',
+  profile: 'profile.mjs',
+  init: 'profile.mjs', // plug-and-play alias: tor-to-proposal init
+};
+
+const DESCRIPTIONS = {
+  'pdf-extract': 'PDF/docx/xlsx -> [[PAGE n]]-tagged text + signals',
+  extract: 'ToR -> tor-extract.json + bid screen + compliance matrix',
+  'cv-gap': 'CV <-> ToR gap analysis (MATCH / GAP-do-not-claim)',
+  'cv-tailor': 'build + lint a ToR-tailored CV (every bullet anchored to the master CV)',
+  'cover-letter': 'lint a drafted cover letter (agent drafts)',
+  'market-rates': 'benchmark scaffold + rate position vs cited band',
+  'pricing-model': 'multi-format rates, every line shows its formula',
+  'financial-proposal': 'client-facing financial proposal from pricing.json (md + xlsx)',
+  dossier: 'client intelligence scaffold',
+  simulator: 'coverage vs evaluation grid -> at-risk points',
+  'template-filler': "fill the client's own docx/xlsx forms",
+  audit: 'pre-submission hard-fail gate',
+  render: 'fallback markdown -> PDF emitter (no document tooling needed)',
+  package: 'verify final docs (re-extract + re-audit) -> pack/ + checklist + zip',
+  'bid-pack': 'one-shot orchestrator: start | apply | pack + the consolidated questionnaire',
+  profile: 'consultant profile wizard (~/.tor-to-proposal/profile.json)',
+  init: 'alias for profile — one-time setup wizard',
+};
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || cmd === 'help' || cmd === '--help') {
+  process.stdout.write(`tor-to-proposal — the bid tool that refuses to lie.\n\nUsage: tor-to-proposal <command> [options]\n\nQuick start (plug and play):\n  tor-to-proposal init                        one-time profile + setup wizard\n  tor-to-proposal bid-pack start --tor tor.pdf --cv cv.txt --dir mybid/\n  tor-to-proposal bid-pack apply --answers answers.json --dir mybid/\n  tor-to-proposal bid-pack pack --dir mybid/ --fallback-pdf\n\nCommands:\n${Object.keys(TOOLS).map((k) => `  ${k.padEnd(19)} ${DESCRIPTIONS[k]}`).join('\n')}\n\nPer-command help: tor-to-proposal <command> --help\nAgent workflow: see SKILL.md\n`);
+  process.exit(cmd ? 0 : 1);
+}
+if (!TOOLS[cmd]) {
+  if (cmd === 'mcp-server') {
+    // npx launch path: "npx tor-to-proposal mcp-server" (stdio MCP)
+    const res = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'mcp', 'server.mjs'), ...rest], { stdio: 'inherit' });
+    process.exit(res.status ?? 1);
+  }
+  process.stderr.write(`unknown command: ${cmd}\n\nRun without arguments to list commands.\n`);
+  process.exit(1);
+}
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), TOOLS[cmd]);
+const res = spawnSync(process.execPath, [script, ...rest], { stdio: 'inherit' });
+process.exit(res.status ?? 1);

package/commands/tor-audit.md

@@ -0,0 +1,10 @@
+---
+description: Pre-submission audit — hard-fail gate before you submit a bid
+allowed-tools: Bash(node:*), Read, Write
+---
+Audit a finished proposal before submission. Proposal: $ARGUMENTS (ask for the compliance matrix path if it exists).
+
+1. `node <plugin-root>/bin/audit.mjs --proposal <file> --matrix <matrix> --extras <cover-letter>`.
+2. HARD FAILS ([FILL] leftovers, incomplete matrix rows): list them, fix what can be fixed from the ToR, ask the user for the rest. Re-run until exit 0.
+3. Review list (untraced claim-shaped sentences): for each, either add a page tag/source or delete the claim — never soften it into vagueness.
+4. Close with the final pre-submission checklist from the skill's references/review-rules.md (submission channel, deadline timezone, file naming).

package/commands/tor-bid.md

@@ -0,0 +1,18 @@
+---
+description: Run the full tor-to-proposal bid pack on a ToR (and CV)
+allowed-tools: Bash(node:*), Read, Write, Glob, Grep
+---
+Run the complete tor-to-proposal bid pack (see the skill's SKILL.md) on: $ARGUMENTS
+
+Follow the four bid-pack phases in order:
+
+1. INTAKE — `bid-pack start --tor <file> [--cv <file>] --dir <bid-dir>`; review bid-screen.md with the user; go/no-go is THEIR call.
+2. QUESTIONNAIRE — put EVERY question from out/questions.md to the user in ONE message. Write answers.json, then `bid-pack apply`. Repeat until 0 open. Never answer for the user.
+3. DRAFT — cover letter (lint to PASS), technical response per criterion (simulator to ~0 at-risk), tailored CV (cv-tailor lint PASS), financial proposal (already rendered by apply).
+4. PACK — render the four PDFs (references/render-specs.md), then `bid-pack pack --dir <bid-dir>`; deliver pack/ + submission-checklist.md.
+
+Hard requirements:
+- Pricing only from user-confirmed numbers (profile confirm or answers.json) — never assume.
+- Every ToR claim carries (p.X); anything unverified stays [FILL].
+- GAP skills from cv-gap must not appear anywhere, including the tailored CV.
+- `bid-pack pack` must exit 0 before you call anything done; it re-audits the rendered bytes.

package/commands/tor-cv.md

@@ -0,0 +1,10 @@
+---
+description: CV vs ToR gap analysis with honest MATCH/GAP verdicts
+allowed-tools: Bash(node:*), Read, Write
+---
+Analyze CV fit against a ToR. ToR: $ARGUMENTS (ask for the CV path if not obvious).
+
+1. Extract the ToR (`pdf-extract` if needed), then `node <plugin-root>/bin/cv-gap.mjs --tor tor.txt --cv cv.txt`.
+2. Present the MATCH/GAP table with page references.
+3. Suggest CV bullet reordering using the ToR's verbatim terminology — facts unchanged, numbers only from the user.
+4. GAP rows: state plainly these must NOT be claimed in the proposal. If a gap is disqualifying, say so as a go/no-go risk.

package/commands/tor-pack.md

@@ -0,0 +1,11 @@
+---
+description: Verify and package a finished bid into the submittable bid pack
+allowed-tools: Bash(node:*), Read, Write, Glob, Grep
+---
+Package the finished bid directory into the verified submission pack: $ARGUMENTS
+
+1. Confirm the four documents exist as markdown in the bid dir (cover-letter.md, cv-tailored.md, technical-proposal.md, financial-proposal.md) and the lints pass (cover-letter lint, cv-tailor lint, simulator ~0 at-risk).
+2. Render each to PDF with your document tooling per references/render-specs.md (cover-letter.pdf, cv-tailored.pdf, technical-proposal.pdf, financial-proposal.pdf). If you have no document tooling, let --fallback-pdf do it.
+3. Run `bid-pack pack --dir <bid-dir>` (add --fallback-pdf only if needed).
+4. If it exits non-zero: fix every hard fail in pack-report.md, re-render, re-run. It removes stale packs on failure — never submit an old pack.
+5. Deliver pack/ + submission-checklist.md + the zip; remind the user pricing.md/pricing.json stay private.

package/commands/tor-price.md

@@ -0,0 +1,11 @@
+---
+description: Honest pricing — cited benchmark band + transparent rate model
+allowed-tools: Bash(node:*), Read, Write
+---
+Price this assignment honestly: $ARGUMENTS
+
+1. `node <plugin-root>/bin/market-rates.mjs scaffold` — have the user (or an approved web search) fill every benchmark row with source + date.
+2. GATE: ask the user to confirm THEIR base rate, loading (0.2–0.35 typical) and contingency (0.05–0.15 typical) before running pricing-model. Never suggest a base rate.
+3. `node <plugin-root>/bin/pricing-model.mjs --base N --basis day --loading L --contingency C --effort D --out-dir out` — present the table with formulas.
+4. Position vs the cited band with market-rates position. Above band → premium justification needed; below band → check the floor.
+5. Remind: the client's financial form governs; template-filler restructures into it.

package/commands/tor-screen.md

@@ -0,0 +1,11 @@
+---
+description: Quick go/no-go screen of a ToR — extract + bid screen + compliance matrix
+allowed-tools: Bash(node:*), Read, Write
+---
+Screen this ToR for a go/no-go decision: $ARGUMENTS
+
+1. `node <plugin-root>/bin/pdf-extract.mjs <file> --out tor.txt` (if the source is PDF/docx/xlsx; scanned → tell the user to OCR, stop).
+2. `node <plugin-root>/bin/extract.mjs --tor tor.txt --out-dir out` (add EV inputs only if the user supplies fee, bid-days, day-rate).
+3. Present: title, client, deadline, duration/effort, evaluation weights + sum check, the go/no-go checklist, red flags — each with its page.
+
+No drafting in this step. End by asking: go or no-go, and which steps to run next (cv-gap, pricing, full bid).

package/docs/PROMPT-GUIDE.md

@@ -0,0 +1,245 @@
+# tor-to-proposal — Prompt Guide for AI Assistants
+
+For people who work **through an AI assistant** — Claude (Desktop/Code),
+ChatGPT, Codex, or any agent — instead of typing CLI commands. Includes setup
+per assistant and **copy-paste prompts for every step**.
+
+The working pattern is always the same:
+**you provide the evidence and the decisions; the assistant runs the tools;
+the tools enforce the honesty rules.** When you see `[FILL]`, that's a
+question addressed to you.
+
+---
+
+## 1. Setup per assistant (one-time)
+
+### Claude Desktop (chat app)
+Settings → Developer → Edit Config → add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "tor-to-proposal": {
+      "command": "npx",
+      "args": ["-y", "tor-to-proposal", "mcp-server"]
+    }
+  }
+}
+```
+Or, if you cloned the repo: `"command": "node", "args": ["/absolute/path/to/tor-to-proposal/mcp/server.mjs"]`.
+Restart the app. Either way, run `npx tor-to-proposal init` once for your profile.
+
+### Claude Code (terminal)
+```bash
+git clone https://github.com/ahaomar/tor-to-proposal && cd tor-to-proposal && npm install
+claude mcp add tor-to-proposal -- node "$(pwd)/mcp/server.mjs"
+```
+Or install as a plugin (skills + `/tor-*` slash commands + MCP in one):
+```bash
+# inside Claude Code:
+/plugin marketplace add ahaomar/tor-to-proposal
+/plugin install tor-to-proposal@tor-to-proposal
+```
+
+### Codex CLI
+`~/.codex/config.toml`:
+```toml
+[mcp_servers.tor-to-proposal]
+command = "node"
+args = ["/absolute/path/to/tor-to-proposal/mcp/server.mjs"]
+```
+
+### ChatGPT
+If your build supports local MCP connectors (desktop developer mode): point a
+connector at the same `server.mjs`. **If not:** skip setup — use the
+"paste-the-text" prompts in §4; everything works from pasted text except
+direct PDF reading (paste the ToR text instead).
+
+### Any other agent (generic)
+Any agent that can (a) read/write local files and (b) run one shell command
+can drive this repo: give it the repo path and say *"follow SKILL.md in that
+folder"*. The SKILL.md is written to be followed by any capable agent.
+
+**Test any setup with:** *"List your tor-to-proposal tools."* → you should see
+twenty tools: `bid_pack_start`, `bid_pack_apply`, `bid_pack_pack`,
+`profile_set`, `profile_get`, `cv_tailor_build`, `cv_tailor_lint`,
+`financial_proposal`, `render_pdf`, `package_bid`, plus the classics:
+`pdf_extract`, `extract_tor`, `cv_gap`, `cover_letter_lint`,
+`market_rates_scaffold`, `market_rates_position`, `pricing_model`, `dossier`,
+`simulate`, `template_filler`, `audit`.
+
+---
+
+## 2. The one-prompt start (full workflow)
+
+Paste this, with your paths filled in:
+
+```text
+I am bidding on a consultancy. Run the full tor-to-proposal bid pack
+(SKILL.md) with me. My files:
+- ToR: /Users/me/bids/undp-2026-042/tor.pdf
+- CV:  /Users/me/bids/undp-2026-042/cv.txt
+- Bid folder: /Users/me/bids/undp-2026-042/bid
+
+Rules for you:
+- Start with bid_pack_start, then show me the bid screen — I decide go/no-go.
+- Then put EVERY question from out/questions.md to me in ONE message. I answer
+  once; write my answers to answers.json and run bid_pack_apply. Repeat until
+  zero open. Never invent an answer, never ask questions one by one.
+- Drafts get linted/simulated/audited with the tools; fix and loop until they pass.
+- Finish with the four PDFs rendered per references/render-specs.md and
+  bid_pack_pack. Deliver pack/ + submission-checklist.md. Nothing is "done"
+  while pack exits non-zero.
+```
+
+The assistant runs the mechanical pipeline, shows the bid screen, then asks
+**one consolidated questionnaire**. Answer in plain English; it does the tool
+work and writes `answers.json` for you.
+
+---
+
+## 3. Step-by-step prompt library
+
+Run them one at a time if you prefer control (recommended for your first bid).
+
+**The bid pack in three beats (recommended):**
+```text
+1. Start the bid pack on /path/tor.pdf + /path/cv.txt (bid_pack_start) and
+   walk me through the bid screen. Wait for my go/no-go.
+2. Give me the consolidated questionnaire (out/questions.md) — all questions,
+   numbered, one message. I'll answer inline; transcribe to answers.json and
+   run bid_pack_apply until zero open.
+3. Draft the cover letter + technical response, lint/simulate to PASS, then
+   render the four PDFs and run bid_pack_pack. Show me pack-report.md.
+```
+
+**Screen a ToR (go/no-go):**
+```text
+Screen this ToR for a go/no-go decision: /path/tor.pdf. Give me the one-page
+bid screen: title, reference, deadline, duration/effort, evaluation criteria
+with weights, red flags. Ask me for EV inputs (expected fee, bid days, my day
+rate) if you want to show expected value. No drafting yet.
+```
+
+**CV reality check:**
+```text
+Compare my CV (/path/cv.txt) against the extracted ToR. Show the MATCH/GAP
+table with page numbers. Be blunt about GAP rows — I want to know what I must
+not claim. Then suggest how to reorder my CV bullets using the ToR's own
+terminology, without changing any facts.
+```
+
+**Pricing (the gated one):**
+```text
+Help me price this. My floor numbers: minimum net income $[X] per year,
+realistic billable days [Y], overhead/loading about [Z]%. First scaffold the
+benchmark table; research UNDP/UNICEF fee grids and UNGM award notices for
+[this sector] in [region] and give me each band WITH source URL + access date
+— no uncited numbers. Then run the pricing model with my confirmed inputs and
+show every formula. Finally position my rate against the cited band.
+```
+*(If you don't allow web search, the assistant must leave benchmark rows as
+[FILL] and give you the table to fill. That is correct behavior — don't push it.)*
+
+**Cover letter:**
+```text
+Draft a one-page cover letter per assets/templates.md: verbatim title + ref +
+deadline block, 2-sentence understanding from Background/Objectives only, fit
+section quoting 3–5 JD requirements (p.X) with my CV evidence — mark [FILL]
+where I haven't given you evidence yet — compliance declarations, availability
+per the ToR start date. Then lint it with cover_letter_lint and fix everything
+it flags. No superlatives.
+```
+
+**Technical response + self-score:**
+```text
+Draft the technical response: one section per scored criterion, highest weight
+first, in the client's vocabulary, every deliverable addressed. Extract the
+sub-elements of each criterion verbatim into sub-elements.json, then run
+simulate and give me the at-risk points. Loop with me: rewrite the weakest
+criterion, re-simulate, until at-risk ≈ 0.
+```
+
+**Their forms:**
+```text
+Fill the client's financial form (/path/financial-form.xlsx) using
+template_filler: map first and show me every field, fill from pricing.json +
+tor-extract.json (build data.json so labels match exactly), then check. If any
+field stays [FILL], list what you need from me. Never touch their formulas.
+```
+
+**Final gate:**
+```text
+Run the audit on my final files (proposal, cover letter, compliance matrix).
+If it exits non-zero, list the hard fails, fix what you can from the ToR, and
+ask me for the rest. Then run it again until it passes. Finish with the
+pre-submission checklist (submission channel, deadline timezone, file naming).
+```
+
+**Record the outcome (later):**
+```text
+Record this bid in my library per library/SCHEMA.md: outcome [won/lost],
+fee quoted [X], any evaluator feedback I paste below. Local only.
+```
+
+---
+
+## 4. Paste-the-text variant (no file access — e.g. plain ChatGPT web)
+
+If your assistant cannot read local files, paste content directly:
+
+```text
+You are enforcing the tor-to-proposal honesty rules on the text I paste:
+1) Every claim about the assignment must cite "p.X" of the ToR text below or
+   stay [FILL]. 2) Never claim skills absent from my CV. 3) No pricing without
+   asking me first for my floor numbers. 4) No superlatives.
+
+=== ToR text ===
+[paste the full ToR text, or use the pdf-extract output]
+
+=== My CV ===
+[paste CV]
+```
+
+Then use the same step prompts from §3, replacing file paths with "the ToR
+text above". You lose automatic lint/simulate runs — so end with:
+
+```text
+Before I submit: list every sentence in my drafts that violates the rules
+above, with the fix. Act as the audit tool yourself, and be harsh.
+```
+
+---
+
+## 5. What the assistant will ask you (have answers ready)
+
+- **Go/no-go gates:** Can you staff it by their start date? Is the EV
+  positive at a realistic win probability? Any eligibility conflicts?
+- **Pricing gate (mandatory):** your minimum income, billable days, loading %,
+  contingency % — *your* numbers, not its suggestions.
+- **[FILL] questions:** evidence for each fit claim (years, budgets, client
+  names), references, registration status (UNGM etc.).
+- **Form fields:** anything their template demands that no ToR section states.
+
+If it ever fills a `[FILL]` without asking, or produces a number with no
+formula or source, reply: *"No invented values — mark it [FILL] and ask me."*
+Then start a fresh session if it keeps drifting; the tools, not the vibes,
+are the source of truth.
+
+---
+
+## 6. A real exchange, so you know what "good" looks like
+
+> **You:** Screen /Users/me/bids/tor.pdf — should I bid?
+>
+> **Assistant:** Extracted 4 pages, 3 evaluation criteria (weights 15/30/25,
+> sum 70 matches stated total). Deadline 12 Oct 2026 (p.2), effort ~20
+> person-days (p.2), UNGM registration required before award (p.4).
+> Red flags: none in the weights; validity 90 days (p.2) is standard.
+> EV check — I need your inputs: expected fee, days to prepare the bid, your
+> day rate. I won't assume them.
+>
+> **You:** fee ~9,500, bid takes 3 days, my rate 400.
+>
+> **Assistant:** EV at P(win)=0.5 → +$3,550; at 0.25 → −$250. At your realistic
+> win rate this is worth pursuing only if the CV fit is strong. Running
+> cv-gap next? Note: I will not draft anything until you call go/no-go.

package/docs/TECHNICAL-GUIDE.md

@@ -0,0 +1,211 @@
+# tor-to-proposal — Technical Guide
+
+For developers, IT support, and AI engineers deploying/ extending the tool.
+Companion to `USER-GUIDE.md` (end users) and `PROMPT-GUIDE.md` (agent users).
+
+---
+
+## 1. Architecture
+
+```
+                      ┌────────────────────────────────────────────┐
+  surfaces            │  CLI (bin/tor-to-proposal.mjs router)      │
+  ─────────           │  Agent skill (SKILL.md, read by the model) │
+                      │  MCP stdio server (mcp/server.mjs)         │
+                      │  Claude Code plugin (commands/ + .mcp.json)│
+                      └───────────────┬────────────────────────────┘
+                                      │ spawn
+                      ┌───────────────▼────────────────────────────┐
+  deterministic core  │  bin/*.mjs — parse, compute, gate, lint    │
+                      │  (no LLM calls, no network; pure Node ≥18) │
+                      └───────────────┬────────────────────────────┘
+                                      │ reads/writes
+                      ┌───────────────▼────────────────────────────┐
+  data                │  [[PAGE n]]-tagged text · tor-extract.json │
+                      │  pricing.json · client docx/xlsx (read-only│
+                      │  structure) · library/bids/ (win/loss)     │
+                      └────────────────────────────────────────────┘
+```
+
+**The agent/tool contract** (also in SKILL.md): deterministic tools parse,
+compute, gate and lint; the agent drafts and does fuzzy extraction; every
+agent-produced value must carry page attribution to be accepted (`extract.mjs
+--json`), and every draft must pass the lint/simulate/audit gates. An LLM
+alone invents; regex alone can't read a ToR; the pair is the product.
+
+## 2. Install variants
+
+| Variant | Command / config | Audience |
+| --- | --- | --- |
+| Agent skill | `npx skills add ahaomar/tor-to-proposal` (skills.sh) | Claude Code, ZCode, any skill-aware agent |
+| Claude Code plugin | `/plugin marketplace add ahaomar/tor-to-proposal` → `/plugin install tor-to-proposal@tor-to-proposal` | Claude Code users (skill + `/tor-*` commands + MCP) |
+| MCP server | `claude mcp add tor-to-proposal -- node /abs/path/mcp/server.mjs`; Claude Desktop JSON; Codex `~/.codex/config.toml` `[mcp_servers.tor-to-proposal]` | Claude Desktop, Codex, ChatGPT (local connectors) |
+| Standalone CLI | `git clone … && npm install`; `node bin/tor-to-proposal.mjs <cmd>` | CI, scripts, terminal users |
+
+Deps (all local, pure JS): `unpdf` (pdf.js), `mammoth` (docx), `exceljs`
+(xlsx), `adm-zip` (docx zip). Node ≥ 18. No telemetry, no network calls.
+
+## 3. CLI reference
+
+Router: `node bin/tor-to-proposal.mjs <command> [options]` (each tool also
+runs directly). Exit codes everywhere: **0** ok · **1** validation failure /
+hard-fail gate · **2** cannot-process (scanned PDF, inverted band, refused
+formula overwrite) · **3** dependencies missing.
+
+| Command | Key options | Outputs |
+| --- | --- | --- |
+| `bid-pack start` | `--tor file [--cv file] [--dir bid/] [--no-cv-tailor]` | runs pdf-extract → extract → cv-gap → cv-tailor; `out/questions.{json,md}` (consolidated questionnaire), `out/bid-state.json`, `out/bid-context.json` |
+| `bid-pack apply` | `--answers answers.json [--dir bid/]` | records answers; runs pricing + financial proposal on user numbers; `out/cv-evidence.json`, `out/fill-answers.json`, `out/clarifications.md`; regenerates questions |
+| `bid-pack pack` | `--dir bid/ [--fallback-pdf] [--no-zip]` | delegates to `package` |
+| `profile` (`init`) | `init \| set k=v… \| get [k] \| path \| erase` | `~/.tor-to-proposal/profile.json` — user-supplied identity, floor math, rate defaults, master-CV path |
+| `cv-tailor build` | `--cv master.txt --extract tor-extract.json [--profile p.json] [--gap r.md]` | `cv-tailored.md` (reordered master-CV material only) + `cv-tailor-report.md` (trace + terminology mirror) |
+| `cv-tailor lint` | `--cv tailored.md --master master.txt [--gap] [--evidence cv-evidence.json]` | anchor table; exit 1 on unanchored bullets, altered numbers, GAP terms |
+| `financial-proposal` | `--pricing pricing.json --extract tor-extract.json [--context bid-context.json] [--xlsx]` | `financial-proposal.md` (+ `.xlsx` with visible formulas: `D8=B8*C8`, `D10=SUM`) |
+| `render` | `input.md --out out.pdf [--footer text]` | plain submittable PDF (fallback tier; pure JS, WinAnsi text layout) |
+| `package` | `--dir bid/ [--fallback-pdf] [--no-zip]` | re-extracts rendered PDF/docx/xlsx → re-runs audit on those bytes; `pack/` + `pack-report.md` + `submission-checklist.md` + `deadline.ics` + `<ref>-bid-pack.zip`; exit 1 removes stale packs |
+| `pdf-extract` | `file`, `--out`, `--signals`, `--allow-scanned` | `[[PAGE n]]`/`[[SHEET n]]` text; signals JSON (scannedLikely, hasEvaluationTable…) |
+| `extract` | `--tor`, `--json agent.json`, `--fee/--bid-days/--day-rate`, `--out-dir` | `tor-extract.json`, `bid-screen.md` (EV table), `compliance-matrix.md` |
+| `cv-gap` | `--tor`, `--cv`, `--out` | match table, MATCH / "GAP — do not claim" |
+| `cover-letter lint` | `lint --draft`, `--cv`, `--gap`, `--max-words` | lint report; exit 1 lists line-numbered violations |
+| `market-rates scaffold` | `--title`, `--currency` | research table — zero numbers, all `[FILL]` rows |
+| `market-rates position` | `--your-rate --benchmark-low --benchmark-high` | BELOW/WITHIN/ABOVE + advisory; exit 2 if low ≥ high |
+| `pricing-model` | `--base --basis hour|day|week|month --loading --contingency --effort --weeks --out-dir` | `pricing.json`, `pricing.md` (formula per line) |
+| `dossier` | `--client --sector --out` | dossier scaffold with type preset |
+| `simulator` | `--extract --response --sub-elements --out` | at-risk pts per criterion, missing sub-elements, priorities |
+| `template-filler map/fill/check` | `--template file.docx|.xlsx --data map.json --out --report` | fill-report.md (every write + trace); check exits 1 while fields unmapped |
+| `audit` | `--proposal --matrix --extras … --report` | hard-fail list + untraced-claim review; exit 1 = do not submit |
+
+## 4. Data contracts
+
+**Page-tag protocol** — the substrate: `[[PAGE n]]` before each PDF/docx
+page's text; `[[SHEET n: Name]]` for xlsx. `lib.mjs#pageOf(text, index)`
+attributes any match to its page. All citation output is `(p.n)` or
+`[[PAGE n]]`; the universal placeholder is `[FILL…]`.
+
+**`tor-extract.json`** (extract.mjs):
+```jsonc
+{
+  "referenceNumber": { "value": "UNDP-RFP-2026-042", "page": 1 },
+  "deadline": { "value": "12 October 2026", "page": 2 },
+  "evaluation": {
+    "criteria": [ { "label": "…", "weight": 30, "page": 3 } ],
+    "weightsSum": 70, "statedTotal": 70,
+    "weightsSumCheck": "ok | MISMATCH (…) — surface, never fix | not-stated"
+  },
+  "paymentTerms": [ { "value": "…", "page": 4 } ],
+  "conflicts": []   // regex vs agent-field conflicts, recorded not hidden
+}
+```
+
+**Agent field merge (`--json`)** — `{"field": {"value": …, "page": n}}`.
+Agent values are accepted **only** with page attribution; arrays must be
+fully attributed; conflicts land in `conflicts[]`.
+
+**`pricing.json`** — `{inputs (userSupplied: true), constants {8h, 5d, 4.33},
+rates {hour, day, week, month}, loadedDay, quoteFloorDay, lumpSum,
+assignmentTotal}` — consumed by template-filler via a label-mapped `data.json`.
+
+**`sub-elements.json`** (simulator) — `{ "criterion label": ["verbatim
+sub-element", …] }` — agent-extracted from the ToR; labels must match
+tor-extract criteria exactly.
+
+**v2 bid-pack contracts** (all under `<bid-dir>/out/`):
+
+- **`~/.tor-to-proposal/profile.json`** — `{identity{name,credentials,…},
+  rates{floor{annualIncome,billableDays,costLoading},
+  defaults{base,basis,currency,loading,contingency}}, cv{masterPath}}`.
+  Every value user-supplied (`profile set` validates numbers/ranges and the
+  master-CV path exists). This file is the "user input" trace source.
+- **`questions.json`** — `{generatedAt, dir, openCount, items:[{id, area,
+  type, question, why, default?, answer, answerSource}]}`. Ids are stable:
+  `Q-PRICING-BASE/LOADING/CONTINGENCY/CURRENCY`, `Q-PRICING-CONFIRM`,
+  `Q-EFFORT-DAYS`, `Q-AVAILABILITY`, `Q-VALIDITY`, `Q-FILL-CONSULTANT/
+  REIMBURSABLES/TAXES` (generated slots), `Q-FILL-<md5-8>` (draft fills —
+  hash of file+excerpt so a fixed draft drops its question),
+  `Q-CVE-<n>` (CV evidence), `Q-CLAR-*` (client clarifications).
+- **`answers.json`** (user-written via the agent) — flat `{id: value}`.
+- **`bid-context.json`** — derived: identity/consultantLine, refNo, title,
+  deadline, currency, availabilityDate, validity, reimbursables, taxes.
+  Input to financial-proposal and the pack checklist.
+- **`cv-evidence.json`** — `[{id, text, source:"user-input", deleted?}]` —
+  the ONLY way an unanchored line may enter the tailored CV.
+- **`fill-answers.json`** — `[{id, answer, source}]` — trace of draft-fill answers.
+- **`bid-state.json`** — `{steps:{torExtract,structured,cvGap,cvTailored,
+  questions,pricing:{status}}, createdAt, updatedAt}` — resumability.
+- **Pack outputs** — `<bid-dir>/pack/` (canonical names Cover-Letter.*,
+  CV.*, Technical-Proposal.*, Financial-Proposal.* + client forms +
+  submission-checklist.md + deadline.ics), `<bid-dir>/pack-report.md`,
+  `<bid-dir>/<ref>-bid-pack.zip`. `pricing.md`/`pricing.json` are NEVER
+  copied into the pack (floor math stays private).
+
+**`library`** — `library/bids/<ref>/`: `tor-extract.json` (frozen),
+`outcome.json`, `feedback.md`, `rate-band.json`. See `library/SCHEMA.md`;
+aggregation only at n ≥ 10 with n + date.
+
+## 5. MCP server details
+
+`mcp/server.mjs` — dependency-free MCP **stdio** server (JSON-RPC 2.0,
+newline-delimited). Methods: `initialize`, `notifications/*`, `ping`,
+`tools/list` (21 tools), `tools/call`. Tool args are camelCase and mapped to
+CLI flags; array args flatten to repeated flags (`audit.extras`,
+`profile_set.pairs`).
+`tools/call` results carry stdout + stderr and `isError: true` on any non-zero
+exit (a hard-fail gate therefore surfaces as a tool error the agent must read).
+Host cwd is not the repo: tool descriptions mandate absolute paths. Adding a
+tool = one entry in the `TOOLS` array (name, description, JSON-schema,
+`argv(a)` mapper, script). `npx tor-to-proposal mcp-server` launches the same
+server for npx-installed users.
+
+## 6. Claude Code plugin
+
+`.claude-plugin/plugin.json` + `marketplace.json` make the repo installable
+via `/plugin marketplace add`; `commands/*.md` are slash commands
+(`tor-bid` — full bid pack, `tor-pack` — verify + package, `tor-screen`,
+`tor-cv`, `tor-price`, `tor-audit`) that reference
+`<plugin-root>` paths; `.mcp.json` registers the MCP server with
+`${CLAUDE_PLUGIN_ROOT}` so npm-installed binaries resolve inside the plugin.
+
+## 7. Extension points
+
+- **New donor pack**: `references/packs/<donor>.md` — conventions + what to
+  verify; linked from SKILL.md's read-on-demand list. No code changes.
+- **New requirement pattern** (cv-gap): extend the arrays in `bin/cv-gap.mjs`
+  (`DOMAINS`, `CLIENTS`, `CERTS`, `SOFT`, `LANGS`).
+- **New tool**: follow `bin/pricing-model.mjs` as the pattern (lib helpers,
+  `--help`, strict arg validation, exit codes, `[FILL]`-discipline) + wire into
+  router `TOOLS` map, MCP `TOOLS` array, and the test suite.
+- **Richer evaluation parsing**: prefer contributing ToR samples to the
+  fixtures; keep the weights-sum cross-check as the integrity anchor.
+
+## 8. Testing
+
+`npm test` — zero test dependencies, spawns the real CLI (39 tests):
+extraction + weights-sum, pricing arithmetic, band inversion rejection, CV-gap
+honesty, lint pass/fail, simulator at-risk math, docx/xlsx fill + formula
+preservation (verified by re-reading the filled files), audit gate, OCR path,
+**profile set/get/erase + validation rejections (isolated $HOME), cv-tailor
+build + lint (honest pass; invented number, GAP term, and evidence-rescued
+lines), financial proposal md+xlsx formulas, the pure-JS PDF renderer
+(round-tripped through unpdf, multipage), the full bid-pack lifecycle
+(start → questions → apply → pricing → pack happy path), the pack failure
+path ([FILL] survives rendering → exit 1 + stale pack removal), the profile
+one-keystroke confirm path, and an MCP round-trip (handshake → tools/list
+with all 10 v2 tools → profile_set/get → audit hard-fail as isError)**.
+Fixtures in `test/fixtures/`; runtime binaries built into `test/.tmp/`;
+profile-dependent tests run with `$HOME` pointed at the temp dir so a real
+profile is never touched.
+
+## 9. Trust model
+
+- All parsing/computation is local; no tool makes network calls. The only
+  outbound step is market-rate research, run explicitly by/for the user.
+- Client templates are opened read-only in structure terms: only mapped cells
+  are written; formulas are never overwritten (refused with exit 2).
+- `library/bids/` is gitignored; corpus analytics are opt-in, n ≥ 10, always
+  dated.
+- The gates are the guarantee: a draft that skips lint/simulate/audit is, by
+  definition, not produced by this workflow.
+- The pack gate applies to the **rendered bytes**: `package.mjs` re-extracts
+  the text of every final PDF/docx/xlsx and re-runs the audit on that text, so
+  what is verified is what the client reads. On failure the previous pack/ and
+  zip are deleted — a stale pack can never survive next to a failing bid.