tor-to-proposal 2.0.1 → 2.1.0

package/SKILL.md

@@ -82,9 +82,13 @@ Go/no-go is THEIR call. If no-go: stop and say so.
 ### Phase 2 — The ONE questionnaire (no scattered questions, ever)
 
 `out/questions.md` consolidates every open decision: pricing, availability,
-validity, draft `[FILL]`s, CV evidence. **Put all of them to the user in one
-message**, grouped. Never drip-feed questions and never answer one for the
-user. Then:
+validity, draft `[FILL]`s, CV evidence. Two routes, in order of preference:
+
+1. **Interactive wizard (non-technical users):** `node bin/bid-pack.mjs ask
+   --dir <bid-dir>` — asks each open question in the terminal, saves
+   answers.json and applies it. Run again; it only asks what is still open.
+2. **Assistant-mediated:** put all questions to the user in one message,
+   never answer one for the user, then:
 
 ```bash
 # write the answers verbatim:

package/bin/bid-pack.mjs

@@ -5,6 +5,9 @@
 //
 //   start  --tor <file> [--cv <file>] [--dir bid/]   extract + screen + cv-gap
 //          + cv-tailor build + profile import -> questions.json/questions.md
+//   ask    [--dir bid/]                              interactive wizard: answers
+//          the open questions one at a time in the terminal, writes answers.json
+//          and applies them (no editor or JSON knowledge needed)
 //   apply  --answers answers.json [--dir bid/]       store answers, run pricing,
 //          record evidence + fill answers, regenerate the open-question list
 //   pack   [--dir bid/] [--fallback-pdf] [--no-zip]  verify + audit + zip (-> package.mjs)
@@ -14,6 +17,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import readline from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { fail, parseArgs, readText, writeOut, helpText, mdTable } from './lib.mjs';
@@ -21,19 +25,23 @@ import { loadProfile, profilePath } from './profile.mjs';
 
 const HELP = helpText('bid-pack', [
   'start  --tor <file.(pdf|docx|txt)> [--cv <file>] [--dir bid/] [--profile] [--no-cv-tailor]',
+  'ask    [--dir bid/]',
   'apply  --answers answers.json [--dir bid/]',
   'pack   [--dir bid/] [--fallback-pdf] [--no-zip]',
   '',
   'start runs every mechanical step (pdf-extract -> extract -> cv-gap -> cv-tailor)',
   'and consolidates ALL open questions into out/questions.md. Answer them in one go,',
   'have your assistant write answers.json, then apply. Repeat apply until 0 open.',
+  'ask is the human-friendly route: an interactive wizard that asks each open',
+  'question in the terminal (Enter = suggested default, "back" to redo, "quit" to',
+  'cancel), saves answers.json and applies it — no editor or JSON needed.',
   'pack verifies the final documents (re-extract + re-audit) and builds the zip.',
 ]);
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._[0];
-if (args.__help || !['start', 'apply', 'pack'].includes(cmd)) {
+if (args.__help || !['start', 'ask', 'apply', 'pack'].includes(cmd)) {
   process.stdout.write(HELP);
   process.exit(args.__help ? 0 : 1);
 }
@@ -144,6 +152,21 @@ function writeQuestions(q) {
   writeOut(path.join(outDir, 'questions.md'), md);
 }
 
+// Human-readable PDF companions for the working files a non-technical user is
+// most likely to be pointed at (regenerated after start/apply; the .md stays
+// the source of truth — the PDFs are for reading, not editing).
+function renderPreviews() {
+  for (const [file, label] of [
+    ['bid-screen.md', 'Bid-Screen'],
+    ['questions.md', 'Questions'],
+    ['cv-gap-report.md', 'CV-Gap-Report'],
+    ['cv-tailor-report.md', 'CV-Tailor-Report'],
+  ]) {
+    if (!inDir(file)) continue;
+    run('render.mjs', [path.join(outDir, file), '--out', path.join(outDir, 'preview', `${label}.pdf`), '--footer', `preview of out/${file} — the .md file is the source of truth`], { label: `render preview ${label}` });
+  }
+}
+
 // ---------------- context ----------------
 function writeContext() {
   const extractPath = inDir('tor-extract.json');
@@ -214,6 +237,7 @@ function start() {
   writeQuestions(q);
   state.steps.questions = { status: 'done', open: q.openCount };
   writeState(state);
+  renderPreviews();
 
   // report
   const extract = JSON.parse(fs.readFileSync(path.join(outDir, 'tor-extract.json'), 'utf8'));
@@ -226,7 +250,8 @@ function start() {
       `- bid-screen.md — go/no-go decision (the USER decides; read it together)\n` +
       `- compliance-matrix.md, tor-extract.json\n` +
       (args.cv ? `- cv-gap-report.md, cv-tailored.md (+ report)\n` : '') +
-      `- questions.json / questions.md — **${q.items.length} open question(s)**\n\n` +
+      `- questions.json / questions.md — **${q.items.length} open question(s)**\n` +
+      `- preview/ — readable PDFs of the bid screen + questionnaire (just double-click)\n\n` +
       `## Next\n1. Review bid-screen.md with the user. No-go -> stop here.\n` +
       `2. Put every open question to the user IN ONE MESSAGE (questions.md has them).\n` +
       `3. Write answers.json {"Q-...": value, ...} -> bid-pack apply --answers answers.json --dir ${dir}\n` +
@@ -238,7 +263,11 @@ function start() {
 
 // ---------------- apply ----------------
 function apply() {
-  if (!args.answers) { process.stdout.write(HELP); process.exit(1); }
+  if (!args.answers) {
+    process.stdout.write(HELP);
+    process.stdout.write(`\nTip: run "bid-pack ask --dir ${dir}" to answer the open questions interactively in this terminal — no JSON file needed.\n`);
+    process.exit(1);
+  }
   const answersPath = path.resolve(String(args.answers));
   const answers = JSON.parse(readText(answersPath, '--answers'));
   const qPath = inDir('questions.json');
@@ -326,6 +355,7 @@ function apply() {
   state.steps.questions = { status: 'done', open: fresh.openCount };
   state.steps.pricing = { status: inDir('pricing.json') ? 'done' : 'awaiting-user-numbers' };
   writeState(state);
+  renderPreviews();
 
   process.stdout.write(
     `# Apply: ${applied} answer(s) recorded, ${fresh.openCount} still open\n\n` +
@@ -335,6 +365,85 @@ function apply() {
   );
 }
 
+// ---------------- ask (interactive question wizard) ----------------
+async function askWizard() {
+  const qPath = inDir('questions.json');
+  if (!qPath) fail(`no questions.json in ${dir}/out — run: bid-pack start --tor <file> --dir ${dir}`, 2);
+  const q = JSON.parse(fs.readFileSync(qPath, 'utf8'));
+  const yours = q.items.filter((i) => i.type !== 'client');
+  const clients = q.items.filter((i) => i.type === 'client');
+  if (!yours.length) {
+    process.stdout.write(
+      (clients.length
+        ? `Nothing for you to answer here — but send these to the CLIENT before the cutoff:\n${clients.map((c) => `- ${c.question}`).join('\n')}\n`
+        : 'No open questions — everything is already resolved.\n') +
+        (inDir('pricing.json') ? `\nNext: bid-pack pack --dir ${dir} [--fallback-pdf]\n` : '')
+    );
+    return;
+  }
+
+  // Same terminal behavior as the profile wizard: interactive when run by a
+  // human; piped lines are consumed in order (automation/tests).
+  const piped = !process.stdin.isTTY;
+  let pipedLines = [];
+  if (piped) {
+    try {
+      const raw = fs.readFileSync(0, 'utf8');
+      pipedLines = raw.trim() ? raw.split('\n').map((l) => l.trim()) : [];
+    } catch { /* empty stdin */ }
+  }
+  let pipedPos = 0;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const askLine = async (prompt) => {
+    if (piped) return pipedPos < pipedLines.length ? pipedLines[pipedPos++] : 'EOF';
+    try {
+      return (await rl.question(prompt)).trim();
+    } catch (err) {
+      if (err && (err.code === 'ABORT_ERR' || err.name === 'AbortError')) return 'EOF';
+      throw err;
+    }
+  };
+
+  process.stdout.write(
+    `Bid questions — ${yours.length} to answer, one at a time.\n` +
+      'Press Enter to accept the [suggested] value when one is shown. Type "back" to redo the previous question, "quit" to cancel.\n\n'
+  );
+
+  const answers = {};
+  let i = 0;
+  while (i < yours.length) {
+    const item = yours[i];
+    const cur = item.default !== undefined && item.default !== null ? String(item.default) : '';
+    const tail = item.unit ? ` (${item.unit})` : '';
+    const a = await askLine(`(${i + 1}/${yours.length}) ${item.question}${tail}${cur ? ` [${cur}]` : ''}\n> `);
+    if (a === 'EOF' || a.toLowerCase() === 'quit') {
+      rl.close();
+      process.stdout.write('\nCancelled — nothing was saved. (Your documents are untouched; run bid-pack ask again anytime.)\n');
+      return;
+    }
+    if (a.toLowerCase() === 'back') {
+      if (i === 0) { process.stdout.write('  (already at the first question)\n'); continue; }
+      const prev = yours[i - 1];
+      delete answers[prev.id];
+      i -= 1;
+      continue;
+    }
+    if (a === '' && cur === '') {
+      process.stdout.write('  This one needs an answer from you (no suggested default). Type it, or "quit" to stop.\n');
+      continue;
+    }
+    answers[item.id] = a === '' ? item.default : a;
+    i += 1;
+  }
+  rl.close();
+
+  const answersPath = path.join(dir, 'answers.json');
+  fs.writeFileSync(answersPath, JSON.stringify(answers, null, 2));
+  process.stdout.write(`\nSaved your ${Object.keys(answers).length} answer(s) to ${answersPath}\nApplying them now...\n\n`);
+  args.answers = answersPath;
+  apply();
+}
+
 // ---------------- pack ----------------
 function pack() {
   const passThrough = ['--dir', dir, ...(args['fallback-pdf'] ? ['--fallback-pdf'] : []), ...(args['no-zip'] ? ['--no-zip'] : []), ...(args.profile ? ['--profile', String(args.profile)] : [])];
@@ -343,5 +452,6 @@ function pack() {
 }
 
 if (cmd === 'start') start();
+else if (cmd === 'ask') await askWizard();
 else if (cmd === 'apply') apply();
 else pack();

package/bin/profile.mjs

@@ -127,7 +127,8 @@ async function wizard() {
   let pipedLines = [];
   if (piped) {
     try {
-      pipedLines = fs.readFileSync(0, 'utf8').split('\n').map((l) => l.trim());
+      const raw = fs.readFileSync(0, 'utf8');
+      pipedLines = raw.trim() ? raw.split('\n').map((l) => l.trim()) : [];
     } catch { /* empty stdin -> quit below */ }
   }
   let pipedPos = 0;

package/bin/tor-to-proposal.mjs

@@ -39,14 +39,14 @@ const DESCRIPTIONS = {
   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',
+  'bid-pack': 'one-shot orchestrator: start | ask | apply | pack + the consolidated questionnaire',
   profile: 'consultant profile wizard (.tor-to-proposal/profile.json in the current folder)',
   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.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 ask --dir mybid/   answer open questions interactively\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]) {

package/docs/USER-GUIDE.md

@@ -193,6 +193,82 @@ you will ever own.
 
 ---
 
+## 6b. How to answer the questions (`out/questions.md` → `answers.json`)
+
+After `bid-pack start`, the tool writes **`out/questions.md`** — a numbered
+table of everything it cannot decide for you (your price confirmation, effort
+days, availability date, and every `[FILL]` placeholder it found).
+
+**You do not edit questions.md itself.** You answer in one of three ways:
+
+### Way 1 (easiest, no editor needed): the terminal wizard
+
+```bash
+npx tor-to-proposal bid-pack ask --dir .
+```
+
+It asks every open question **one at a time, right in the Terminal** — exactly
+like the `init` wizard. Press Enter to accept a suggested value, type `back`
+to redo the previous question, `quit` to stop. At the end it saves your
+answers and applies them automatically. Run it again anytime; it only asks
+what is still open.
+
+### Way 2: reply to your AI assistant
+questions.md ends with the exact instruction. Just type your numbered answers
+in the chat, e.g.:
+
+```
+1. yes
+2. 25 person-days
+3. 1 November 2026
+4. 90 days from submission
+```
+
+The assistant writes them into `answers.json` for you and runs
+`bid-pack apply`.
+
+### Way 3 (by hand): write answers.json yourself
+Create a file called `answers.json` **in your bid folder** (next to
+`tor.pdf`). It is a simple JSON object: **question ID → your answer**.
+Copy the IDs exactly from `out/questions.json` or the **bold** codes in
+questions.md. A complete sample:
+
+```json
+{
+  "Q-PRICING-CONFIRM": "yes",
+  "Q-EFFORT-DAYS": "25 person-days",
+  "Q-AVAILABILITY": "1 November 2026",
+  "Q-VALIDITY": "90 days from submission",
+  "Q-FILL-TAXES": "Prices exclude VAT; consultant is registered with FBR.",
+  "Q-FILL-REIMBURSABLES": "Travel and interpretation costs are reimbursable at cost against receipts.",
+  "Q-CVE-1": "Led three UNDP M&E assignments (2022–2025) as team lead.",
+  "Q-CLAR-1": "Requested the final evaluation grid by email on 3 Oct 2026."
+}
+```
+
+What the special IDs mean:
+
+| ID pattern | Meaning | What to answer |
+| --- | --- | --- |
+| `Q-PRICING-CONFIRM` | Your saved profile rate offered for this bid | `yes` to use it, or new numbers: `"base 420 loading 0.25 contingency 0.1"` |
+| `Q-EFFORT-DAYS` | Person-days you will quote | e.g. `"25 person-days"` |
+| `Q-AVAILABILITY` | When you can start | any honest date |
+| `Q-VALIDITY` | How long your offer stays valid | e.g. `"90 days from submission"` |
+| `Q-FILL-...` | A `[FILL]` box in a draft document | the real fact that belongs there |
+| `Q-CVE-n` | A CV line needs proof (or removal) | the true fact, or `"delete"` |
+| `Q-CLAR-n` | Something to ask the CLIENT | what you asked them and when |
+
+Then run:
+
+```bash
+npx tor-to-proposal bid-pack apply --answers answers.json --dir .
+```
+
+`apply` re-prints the questionnaire — repeat until it says **0 open
+questions**, then run `bid-pack pack`.
+
+---
+
 ## 7. If something goes wrong
 
 | What you see | What it means | What to do |
@@ -222,6 +298,9 @@ you will ever own.
 - **Master CV** — your full, real CV. The tailored one is derived from it and
   verified against it.
 - **`[FILL]`** — a yellow flag meaning "a real fact goes here — yours".
+- **`out/preview/`** — readable PDF copies of the bid screen, the questions
+  and the CV reports, regenerated after every `start` and `apply`. Double-click
+  to read them; the `.md` originals are the working files the tool edits.
 - **Floor rate** — the lowest daily rate that still pays your bills. Below it,
   you're paying the client.
 - **MCP / skill / plugin** — three plumbing formats for connecting the tool to

package/mcp/server.mjs

@@ -322,7 +322,7 @@ function handle(msg) {
     return {
       protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'tor-to-proposal', version: '2.0.1' },
+      serverInfo: { name: 'tor-to-proposal', version: '2.1.0' },
     };
   }
   if (typeof method === 'string' && method.startsWith('notifications/')) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tor-to-proposal",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "The bid tool that refuses to lie. ToR + CV in -> verified bid pack out: cover letter, tailored CV, technical response, financial proposal, submission checklist. Deterministic CLI + agent skill for UN / NGO / government consultants.",
   "type": "module",
   "bin": {